@stigmer/react 3.12.0 → 3.12.2

package/src/attachment/vision-preflight.ts

@@ -0,0 +1,236 @@
+/**
+ * Client-side vision preflight — predicts, before a turn is spent, which
+ * attached images the runner will refuse to deliver inline and why
+ * (stigmer/stigmer#365, stigmer/stigmer#386).
+ *
+ * The runner is the enforcement authority (`VisionBudget` in its
+ * `shared/attachment-vision.ts`); this module is the warning authority.
+ * To never warn differently than the runner behaves, it replicates the
+ * runner's admission semantics against the SAME data the runner uses:
+ *
+ * - the byte budget arrives via the registry document's `limits.vision`
+ *   block ({@link VisionLimits}) — advertised == enforced;
+ * - the model's vision capability arrives via the per-model
+ *   `capabilities` block ({@link ModelInfo.visionCapability});
+ * - reasons reuse the runner's disclosure vocabulary
+ *   (`VisionDegradedReason`), so a warning here and a disclosure in the
+ *   agent's reply always tell one story.
+ *
+ * Tri-state discipline: absent limits or an unassessed model produce NO
+ * warnings. A client that cannot know the budget must stay silent, not
+ * guess — the runner's own disclosure remains the backstop.
+ *
+ * Deliberately assessed client-side reasons are a SUBSET of the runner's:
+ * `unsupported_format` and `type_mismatch` need magic-byte sniffing that a
+ * declared content type cannot honestly stand in for (and pasted images are
+ * already normalized by `prepareImageForVision`), so those two remain
+ * runner-disclosed only.
+ */
+
+import type { ModelInfo, VisionLimits } from "../models/registry.js";
+import { formatFileSize } from "./attachment-utils.js";
+
+/**
+ * Content types the runner recognizes as vision candidates (its
+ * `VisionMimeType` set). Anything else — PDFs, SVGs, archives — rides the
+ * normal file story with no inline-vision expectation and no warning.
+ */
+const VISION_CANDIDATE_TYPES: ReadonlySet<string> = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+]);
+
+/** Minimal attachment shape the preflight needs — pure data, no `File`. */
+export interface VisionPreflightAttachment {
+  /** Display name used in warning copy (the chip's filename). */
+  readonly name: string;
+  /** Raw byte size — what the runner's budget counts. */
+  readonly sizeBytes: number;
+  /** Declared/detected MIME type (`AttachmentEntry.contentType`). */
+  readonly contentType: string;
+}
+
+/**
+ * Why an image will not be viewable inline — the client-assessable subset
+ * of the runner's `VisionDegradedReason` vocabulary, same spellings.
+ */
+export type VisionPreflightReason =
+  /** Raw bytes exceed the per-image cap; a smaller re-export would fix it. */
+  | "too_large"
+  /** Image is fine but the turn's total/count budget is already spent. */
+  | "budget_exhausted"
+  /** The selected model is explicitly assessed as unable to see images. */
+  | "model_no_vision";
+
+/** One image the runner is predicted to degrade, and why. */
+export interface VisionPreflightWarning {
+  readonly name: string;
+  readonly sizeBytes: number;
+  readonly reason: VisionPreflightReason;
+}
+
+/** Result of {@link assessVisionPreflight}. */
+export interface VisionPreflight {
+  /** Predicted-degraded images in attachment order. Empty = all clear. */
+  readonly warnings: readonly VisionPreflightWarning[];
+  /**
+   * True when the selected model is explicitly blind (`vision: false`)
+   * and at least one image is attached. When set, every image warning
+   * carries `model_no_vision` — resending smaller images cannot help, so
+   * warning UI should lead with the model, not the files.
+   */
+  readonly modelCannotSeeImages: boolean;
+}
+
+const NO_WARNINGS: VisionPreflight = { warnings: [], modelCannotSeeImages: false };
+
+/** Options for {@link assessVisionPreflight}. */
+export interface AssessVisionPreflightOptions {
+  /**
+   * The model the turn will run on. `undefined` (unknown/still loading)
+   * disables the capability verdict, never the byte assessment.
+   */
+  readonly model?: ModelInfo | undefined;
+  /**
+   * The advertised byte budget from `useModelRegistry().visionLimits`.
+   * `undefined` (older server, still loading) disables the byte
+   * assessment, never the capability verdict.
+   */
+  readonly limits?: VisionLimits | undefined;
+}
+
+/**
+ * Predict which attached images the runner will degrade this turn.
+ *
+ * Pure and deterministic — safe to call in render (memoized by callers).
+ * Non-image attachments never warn. The byte assessment replicates the
+ * runner's sequential admission: an image over the per-image cap is
+ * degraded WITHOUT consuming budget; remaining images are admitted in
+ * order until the count or total-byte budget is exhausted.
+ */
+export function assessVisionPreflight(
+  attachments: readonly VisionPreflightAttachment[],
+  options?: AssessVisionPreflightOptions,
+): VisionPreflight {
+  const candidates = attachments.filter((a) =>
+    VISION_CANDIDATE_TYPES.has(a.contentType.toLowerCase()),
+  );
+  if (candidates.length === 0) return NO_WARNINGS;
+
+  // The capability gate short-circuits the byte math: on an explicitly
+  // blind model no image is deliverable at any size, and mixing byte
+  // warnings in would wrongly suggest a smaller resend could help.
+  if (options?.model?.visionCapability === false) {
+    return {
+      warnings: candidates.map((a) => ({
+        name: a.name,
+        sizeBytes: a.sizeBytes,
+        reason: "model_no_vision",
+      })),
+      modelCannotSeeImages: true,
+    };
+  }
+
+  const limits = options?.limits;
+  if (!limits) return NO_WARNINGS;
+
+  const warnings: VisionPreflightWarning[] = [];
+  let acceptedCount = 0;
+  let acceptedBytes = 0;
+
+  for (const image of candidates) {
+    if (image.sizeBytes > limits.maxImageBytes) {
+      warnings.push({ name: image.name, sizeBytes: image.sizeBytes, reason: "too_large" });
+      continue;
+    }
+    if (
+      acceptedCount >= limits.maxImages ||
+      acceptedBytes + image.sizeBytes > limits.maxTotalBytes
+    ) {
+      warnings.push({
+        name: image.name,
+        sizeBytes: image.sizeBytes,
+        reason: "budget_exhausted",
+      });
+      continue;
+    }
+    acceptedCount += 1;
+    acceptedBytes += image.sizeBytes;
+  }
+
+  return warnings.length === 0
+    ? NO_WARNINGS
+    : { warnings, modelCannotSeeImages: false };
+}
+
+/** Options for {@link visionPreflightMessage}. */
+export interface VisionPreflightMessageOptions {
+  /** The advertised budget — names the caps in the copy when present. */
+  readonly limits?: VisionLimits | undefined;
+  /** Display name of the selected model, for the capability wording. */
+  readonly modelDisplayName?: string | undefined;
+}
+
+/**
+ * One-line human copy for a {@link VisionPreflight} — the client-side twin
+ * of the runner's `visionDisclosureLines`, worded for BEFORE the turn
+ * ("will arrive as a file") instead of after ("was not viewable").
+ *
+ * Returns `null` when there is nothing to warn about. Copy rules:
+ * - a blind model leads with the model, never the files — no smaller
+ *   resend can help, so file-size advice would be dishonest;
+ * - `too_large` names the files (up to two, then a count) and the actual
+ *   cap, so the fix — export smaller — is self-evident;
+ * - `budget_exhausted` explains the per-turn budget, the only fix being
+ *   fewer images this turn.
+ */
+export function visionPreflightMessage(
+  preflight: VisionPreflight,
+  options?: VisionPreflightMessageOptions,
+): string | null {
+  if (preflight.warnings.length === 0) return null;
+
+  if (preflight.modelCannotSeeImages) {
+    const model = options?.modelDisplayName ?? "The selected model";
+    return `${model} can't view images — attached images will reach the agent as files only.`;
+  }
+
+  const tooLarge = preflight.warnings.filter((w) => w.reason === "too_large");
+  const exhausted = preflight.warnings.filter((w) => w.reason === "budget_exhausted");
+  const parts: string[] = [];
+
+  if (tooLarge.length > 0) {
+    const capPhrase = options?.limits
+      ? `the ${formatFileSize(options.limits.maxImageBytes)} inline-image limit`
+      : "the inline-image size limit";
+    if (tooLarge.length === 1) {
+      const w = tooLarge[0];
+      parts.push(
+        `${w.name} (${formatFileSize(w.sizeBytes)}) exceeds ${capPhrase} and will reach the agent as a file, not an image`,
+      );
+    } else if (tooLarge.length === 2) {
+      parts.push(
+        `${tooLarge[0].name} and ${tooLarge[1].name} exceed ${capPhrase} and will reach the agent as files, not images`,
+      );
+    } else {
+      parts.push(
+        `${tooLarge.length} images exceed ${capPhrase} and will reach the agent as files, not images`,
+      );
+    }
+  }
+
+  if (exhausted.length > 0) {
+    const budget = options?.limits
+      ? `this turn's inline-image budget (${options.limits.maxImages} images, ${formatFileSize(options.limits.maxTotalBytes)} total)`
+      : "this turn's inline-image budget";
+    parts.push(
+      exhausted.length === 1
+        ? `${exhausted[0].name} is over ${budget} and will reach the agent as a file`
+        : `${exhausted.length} images are over ${budget} and will reach the agent as files`,
+    );
+  }
+
+  return parts.length === 0 ? null : `${parts.join("; ")}.`;
+}

