@cms.ai/brand_brain 0.0.1 → 0.1.0

package/dist/react/index.d.cts

@@ -1,5 +1,9 @@
 //#region src/types.d.ts
-/** The `name` on `CUSTOM` guide events (skill payloads). */
+/**
+ * The `name` on `CUSTOM` guide events (skill payloads). `SkillGate` and
+ * `SkillError` never surface as `skill` stream events — the SDK re-maps them to
+ * the dedicated `gate` / `error` {@link GuideStreamEvent} variants.
+ */
 declare const GuideEvent: {
   readonly SkillStart: "skill_start";
   readonly SkillContent: "skill_content";
@@ -20,9 +24,7 @@ declare const GuideEvent: {
   readonly SkillEnd: "skill_end";
   readonly SkillError: "skill_error";
   readonly SkillGate: "skill_gate";
-  readonly InputSuggestions: "input_suggestions";
 };
-type GuideEventName = (typeof GuideEvent)[keyof typeof GuideEvent];
 /** The guide skill types. `answer` is always on; the rest are enabled per-guide. */
 declare const SkillResponseType: {
   readonly Answer: "answer";
@@ -74,9 +76,62 @@ interface GuideGraphSnapshot {
   }>;
 }
 /**
- * Resolved guide metadata returned by `guides.resolve`. `theme` / `skillIconStyle`
- * are left as `unknown` in v1 — read them defensively or narrow as needed.
+ * The guide's brand theme — shadcn-style design tokens as CSS color strings
+ * (hex or `oklch(...)`). Every property is optional: absent tokens mean "keep
+ * your default". Map them onto your CSS variables / Tailwind theme so the
+ * guide UI matches the brand:
+ *
+ * ```css
+ * :root {
+ *   --primary: <theme.primary>;
+ *   --background: <theme.background>;
+ * }
+ * ```
  */
+interface BrandKitTheme {
+  /** Main brand color (buttons, focus rings) */
+  primary?: string;
+  /** Text on primary backgrounds */
+  primaryForeground?: string;
+  /** Secondary surface color */
+  secondary?: string;
+  /** Text on secondary surfaces */
+  secondaryForeground?: string;
+  /** Main page background */
+  background?: string;
+  /** Default body text */
+  foreground?: string;
+  /** Muted areas, borders, inputs */
+  muted?: string;
+  /** Muted/secondary text */
+  mutedForeground?: string;
+  /** Border color */
+  border?: string;
+  /** Input border color */
+  input?: string;
+  /** Focus ring color */
+  ring?: string;
+}
+/** How a brand kit colors the guide's skill icons. */
+declare const SkillIconColorMode: {
+  /** Keep the built-in per-skill colors. */readonly Default: "default"; /** Apply a single brand color to every skill icon. */
+  readonly Mono: "mono"; /** Pick a color per skill; skills left unset fall back to the default. */
+  readonly PerSkill: "per_skill";
+};
+/**
+ * Per-brand-kit skill icon color customization, discriminated on `mode`.
+ * Colors are CSS color strings (same format as {@link BrandKitTheme}).
+ */
+type SkillIconStyle = {
+  mode: typeof SkillIconColorMode.Default;
+} | {
+  mode: typeof SkillIconColorMode.Mono; /** Single color applied to every skill icon. */
+  monoColor: string;
+} | {
+  mode: typeof SkillIconColorMode.PerSkill; /** Color per skill; missing keys fall back to the default. */
+  colors: Partial<Record<SkillResponseTypeType, string>>;
+};
+/** Resolved guide metadata returned by `guides.resolve`. */
 interface ResolvedGuide {
   id: string;
   name: string;
@@ -89,8 +144,9 @@ interface ResolvedGuide {
   advancedSettings: {
     gatePdfDownload: boolean;
   };
-  theme: unknown;
-  skillIconStyle: unknown;
+  /** Brand design tokens — apply to your UI so the guide matches the brand. */
+  theme: BrandKitTheme | null;
+  skillIconStyle: SkillIconStyle | null;
   faviconUrl: string | null;
   logoUrl: string | null;
   heroImageUrl: string | null;
@@ -124,7 +180,12 @@ interface ConversationWithMessages {
   conversation: Conversation;
   messages: ConversationMessage[];
 }
-/** A persisted skill deliverable. `data` shape varies by `type`. */
+/**
+ * A persisted skill deliverable. `data` shape varies by `type` — it is the
+ * skill's completed output (e.g. for `howto` a `{ title, steps: HowToStep[] }`
+ * record); the streamed payload interfaces in this file describe the same
+ * building blocks.
+ */
 interface SkillInstance {
   id: string;
   skillOutputId: string;
@@ -218,8 +279,10 @@ interface InitGuideConfig {
   /** Guide slug to resolve (e.g. "default"). */
   slug: string;
   /**
-   * Host domain used for account resolution + attribution. Defaults to
-   * `window.location.hostname`. Required when running without a browser window.
+   * Optional override for the host used in account resolution + attribution.
+   * Defaults to the `baseUrl` hostname (lowercased, `www.`/port stripped), which
+   * is the registered account domain. Only set this if resolution must key off a
+   * different registered domain than the one requests are sent to.
    */
   domain?: string;
   /**
@@ -250,10 +313,414 @@ interface AskOptions {
   /** Abort the in-flight stream. */
   signal?: AbortSignal;
 }
+/** Kind of content a document/playlist item points at. */
+declare const ContentType: {
+  readonly PDF: "pdf";
+  readonly DOCX: "docx";
+  readonly PPTX: "pptx";
+  readonly Image: "image";
+  readonly VideoNative: "video_native";
+  readonly VideoYouTube: "video_youtube";
+  readonly VideoWistia: "video_wistia";
+  readonly Document: "document";
+  readonly URL: "url";
+  readonly Text: "text";
+  readonly Markdown: "markdown";
+};
+type ContentTypeName = (typeof ContentType)[keyof typeof ContentType];
+/**
+ * Document reference streamed with a reply — the sources behind the answer.
+ * Render as source cards/citations: title, optional link, optional thumbnail.
+ */
+interface GuideDocument {
+  id: string;
+  title: string;
+  tag?: string;
+  /** Lucide icon name. */
+  icon?: string;
+  url?: string;
+  contentType?: ContentTypeName;
+  body?: string;
+  thumbnailUrl?: string;
+  /** 1-based citation number matching the [N] references in the reply text. Undefined if the document was not part of the reply context. */
+  citationIndex?: number;
+}
+/** Confidence level attached to a content recommendation. */
+declare const Confidence: {
+  readonly High: "high";
+  readonly Medium: "medium";
+  readonly Low: "low";
+};
+type ConfidenceName = (typeof Confidence)[keyof typeof Confidence];
+/**
+ * Follow-up recommendation to invoke a skill — render as a pill button that
+ * calls `ask(prompt, { forcedSkill: skill })`.
+ */
+interface SkillRecommendation {
+  id: string;
+  skill: SkillResponseTypeType;
+  label: string;
+  prompt: string;
+}
+/**
+ * A content recommendation generated by the recommend skill — render as a card
+ * whose click calls `ask(prompt, { forcedSkill: targetSkill })`.
+ */
+interface ContentRecommendation {
+  id: string;
+  targetSkill: Exclude<SkillResponseTypeType, "recommend">;
+  title: string;
+  rationale: string;
+  prompt: string;
+  confidence: ConfidenceName;
+}
+/** The render kind of a surfaced call-to-action. */
+declare const SkillCtaKind: {
+  readonly Url: "url";
+  readonly Form: "form";
+  readonly Product: "product";
+  readonly Scheduler: "scheduler";
+};
+/** Where a surfaced CTA renders. One slot today: below the skill response. */
+declare const CtaPlacement: {
+  readonly ResponseFooter: "response_footer";
+};
+type CtaPlacementName = (typeof CtaPlacement)[keyof typeof CtaPlacement];
+/** Which scheduler embed a scheduler CTA loads. */
+declare const SchedulerProvider: {
+  readonly HubSpot: "hubspot";
+  readonly Calendly: "calendly";
+};
+type SchedulerProviderName = (typeof SchedulerProvider)[keyof typeof SchedulerProvider];
+/**
+ * A call-to-action surfaced for a turn, discriminated on `kind`:
+ * - `url`:       external link — render a button that opens `href`.
+ * - `form`:      in-guide form — render a button/banner for the form `formId`.
+ * - `product`:   product recommendation — render a link/card to `href`.
+ * - `scheduler`: meeting embed — render a button that opens `url` in the
+ *                provider's scheduling widget (or a new tab).
+ *
+ * Only render the first CTA in the list; the wire carries a list for forward
+ * compatibility. `ctaInstanceId` (when present) should be echoed on CTA
+ * analytics events so impressions and clicks join up.
+ */
+type SkillCTA = {
+  kind: typeof SkillCtaKind.Url;
+  placement: CtaPlacementName;
+  ctaId: string | null;
+  label: string;
+  href: string; /** Custom banner heading; absent → use a default like "Recommended next step". */
+  bannerText?: string; /** Lucide icon name; absent → a default lightbulb. */
+  bannerIcon?: string;
+  ctaInstanceId?: string;
+} | {
+  kind: typeof SkillCtaKind.Form;
+  placement: CtaPlacementName;
+  ctaId: string;
+  label: string;
+  formId: string;
+  bannerText?: string;
+  bannerIcon?: string;
+  ctaInstanceId?: string;
+} | {
+  kind: typeof SkillCtaKind.Product;
+  placement: CtaPlacementName;
+  productId: string;
+  label: string;
+  href: string;
+  ctaInstanceId?: string;
+} | {
+  kind: typeof SkillCtaKind.Scheduler;
+  placement: CtaPlacementName;
+  ctaId: string;
+  label: string;
+  provider: SchedulerProviderName; /** The meeting/scheduling link the embed loads. */
+  url: string;
+  bannerText?: string;
+  bannerIcon?: string;
+  ctaInstanceId?: string;
+};
+/** Diagnose skill mode. */
+declare const DiagnoseSubtype: {
+  /** A scored self-assessment rendered with results at the end. */readonly Standalone: "standalone"; /** Questions gather context for a follow-up skill (see `followUpSkill`). */
+  readonly ContextGathering: "context_gathering";
+};
+type DiagnoseSubtypeName = (typeof DiagnoseSubtype)[keyof typeof DiagnoseSubtype];
+/** Answer option labels for diagnose questions. */
+declare const DiagnoseOptionLabel: {
+  readonly A: "A";
+  readonly B: "B";
+  readonly C: "C";
+  readonly D: "D";
+};
+type DiagnoseOptionLabelName = (typeof DiagnoseOptionLabel)[keyof typeof DiagnoseOptionLabel];
+/** Header for a diagnostic assessment — render as the assessment intro. */
+interface DiagnosticHeader {
+  targetTopic: string;
+  subtitle: string;
+  /** Total number of questions the assessment will stream. */
+  questionCount: number;
+  subtype?: DiagnoseSubtypeName;
+  /** For context_gathering mode — the skill to invoke after the user submits answers. */
+  followUpSkill?: string;
+  /** For context_gathering mode — the prompt to send to `followUpSkill` afterwards. */
+  followUpPrompt?: string;
+}
+/**
+ * A self-assessment question (no correct answer). Render the options as a
+ * single-choice list; `score` supports a results chart in standalone mode.
+ */
+interface DiagnosticQuestion {
+  id: string;
+  /** Short category name, usable as a results-chart axis label. */
+  category: string;
+  questionText: string;
+  options: Array<{
+    label: DiagnoseOptionLabelName;
+    text: string;
+    score?: number;
+  }>;
+  prerequisiteConceptId: string | null;
+  prerequisiteConceptName: string | null;
+}
+/** A step title in a how-to outline (details stream later as {@link HowToStep}). */
+interface HowToStepOutline {
+  id: string;
+  title: string;
+}
+/** How-to outline — render immediately as a skeleton; steps fill in after. */
+interface HowToOutline {
+  title: string;
+  steps: HowToStepOutline[];
+}
+/** Content reference attached to a how-to step — render as a source card. */
+interface HowToStepContent {
+  contentId: string;
+  title: string;
+  url: string | null;
+  contentType: ContentTypeName | null;
+  /** The matching excerpt that demonstrates relevance. */
+  excerpt: string;
+  thumbnailUrl?: string;
+}
+/** A fully detailed how-to step — replaces the outline entry with the same `id`. */
+interface HowToStep {
+  id: string;
+  title: string;
+  description: string;
+  content: HowToStepContent | null;
+  /** Lucide icon name. */
+  icon?: string;
+}
+/** Header for a playlist — render as the playlist title/description. */
+interface PlaylistHeader {
+  title: string;
+  description: string;
+}
+/** A single item in a curated playlist — render as a content card. */
+interface PlaylistItem {
+  id: string;
+  title: string;
+  description: string | null;
+  body?: string | null;
+  contentType: ContentTypeName;
+  url: string | null;
+  thumbnailUrl?: string;
+  /** Why this item is included — streams in later via `skill_playlist_rationale`. */
+  rationale?: string;
+}
+/** Business case format sub-types. */
+declare const BusinessCaseSubType: {
+  readonly RoiAnalysis: "roi-analysis";
+  readonly StakeholderBrief: "stakeholder-brief";
+  readonly VendorComparison: "vendor-comparison";
+};
+type BusinessCaseSubTypeName = (typeof BusinessCaseSubType)[keyof typeof BusinessCaseSubType];
+/** Format option in the business case chooser — render as a selectable card. */
+interface BusinessCaseFormatOption {
+  subType: BusinessCaseSubTypeName;
+  label: string;
+  description: string;
+  /** Lucide icon name. */
+  icon: string;
+}
+/** Reference to a pre-generated business case draft, keyed by sub-type. */
+interface BusinessCaseDraftRef {
+  draftId: string;
+  skillInstanceId: string;
+}
+/** Node types in a solution design diagram. */
+declare const SolutionDesignNodeType: {
+  readonly Process: "process";
+  readonly Decision: "decision";
+  readonly Datastore: "datastore";
+  readonly External: "external";
+  readonly Trigger: "trigger";
+  readonly Start: "start";
+  readonly End: "end";
+};
+type SolutionDesignNodeTypeName = (typeof SolutionDesignNodeType)[keyof typeof SolutionDesignNodeType];
+/** A node in a solution design diagram — render as a flowchart node. */
+interface SolutionDesignNode {
+  id: string;
+  label: string;
+  description: string;
+  nodeType: SolutionDesignNodeTypeName;
+  /** Lucide icon name. */
+  icon: string;
+}
+/** A directed edge between two solution design nodes (by node `id`). */
+interface SolutionDesignEdge {
+  id: string;
+  source: string;
+  target: string;
+  label?: string;
+}
+/** Header for a solution design — render as the diagram title/summary. */
+interface SolutionDesignHeader {
+  title: string;
+  summary: string;
+}
+/** Suggested retry attached to a recoverable skill error. */
+interface SkillErrorRetryHint {
+  /** Re-ask with this prompt… */
+  prompt: string;
+  /** …optionally forcing this skill. */
+  forcedSkill?: SkillResponseTypeType;
+}
 /**
- * A single event yielded by {@link GuideClient.ask}. The common case is `text`
- * (the streamed chat reply); `skill` carries every structured skill payload,
- * discriminated by its {@link GuideEventName} `name`.
+ * A structured skill event, discriminated on `name`. Every turn runs one skill
+ * (plain answers are the `answer` skill): `skill_start` announces which,
+ * payload events stream the deliverable, and `skill_end` closes it. Use
+ * {@link reduceSkillEvent} to fold these into renderable state instead of
+ * handling each variant by hand.
+ */
+type GuideSkillEvent = {
+  type: "skill";
+  name: typeof GuideEvent.SkillStart; /** Which skill this turn runs, and the assistant message it belongs to. */
+  value: {
+    skill: SkillResponseTypeType;
+    messageId: string;
+    diagnoseSubtype?: DiagnoseSubtypeName;
+    followUpSkill?: string;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillContent; /** Markdown token chunk of the skill's long-form body (business case drafts, etc.). */
+  value: {
+    delta: string;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillDocuments; /** Source documents behind the reply — render as citation/source cards. */
+  value: {
+    documents: GuideDocument[];
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillRecommendations;
+  /**
+   * Either the recommend skill's content cards ({@link ContentRecommendation},
+   * has `targetSkill`) or post-answer follow-up pills ({@link SkillRecommendation},
+   * has `skill`). Discriminate by which of those keys is present.
+   */
+  value: {
+    recommendations: ContentRecommendation[] | SkillRecommendation[];
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillCTAs; /** Calls-to-action for this turn — render the first below the response. */
+  value: {
+    ctas: SkillCTA[];
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillDiagnoseHeader;
+  value: {
+    header: DiagnosticHeader;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillDiagnoseQuestion;
+  value: {
+    question: DiagnosticQuestion;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillPlaylistItems;
+  value: {
+    items: PlaylistItem[];
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillPlaylistHeader;
+  value: {
+    header: PlaylistHeader;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillPlaylistRationale; /** Late-streamed rationale for the playlist item with this `itemId`. */
+  value: {
+    itemId: string;
+    rationale: string;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillHowToOutline; /** Render the outline immediately; detailed steps stream in `skill_howto_steps`. */
+  value: {
+    outline: HowToOutline;
+    skillInstanceId?: string;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillHowToSteps;
+  value: {
+    steps: HowToStep[];
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillBusinessCaseChooser; /** Format options to choose from; `drafts` maps subType → pre-generated draft. */
+  value: {
+    formats: BusinessCaseFormatOption[];
+    drafts: Record<string, BusinessCaseDraftRef>;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillBusinessCaseDelta; /** Markdown chunk of the draft for one business case format. */
+  value: {
+    subType: BusinessCaseSubTypeName;
+    delta: string;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillSolutionDesignHeader;
+  value: {
+    header: SolutionDesignHeader;
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillSolutionDesignDiagram; /** Flowchart nodes + edges — render with any diagram/graph component. */
+  value: {
+    nodes: SolutionDesignNode[];
+    edges: SolutionDesignEdge[];
+  };
+} | {
+  type: "skill";
+  name: typeof GuideEvent.SkillEnd; /** `skillInstanceId` is the persisted deliverable's id (for `skills.get`/`update`). */
+  value: {
+    skillInstanceId?: string;
+    skillResponseId?: string;
+  };
+};
+/**
+ * A single event yielded by {@link GuideClient.ask}.
+ *
+ * - `text` streams the chat reply; `skill` carries the structured deliverable
+ *   (see {@link GuideSkillEvent}).
+ * - `gate` means the guide wants an email before continuing — collect one,
+ *   call `submitGate(email)`, then re-send the message.
+ * - `skill-unknown` is a forward-compatibility escape hatch: a structured
+ *   event this SDK version doesn't know. Safe to ignore.
  */
 type GuideStreamEvent = {
   type: "run-started";
@@ -269,9 +736,9 @@ type GuideStreamEvent = {
 } | {
   type: "message-end";
   messageId: string;
-} | {
-  type: "skill";
-  name: GuideEventName;
+} | GuideSkillEvent | {
+  type: "skill-unknown";
+  name: string;
   value: Record<string, unknown>;
 } | {
   type: "gate";
@@ -282,6 +749,8 @@ type GuideStreamEvent = {
   type: "error";
   message: string;
   code?: string;
+  retryable?: boolean;
+  retryHint?: SkillErrorRetryHint;
 } | {
   type: "run-finished";
   finishReason?: string;
@@ -305,6 +774,11 @@ interface SkillsApi {
   markShared(skillInstanceId: string): Promise<MarkSharedResult>;
   importShared(sourceSkillInstanceId: string): Promise<ImportSharedResult>;
 }
+/**
+ * Normalize `baseUrl` to the bare host the server stores: lowercased, no port,
+ * no leading `www.` (the domain write-path strips it, so a `www.` host can
+ * never match). Accepts a bare host too, in case `baseUrl` omits the protocol.
+ */
 /**
  * The client returned by {@link initGuide}. Holds the resolved guide, the
  * credentialed live API client, and the in-memory conversation history. Every
@@ -357,7 +831,74 @@ declare class GuideClient {
   private applyInitialConsent;
 }
 //#endregion
+//#region src/skill-state.d.ts
+/**
+ * Renderable state for one skill turn, folded from the `skill` events of a
+ * single {@link GuideClient.ask} stream. Which fields fill in depends on
+ * `skill`; everything else stays at its empty default:
+ *
+ * - `answer`:         `documents`, `followUpRecommendations`, `ctas`
+ * - `recommend`:      `contentRecommendations`, `ctas`
+ * - `diagnose`:       `diagnoseHeader`, `diagnoseQuestions`
+ * - `playlist`:       `playlistHeader`, `playlistItems`
+ * - `howto`:          `howToOutline` (render first), then `howToSteps`
+ * - `businesscase`:   `businessCaseFormats`/`businessCaseDrafts` (chooser), then
+ *                     `businessCaseContent[subType]` markdown as a format streams
+ * - `solutiondesign`: `solutionDesignHeader`, `solutionDesignNodes`/`Edges`
+ */
+interface GuideSkillTurn {
+  /** Which skill this turn ran. Null until `skill_start` arrives. */
+  skill: SkillResponseTypeType | null;
+  /** `streaming` until `skill_end`. */
+  status: "streaming" | "complete";
+  /** The assistant message this skill output belongs to. */
+  messageId: string | null;
+  /** Diagnose mode — `context_gathering` runs `followUpSkill` after answers are submitted. */
+  diagnoseSubtype: DiagnoseSubtypeName | null;
+  followUpSkill: string | null;
+  /** Accumulated long-form markdown body (`skill_content` deltas). */
+  content: string;
+  /** Source documents behind the reply — render as citation/source cards. */
+  documents: GuideDocument[];
+  /** The recommend skill's content cards. */
+  contentRecommendations: ContentRecommendation[];
+  /** Post-answer follow-up pills — `ask(prompt, { forcedSkill: skill })` on click. */
+  followUpRecommendations: SkillRecommendation[];
+  /** Calls-to-action — render the first below the response. */
+  ctas: SkillCTA[];
+  diagnoseHeader: DiagnosticHeader | null;
+  diagnoseQuestions: DiagnosticQuestion[];
+  playlistHeader: PlaylistHeader | null;
+  playlistItems: PlaylistItem[];
+  howToOutline: HowToOutline | null;
+  howToSteps: HowToStep[];
+  businessCaseFormats: BusinessCaseFormatOption[];
+  businessCaseDrafts: Record<string, BusinessCaseDraftRef>;
+  /** Accumulated draft markdown per business case subType. */
+  businessCaseContent: Record<string, string>;
+  solutionDesignHeader: SolutionDesignHeader | null;
+  solutionDesignNodes: SolutionDesignNode[];
+  solutionDesignEdges: SolutionDesignEdge[];
+  /** Persisted deliverable id (for `client.skills.get`/`update`), set on `skill_end`. */
+  skillInstanceId: string | null;
+}
+//#endregion
 //#region src/react/useGuide.d.ts
+interface UseGuideConfig extends InitGuideConfig {
+  /**
+   * Called with every raw stream event, in order — the escape hatch for
+   * anything the hook's derived state doesn't cover.
+   */
+  onEvent?: (event: GuideStreamEvent) => void;
+}
+/** A pending email gate — the guide wants an email before finishing the turn. */
+interface GateRequest {
+  /** The skill that was gated. */
+  skill: SkillResponseTypeType;
+  /** The visitor prompt that triggered the gate (re-sent after unlocking). */
+  prompt?: string;
+  skillInstanceId?: string;
+}
 interface UseGuideResult {
   /** The client once bootstrapped, else `null`. */
   client: GuideClient | null;
@@ -365,23 +906,41 @@ interface UseGuideResult {
   guide: ResolvedGuide | null;
   /** Conversation history, kept in sync with the client. */
   messages: ChatMessage[];
+  /**
+   * Structured deliverable of the current / most recent turn (documents,
+   * recommendations, CTAs, how-to steps, …). `null` before the first ask.
+   */
+  skillTurn: GuideSkillTurn | null;
+  /**
+   * Set when the guide asks for an email mid-turn. Render an email form, call
+   * `submitGate(email)`, then `retryLastAsk()` to finish the interrupted turn.
+   */
+  gate: GateRequest | null;
   /** `true` once the client has finished initializing. */
   isReady: boolean;
   /** `true` while a reply is streaming. */
   isStreaming: boolean;
   /** Init or stream error, else `null`. */
   error: Error | null;
-  /** Send a message and stream the reply into `messages`. */
+  /** Send a message and stream the reply into `messages` / `skillTurn`. */
   ask: (message: string, options?: AskOptions) => Promise<void>;
+  /**
+   * Submit the visitor's email — for the pending `gate` (its context is merged
+   * in automatically) or as general lead capture. Clears `gate` on success.
+   */
+  submitGate: (email: string, options?: SubmitGateOptions) => Promise<SubmitGateResult>;
+  /** Re-send the last user message, e.g. to finish a gated turn after `submitGate`. */
+  retryLastAsk: () => Promise<void>;
   /** Clear the in-memory conversation. */
   reset: () => void;
 }
 /**
  * React binding over {@link initGuide}. Bootstraps once per `baseUrl`+`slug`,
- * mirrors the streamed reply into state, and ends the session on unmount —
+ * mirrors the streamed reply into `messages`, folds structured skill events
+ * into `skillTurn`, surfaces email gates, and ends the session on unmount —
  * encapsulating the streaming/cleanup patterns so generated UIs stay correct.
  */
-declare function useGuide(config: InitGuideConfig): UseGuideResult;
+declare function useGuide(config: UseGuideConfig): UseGuideResult;
 //#endregion
-export { type UseGuideResult, useGuide };
+export { type GateRequest, type UseGuideConfig, type UseGuideResult, useGuide };
 //# sourceMappingURL=index.d.cts.map