@babav/knowledge-core-client 0.30.0 → 0.31.0

package/dist/index.d.ts

@@ -95,7 +95,15 @@ export interface QueryRequest {
  * registers). */
 export type VisualLayout = "linear-flow" | "ring-cycle" | "nesting" | "radial-hub" | "side-by-side" | "stacked-layers" | "two-state" | "free";
 /** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
- * system as citations). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
+ * system as citations).
+ *
+ * UNIFORM DELIVERY: every register (chart / structural / conceptual / scenic) carries `image` — a
+ * PNG served BY KC. To display it, GET `image.url` (resolve a relative path against your KC base
+ * URL) with your normal API key; the response body is the PNG bytes. The URL is a stable, non-
+ * expiring KC endpoint for persisted/conversational visuals (`expires_at` absent), so it works on
+ * reload/copy/export and on later conversation retrieval — the client never fetches GCS and never
+ * parses inline SVG. `rendered_svg` appears ONLY as a rare fail-soft fallback (server rasterization
+ * failed); prefer `image` and treat `rendered_svg` as a last resort. */
 export interface Visual {
     id: string;
     anchor: {
@@ -107,13 +115,15 @@ export interface Visual {
     payload: Record<string, unknown>;
     /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
     layout: VisualLayout;
-    rendered_svg?: string;
+    /** PRIMARY: GET this (relative to your KC base, with your API key) -> PNG bytes. */
     image?: {
         url: string;
-        expires_at: number;
         width: number;
         height: number;
+        expires_at?: number;
     };
+    /** Fail-soft fallback only (rasterize/store failed); normally absent. */
+    rendered_svg?: string;
 }
 /** Visual stage (streaming): generation has started. MAY be emitted twice — first with
  *  `pending: null` (started, count unknown), then again with the ACCURATE post-vet count before

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "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

@@ -129,7 +129,15 @@ export type VisualLayout =
   | "free";
 
 /** A visual attached to a response, anchored by char offsets into `answer` (SAME coordinate
- * system as citations). For delivery="svg", `rendered_svg` is set; scenic sets `image`. */
+ * system as citations).
+ *
+ * UNIFORM DELIVERY: every register (chart / structural / conceptual / scenic) carries `image` — a
+ * PNG served BY KC. To display it, GET `image.url` (resolve a relative path against your KC base
+ * URL) with your normal API key; the response body is the PNG bytes. The URL is a stable, non-
+ * expiring KC endpoint for persisted/conversational visuals (`expires_at` absent), so it works on
+ * reload/copy/export and on later conversation retrieval — the client never fetches GCS and never
+ * parses inline SVG. `rendered_svg` appears ONLY as a rare fail-soft fallback (server rasterization
+ * failed); prefer `image` and treat `rendered_svg` as a last resort. */
 export interface Visual {
   id: string;
   anchor: { start: number; end: number };
@@ -138,8 +146,10 @@ export interface Visual {
   payload: Record<string, unknown>; // {kind: "grammar"|"vega_lite"|"svg"|"image", ...}
   /** Declared spatial arrangement (meaningful for `conceptual`; "free" otherwise). */
   layout: VisualLayout;
+  /** PRIMARY: GET this (relative to your KC base, with your API key) -> PNG bytes. */
+  image?: { url: string; width: number; height: number; expires_at?: number };
+  /** Fail-soft fallback only (rasterize/store failed); normally absent. */
   rendered_svg?: string;
-  image?: { url: string; expires_at: number; width: number; height: number };
 }
 
 /** Visual stage (streaming): generation has started. MAY be emitted twice — first with