package/src/billing/AutoRechargeCard.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useCallback, useEffect } from "react";
+import { useState, useCallback, useEffect, useId } from "react";
 import { cn } from "@stigmer/theme";
 import type { AutoRechargeConfig } from "@stigmer/protos/ai/stigmer/billing/v1/billing_account_pb";
 import { BillingAccountStatus } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
@@ -64,6 +64,7 @@ export function AutoRechargeCard({
   onSaved,
   className,
 }: AutoRechargeCardProps) {
+  const baseId = useId();
   const { setConfig, isSubmitting, error, clearError } =
     useSetAutoRechargeConfig();
 
@@ -168,7 +169,7 @@ export function AutoRechargeCard({
       {canConfigure && (
         <div className="stg:mt-4 stg:space-y-3">
           <DollarInput
-            id="ar-threshold"
+            id={`${baseId}-threshold`}
             label="When balance drops below"
             value={threshold}
             onChange={setThreshold}
@@ -176,7 +177,7 @@ export function AutoRechargeCard({
             placeholder="e.g. 5"
           />
           <DollarInput
-            id="ar-amount"
+            id={`${baseId}-amount`}
             label="Recharge amount"
             value={amount}
             onChange={setAmount}
@@ -184,7 +185,7 @@ export function AutoRechargeCard({
             placeholder="e.g. 50"
           />
           <DollarInput
-            id="ar-cap"
+            id={`${baseId}-cap`}
             label="Monthly cap"
             value={cap}
             onChange={setCap}

package/src/billing/BillingSection.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useCallback } from "react";
+import { useCallback, useId, useState } from "react";
 import { cn } from "@stigmer/theme";
 import { getUserMessage } from "@stigmer/sdk";
 import { BillingAccountStatus } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
@@ -53,14 +53,15 @@ export function BillingSection({
   onDismissCheckoutSuccess,
   className,
 }: BillingSectionProps) {
+  const headingId = useId();
   const { activeOrg } = useOrg();
   const mode = useDeploymentMode();
   const orgId = activeOrg?.metadata?.id ?? "";
 
   return (
-    <section aria-labelledby="billing-heading" className={className}>
+    <section aria-labelledby={headingId} className={className}>
       <h2
-        id="billing-heading"
+        id={headingId}
         className="stg:text-foreground stg:mb-1 stg:text-sm stg:font-semibold"
       >
         Billing

package/src/channel/ChannelConversationsDialog.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef } from "react";
+import { useCallback, useId, useRef } from "react";
 import { timestampDate } from "@bufbuild/protobuf/wkt";
 import { MessageSquare, User, X } from "lucide-react";
 import { cn } from "@stigmer/theme";
@@ -69,6 +69,7 @@ export function ChannelConversationsDialog({
   modal = true,
 }: ChannelConversationsDialogProps) {
   const dialogRef = useRef<HTMLDialogElement>(null);
+  const titleId = useId();
 
   const handleClose = useCallback(() => {
     dialogRef.current?.close();
@@ -97,13 +98,14 @@ export function ChannelConversationsDialog({
       onClose={handleClose}
       className={cn(
         "stg:w-full stg:max-w-lg stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-black/50" : "stg:relative",
+        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-backdrop" : "stg:relative",
       )}
-      aria-labelledby="channel-conversations-title"
+      aria-labelledby={titleId}
     >
       {/* Body mounts only while open so each opening fetches fresh. */}
       {open && (
         <ChannelConversationsDialogBody
+          titleId={titleId}
           channel={channel}
           sessionHref={sessionHref}
           onClose={handleClose}
@@ -114,10 +116,12 @@ export function ChannelConversationsDialog({
 }
 
 function ChannelConversationsDialogBody({
+  titleId,
   channel,
   sessionHref,
   onClose,
 }: {
+  readonly titleId: string;
   readonly channel: AgentChannel;
   readonly sessionHref?: (sessionId: string) => string;
   readonly onClose: () => void;
@@ -133,7 +137,7 @@ function ChannelConversationsDialogBody({
       <div className="stg:flex stg:items-start stg:justify-between stg:gap-3 stg:border-b stg:border-border stg:px-5 stg:py-4">
         <div className="stg:min-w-0">
           <h2
-            id="channel-conversations-title"
+            id={titleId}
             className="stg:text-sm stg:font-semibold stg:text-popover-foreground"
           >
             Sessions

package/src/channel/ChannelCredentialsDialog.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useId, useRef, useState } from "react";
 import { cn } from "@stigmer/theme";
 import { getUserMessage, type ResourceRef } from "@stigmer/sdk";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
@@ -53,6 +53,12 @@ export function ChannelCredentialsDialog({
 }: ChannelCredentialsDialogProps) {
   const dialogRef = useRef<HTMLDialogElement>(null);
 
+  // Instance-scoped title id (oss#593): a reusable component must not
+  // hardcode DOM ids — hosts legitimately mount this dialog more than once
+  // per page (e.g. zone-cached detail pages), and duplicate ids break the
+  // aria-labelledby association for every copy after the first.
+  const titleId = useId();
+
   const handleClose = useCallback(() => {
     dialogRef.current?.close();
     onOpenChange(false);
@@ -80,9 +86,9 @@ export function ChannelCredentialsDialog({
       onClose={handleClose}
       className={cn(
         "stg:w-full stg:max-w-md stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-black/50" : "stg:relative",
+        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-backdrop" : "stg:relative",
       )}
-      aria-labelledby="channel-credentials-title"
+      aria-labelledby={titleId}
     >
       {/* Body mounts only while open so its draft resets per session —
           reopening never resumes stale, unsaved edits. */}
@@ -92,6 +98,7 @@ export function ChannelCredentialsDialog({
           channel={channel}
           onSaved={onSaved}
           onClose={handleClose}
+          titleId={titleId}
         />
       )}
     </dialog>
@@ -103,11 +110,14 @@ function ChannelCredentialsDialogBody({
   channel,
   onSaved,
   onClose,
+  titleId,
 }: {
   readonly agent: Agent;
   readonly channel: AgentChannel;
   readonly onSaved?: () => void;
   readonly onClose: () => void;
+  /** Heading id minted by the outer dialog for its aria-labelledby. */
+  readonly titleId: string;
 }) {
   const channelName =
     channel.metadata?.name || channel.metadata?.slug || "this channel";
@@ -142,7 +152,7 @@ function ChannelCredentialsDialogBody({
       <div className="stg:flex stg:items-start stg:justify-between stg:gap-3 stg:border-b stg:border-border stg:px-5 stg:py-4">
         <div className="stg:min-w-0">
           <h2
-            id="channel-credentials-title"
+            id={titleId}
             className="stg:text-sm stg:font-semibold stg:text-foreground"
           >
             Tool credentials

package/src/channel/ChannelTemplatesDialog.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, type ReactNode } from "react";
+import { useCallback, useId, useRef, type ReactNode } from "react";
 import { ExternalLink, LayoutTemplate, X } from "lucide-react";
 import { cn } from "@stigmer/theme";
 import { getUserMessage } from "@stigmer/sdk";
@@ -90,6 +90,7 @@ export function ChannelTemplatesDialog({
   modal = true,
 }: ChannelTemplatesDialogProps) {
   const dialogRef = useRef<HTMLDialogElement>(null);
+  const titleId = useId();
 
   const handleClose = useCallback(() => {
     dialogRef.current?.close();
@@ -120,14 +121,15 @@ export function ChannelTemplatesDialog({
         // Wider than the conversations dialog on purpose: template
         // bodies are the content, and a narrow column shreds them.
         "stg:w-full stg:max-w-2xl stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-black/50" : "stg:relative",
+        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-backdrop" : "stg:relative",
       )}
-      aria-labelledby="channel-templates-title"
+      aria-labelledby={titleId}
     >
       {/* Body mounts only while open so each opening fetches fresh —
           approval statuses change on the provider's side at any time. */}
       {open && (
         <ChannelTemplatesDialogBody
+          titleId={titleId}
           channel={channel}
           onEditYaml={onEditYaml}
           onClose={handleClose}
@@ -138,10 +140,12 @@ export function ChannelTemplatesDialog({
 }
 
 function ChannelTemplatesDialogBody({
+  titleId,
   channel,
   onEditYaml,
   onClose,
 }: {
+  readonly titleId: string;
   readonly channel: AgentChannel;
   readonly onEditYaml?: () => void;
   readonly onClose: () => void;
@@ -154,7 +158,7 @@ function ChannelTemplatesDialogBody({
       <div className="stg:flex stg:items-start stg:justify-between stg:gap-3 stg:border-b stg:border-border stg:px-5 stg:py-4">
         <div className="stg:min-w-0">
           <h2
-            id="channel-templates-title"
+            id={titleId}
             className="stg:text-sm stg:font-semibold stg:text-popover-foreground"
           >
             Templates

package/src/channel/ConnectSlackDialog.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useId, useMemo, useRef, useState } from "react";
 import { cn } from "@stigmer/theme";
 import { getErrorReason, type ResourceRef } from "@stigmer/sdk";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
@@ -91,6 +91,12 @@ export function ConnectSlackDialog({
 }: ConnectSlackDialogProps) {
   const dialogRef = useRef<HTMLDialogElement>(null);
 
+  // Instance-scoped title id (oss#593): a reusable component must not
+  // hardcode DOM ids — hosts legitimately mount this dialog more than once
+  // per page (e.g. zone-cached detail pages), and duplicate ids break the
+  // aria-labelledby association for every copy after the first.
+  const titleId = useId();
+
   const handleClose = useCallback(() => {
     dialogRef.current?.close();
     onOpenChange(false);
@@ -120,9 +126,9 @@ export function ConnectSlackDialog({
       onClose={handleClose}
       className={cn(
         "stg:w-full stg:max-w-md stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-black/50" : "stg:relative",
+        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-backdrop" : "stg:relative",
       )}
-      aria-labelledby="connect-slack-title"
+      aria-labelledby={titleId}
     >
       {/* Body mounts only while open so its flow state resets per
           session — reopening the dialog never resumes a stale flow. */}
@@ -132,6 +138,7 @@ export function ConnectSlackDialog({
           channel={channel ?? null}
           onChannelsChanged={onChannelsChanged}
           onClose={handleClose}
+          titleId={titleId}
           channelAppsHref={channelAppsHref}
         />
       )}
@@ -149,6 +156,8 @@ interface ConnectSlackDialogBodyProps {
   readonly onChannelsChanged?: () => void;
   readonly onClose: () => void;
   readonly channelAppsHref?: string;
+  /** Heading id minted by the outer dialog for its aria-labelledby. */
+  readonly titleId: string;
 }
 
 function ConnectSlackDialogBody({
@@ -157,6 +166,7 @@ function ConnectSlackDialogBody({
   onChannelsChanged,
   onClose,
   channelAppsHref,
+  titleId,
 }: ConnectSlackDialogBodyProps) {
   const deploymentMode = useDeploymentMode();
   const agentName = agent.metadata?.name || agent.metadata?.slug || "this agent";
@@ -276,7 +286,7 @@ function ConnectSlackDialogBody({
       <div className="stg:flex stg:items-start stg:justify-between stg:gap-3 stg:border-b stg:border-border stg:px-5 stg:py-4">
         <div className="stg:flex stg:items-center stg:gap-2.5">
           <SlackMarkIcon className="stg:size-5 stg:text-foreground" />
-          <h2 id="connect-slack-title" className="stg:text-sm stg:font-semibold stg:text-foreground">
+          <h2 id={titleId} className="stg:text-sm stg:font-semibold stg:text-foreground">
             {channel ? "Reconnect to Slack" : "Connect to Slack"}
           </h2>
         </div>

package/src/channel/ConnectWhatsAppDialog.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useId, useMemo, useRef, useState } from "react";
 import { cn } from "@stigmer/theme";
 import { getErrorReason, type ResourceRef } from "@stigmer/sdk";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
@@ -102,6 +102,12 @@ export function ConnectWhatsAppDialog({
 }: ConnectWhatsAppDialogProps) {
   const dialogRef = useRef<HTMLDialogElement>(null);
 
+  // Instance-scoped title id (oss#593): a reusable component must not
+  // hardcode DOM ids — hosts legitimately mount this dialog more than once
+  // per page (e.g. zone-cached detail pages), and duplicate ids break the
+  // aria-labelledby association for every copy after the first.
+  const titleId = useId();
+
   const handleClose = useCallback(() => {
     dialogRef.current?.close();
     onOpenChange(false);
@@ -131,9 +137,9 @@ export function ConnectWhatsAppDialog({
       onClose={handleClose}
       className={cn(
         "stg:w-full stg:max-w-md stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-black/50" : "stg:relative",
+        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-backdrop" : "stg:relative",
       )}
-      aria-labelledby="connect-whatsapp-title"
+      aria-labelledby={titleId}
     >
       {/* Body mounts only while open so its flow state resets per
           session — reopening the dialog never resumes a stale flow. */}
@@ -144,6 +150,7 @@ export function ConnectWhatsAppDialog({
           onChannelsChanged={onChannelsChanged}
           onClose={handleClose}
           channelAppsHref={channelAppsHref}
+          titleId={titleId}
         />
       )}
     </dialog>
@@ -160,6 +167,8 @@ interface ConnectWhatsAppDialogBodyProps {
   readonly onChannelsChanged?: () => void;
   readonly onClose: () => void;
   readonly channelAppsHref?: string;
+  /** Heading id minted by the outer dialog for its aria-labelledby. */
+  readonly titleId: string;
 }
 
 function ConnectWhatsAppDialogBody({
@@ -168,6 +177,7 @@ function ConnectWhatsAppDialogBody({
   onChannelsChanged,
   onClose,
   channelAppsHref,
+  titleId,
 }: ConnectWhatsAppDialogBodyProps) {
   const stigmer = useStigmer();
   const deploymentMode = useDeploymentMode();
@@ -314,7 +324,7 @@ function ConnectWhatsAppDialogBody({
       <div className="stg:flex stg:items-start stg:justify-between stg:gap-3 stg:border-b stg:border-border stg:px-5 stg:py-4">
         <div className="stg:flex stg:items-center stg:gap-2.5">
           <WhatsAppMarkIcon className="stg:size-5 stg:text-foreground" />
-          <h2 id="connect-whatsapp-title" className="stg:text-sm stg:font-semibold stg:text-foreground">
+          <h2 id={titleId} className="stg:text-sm stg:font-semibold stg:text-foreground">
             {channel ? "Reconnect to WhatsApp" : "Connect to WhatsApp"}
           </h2>
         </div>

package/src/channel/useChannelSessions.ts

@@ -1,6 +1,9 @@
 "use client";
 
 import { create } from "@bufbuild/protobuf";
+// AgentChannel is type-only here so the doc link below resolves (the sibling
+// channel hooks import it for real use); the strict tsdoc gate guards it.
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import { ListSessionsByChannelRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/io_pb";
 import { useStigmer } from "../hooks.js";