@stigmer/react 3.12.1 → 3.12.2

package/src/mcp-server/internal/definitionDrift.ts

@@ -0,0 +1,158 @@
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { McpServerInput } from "@stigmer/sdk";
+import { mcpServerToInput } from "./mcpServerToInput.js";
+
+/**
+ * Connection-defining field groups a marketplace definition can drift on.
+ *
+ * Stable identifiers, not display copy — {@link DefinitionDriftNotice}
+ * owns the human-readable labels. Cosmetic fields (description, icon,
+ * tags, repository metadata, env var descriptions) are deliberately NOT
+ * drift: they cannot break a connection, so they never nag — they simply
+ * ride along when the user refreshes.
+ */
+export type DriftFieldId =
+  | "transport"
+  | "endpoint"
+  | "headers"
+  | "queryParams"
+  | "timeout"
+  | "command"
+  | "workingDirectory"
+  | "environmentVariables"
+  | "authentication";
+
+/**
+ * Deep equality over the plain-object projections produced by
+ * `mcpServerToInput`. Key order is irrelevant (proto map iteration order
+ * is not canonical); `undefined` values and absent keys are equivalent
+ * (the conversion uses `undefined` for proto defaults).
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return (
+      Array.isArray(a) &&
+      Array.isArray(b) &&
+      a.length === b.length &&
+      a.every((v, i) => deepEqual(v, b[i]))
+    );
+  }
+  if (isRecord(a) && isRecord(b)) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+      if (!deepEqual(a[key], b[key])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+/**
+ * The functional shape of an env declaration map: which vars exist,
+ * whether they are secret, whether they are optional. Descriptions are
+ * guidance for humans — a description-only template edit must not raise
+ * a drift notice.
+ */
+function functionalEnvShape(env: McpServerInput["env"]) {
+  if (!env) return undefined;
+  const shape: Record<string, { isSecret?: boolean; optional?: boolean }> = {};
+  for (const [key, decl] of Object.entries(env)) {
+    shape[key] = { isSecret: decl.isSecret, optional: decl.optional };
+  }
+  return shape;
+}
+
+/**
+ * Compares an org-owned MCP server against the marketplace definition it
+ * mirrors and reports which connection-defining field groups differ, or
+ * `null` when the connection-defining configuration matches.
+ *
+ * The comparison runs on `mcpServerToInput` projections rather than raw
+ * protos: that conversion is the SDK's canonical read-modify-write lens,
+ * and its exhaustiveness is fence-tested — so a new spec field cannot
+ * silently bypass this comparison either.
+ */
+export function computeDefinitionDrift(
+  current: McpServer,
+  template: McpServer,
+): readonly DriftFieldId[] | null {
+  const cur = mcpServerToInput(current);
+  const tpl = mcpServerToInput(template);
+
+  const changed: DriftFieldId[] = [];
+
+  const curTransport = cur.stdio ? "stdio" : cur.http ? "http" : "none";
+  const tplTransport = tpl.stdio ? "stdio" : tpl.http ? "http" : "none";
+
+  if (curTransport !== tplTransport) {
+    changed.push("transport");
+  } else if (curTransport === "http") {
+    if (cur.http!.url !== tpl.http!.url) changed.push("endpoint");
+    if (!deepEqual(cur.http!.headers, tpl.http!.headers)) changed.push("headers");
+    if (!deepEqual(cur.http!.queryParams, tpl.http!.queryParams)) {
+      changed.push("queryParams");
+    }
+    if (cur.http!.timeoutSeconds !== tpl.http!.timeoutSeconds) {
+      changed.push("timeout");
+    }
+  } else if (curTransport === "stdio") {
+    if (
+      cur.stdio!.command !== tpl.stdio!.command ||
+      !deepEqual(cur.stdio!.args, tpl.stdio!.args)
+    ) {
+      changed.push("command");
+    }
+    if (cur.stdio!.workingDir !== tpl.stdio!.workingDir) {
+      changed.push("workingDirectory");
+    }
+  }
+
+  if (!deepEqual(functionalEnvShape(cur.env), functionalEnvShape(tpl.env))) {
+    changed.push("environmentVariables");
+  }
+
+  if (!deepEqual(cur.auth, tpl.auth)) {
+    changed.push("authentication");
+  }
+
+  return changed.length > 0 ? changed : null;
+}
+
+/**
+ * Builds the update payload for a one-click "refresh from marketplace".
+ *
+ * Definition fields — transport, env declarations, auth, and the cosmetic
+ * description/icon/tags/repository metadata — come from the template.
+ * The user's own choices survive: identity (name/org/slug/labels), tool
+ * enablement, and pinned approval policies. Visibility is not part of the
+ * input contract at all (the backend preserves it on update;
+ * `updateVisibility` is its dedicated write path).
+ *
+ * Built by merging two `mcpServerToInput` projections, so the preserved
+ * set is the explicit override list below and nothing can be lost in
+ * translation (the conversion is fence-tested exhaustive).
+ */
+export function buildRefreshInput(
+  current: McpServer,
+  template: McpServer,
+): McpServerInput {
+  const cur = mcpServerToInput(current);
+  const tpl = mcpServerToInput(template);
+
+  return {
+    ...tpl,
+    // Identity: the update must land on the user's own resource.
+    name: cur.name,
+    org: cur.org,
+    slug: cur.slug,
+    labels: cur.labels,
+    // User policy: never reset by a definition refresh.
+    defaultEnabledTools: cur.defaultEnabledTools,
+    pinnedToolApprovals: cur.pinnedToolApprovals,
+  };
+}

package/src/mcp-server/internal/mcpServerToInput.ts

@@ -36,6 +36,7 @@ export function mcpServerToInput(server: McpServer): McpServerInput {
       ? spec.pinnedToolApprovals.map((p) => ({
           toolName: p.toolName || undefined,
           message: p.message || undefined,
+          fromDestructiveHint: p.fromDestructiveHint || undefined,
         }))
       : undefined;
 
@@ -48,6 +49,7 @@ export function mcpServerToInput(server: McpServer): McpServerInput {
         tokenLifetimeHint: spec.auth.tokenLifetimeHint || undefined,
         scopeHints: spec.auth.scopeHints.length > 0 ? [...spec.auth.scopeHints] : undefined,
         discoveryUrl: spec.auth.discoveryUrl || undefined,
+        oauthOnly: spec.auth.oauthOnly || undefined,
       }
     : undefined;
 
@@ -60,6 +62,7 @@ export function mcpServerToInput(server: McpServer): McpServerInput {
       : undefined,
     description: spec?.description || undefined,
     iconUrl: spec?.iconUrl || undefined,
+    tags: spec?.tags?.length ? [...spec.tags] : undefined,
     defaultEnabledTools: spec?.defaultEnabledTools?.length
       ? [...spec.defaultEnabledTools]
       : undefined,

package/src/mcp-server/steps/EnvironmentAuthStep.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useState } from "react";
+import { useCallback, useId, useState } from "react";
 import { cn } from "@stigmer/theme";
 import type { McpServerWizardData, EnvVarEntry } from "./types.js";
 
@@ -25,6 +25,7 @@ export function EnvironmentAuthStep({
   data,
   updateData,
 }: EnvironmentAuthStepProps) {
+  const baseId = useId();
   const [envExpanded, setEnvExpanded] = useState(data.env.length > 0);
 
   return (
@@ -41,7 +42,6 @@ export function EnvironmentAuthStep({
 
       {/* Environment Variables */}
       <CollapsibleSection
-        id="env"
         title="Environment Variables"
         subtitle="Secrets and configuration the server requires at runtime"
         count={data.env.length}
@@ -56,7 +56,6 @@ export function EnvironmentAuthStep({
 
       {/* Auth Configuration */}
       <CollapsibleSection
-        id="auth"
         title="OAuth Authentication"
         subtitle="Configure OAuth for servers that require user authorization"
         expanded={data.authEnabled}
@@ -66,13 +65,13 @@ export function EnvironmentAuthStep({
           <div className="stg:grid stg:gap-4 stg:sm:grid-cols-2">
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-auth-app-org"
+                htmlFor={`${baseId}-app-org`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 OAuth App Organization
               </label>
               <input
-                id="stgm-wizard-mcp-auth-app-org"
+                id={`${baseId}-app-org`}
                 type="text"
                 value={data.authOAuthAppOrg}
                 onChange={(e) =>
@@ -89,13 +88,13 @@ export function EnvironmentAuthStep({
 
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-auth-app-slug"
+                htmlFor={`${baseId}-app-slug`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 OAuth App Slug
               </label>
               <input
-                id="stgm-wizard-mcp-auth-app-slug"
+                id={`${baseId}-app-slug`}
                 type="text"
                 value={data.authOAuthAppSlug}
                 onChange={(e) =>
@@ -113,13 +112,13 @@ export function EnvironmentAuthStep({
 
           <div className="stg:space-y-1.5">
             <label
-              htmlFor="stgm-wizard-mcp-auth-target-var"
+              htmlFor={`${baseId}-target-var`}
               className="stg:text-sm stg:font-medium stg:text-foreground"
             >
               Target Environment Variable
             </label>
             <input
-              id="stgm-wizard-mcp-auth-target-var"
+              id={`${baseId}-target-var`}
               type="text"
               value={data.authTargetEnvVar}
               onChange={(e) =>
@@ -140,13 +139,13 @@ export function EnvironmentAuthStep({
           <div className="stg:grid stg:gap-4 stg:sm:grid-cols-2">
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-auth-lifetime"
+                htmlFor={`${baseId}-lifetime`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 Token Lifetime Hint
               </label>
               <input
-                id="stgm-wizard-mcp-auth-lifetime"
+                id={`${baseId}-lifetime`}
                 type="text"
                 value={data.authTokenLifetimeHint}
                 onChange={(e) =>
@@ -163,13 +162,13 @@ export function EnvironmentAuthStep({
 
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-auth-scopes"
+                htmlFor={`${baseId}-scopes`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 Scope Hints
               </label>
               <input
-                id="stgm-wizard-mcp-auth-scopes"
+                id={`${baseId}-scopes`}
                 type="text"
                 value={data.authScopeHints}
                 onChange={(e) =>
@@ -190,13 +189,13 @@ export function EnvironmentAuthStep({
 
           <div className="stg:space-y-1.5">
             <label
-              htmlFor="stgm-wizard-mcp-auth-discovery"
+              htmlFor={`${baseId}-discovery`}
               className="stg:text-sm stg:font-medium stg:text-foreground"
             >
               Discovery URL
             </label>
             <input
-              id="stgm-wizard-mcp-auth-discovery"
+              id={`${baseId}-discovery`}
               type="url"
               value={data.authDiscoveryUrl}
               onChange={(e) =>
@@ -221,7 +220,6 @@ export function EnvironmentAuthStep({
 // ---------------------------------------------------------------------------
 
 function CollapsibleSection({
-  id,
   title,
   subtitle,
   count,
@@ -229,7 +227,6 @@ function CollapsibleSection({
   onToggle,
   children,
 }: {
-  readonly id: string;
   readonly title: string;
   readonly subtitle: string;
   readonly count?: number;
@@ -237,13 +234,16 @@ function CollapsibleSection({
   readonly onToggle: () => void;
   readonly children: React.ReactNode;
 }) {
+  // The disclosure-panel DOM id is minted per mount — deriving it from a
+  // static section key would collide when two wizards mount on one page.
+  const panelId = useId();
   return (
     <div className="stg:overflow-hidden stg:rounded-lg stg:border stg:border-border">
       <button
         type="button"
         onClick={onToggle}
         aria-expanded={expanded}
-        aria-controls={`stgm-wizard-section-${id}`}
+        aria-controls={panelId}
         className={cn(
           "stg:flex stg:w-full stg:items-center stg:justify-between stg:px-4 stg:py-3 stg:text-left stg:transition-colors",
           "stg:hover:bg-accent-hover",
@@ -269,7 +269,7 @@ function CollapsibleSection({
 
       {expanded && (
         <div
-          id={`stgm-wizard-section-${id}`}
+          id={panelId}
           className="stg:border-t stg:border-border stg:px-4 stg:py-4"
         >
           {children}

package/src/mcp-server/steps/IdentityTransportStep.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback } from "react";
+import { useCallback, useId } from "react";
 import { cn } from "@stigmer/theme";
 import { generateSlug } from "../../internal/slug.js";
 import type { McpServerWizardData, KeyValueEntry } from "./types.js";
@@ -35,6 +35,7 @@ export function IdentityTransportStep({
   updateData,
   validationError,
 }: IdentityTransportStepProps) {
+  const baseId = useId();
   const handleNameChange = useCallback(
     (value: string) => {
       if (!data.slugTouched) {
@@ -79,13 +80,13 @@ export function IdentityTransportStep({
       <div className="stg:grid stg:gap-4 stg:sm:grid-cols-2">
         <div className="stg:space-y-1.5">
           <label
-            htmlFor="stgm-wizard-mcp-name"
+            htmlFor={`${baseId}-name`}
             className="stg:text-sm stg:font-medium stg:text-foreground"
           >
             Name <span className="stg:text-destructive">*</span>
           </label>
           <input
-            id="stgm-wizard-mcp-name"
+            id={`${baseId}-name`}
             type="text"
             value={data.name}
             onChange={(e) => handleNameChange(e.target.value)}
@@ -101,13 +102,13 @@ export function IdentityTransportStep({
 
         <div className="stg:space-y-1.5">
           <label
-            htmlFor="stgm-wizard-mcp-slug"
+            htmlFor={`${baseId}-slug`}
             className="stg:text-sm stg:font-medium stg:text-foreground"
           >
             Slug
           </label>
           <input
-            id="stgm-wizard-mcp-slug"
+            id={`${baseId}-slug`}
             type="text"
             value={data.slug}
             onChange={(e) => handleSlugChange(e.target.value)}
@@ -135,13 +136,13 @@ export function IdentityTransportStep({
       {/* Description */}
       <div className="stg:space-y-1.5">
         <label
-          htmlFor="stgm-wizard-mcp-description"
+          htmlFor={`${baseId}-description`}
           className="stg:text-sm stg:font-medium stg:text-foreground"
         >
           Description
         </label>
         <input
-          id="stgm-wizard-mcp-description"
+          id={`${baseId}-description`}
           type="text"
           value={data.description}
           onChange={(e) => updateData({ description: e.target.value })}
@@ -159,13 +160,13 @@ export function IdentityTransportStep({
       <div className="stg:grid stg:gap-4 stg:sm:grid-cols-2">
         <div className="stg:space-y-1.5">
           <label
-            htmlFor="stgm-wizard-mcp-icon"
+            htmlFor={`${baseId}-icon`}
             className="stg:text-sm stg:font-medium stg:text-foreground"
           >
             Icon URL
           </label>
           <input
-            id="stgm-wizard-mcp-icon"
+            id={`${baseId}-icon`}
             type="url"
             value={data.iconUrl}
             onChange={(e) => updateData({ iconUrl: e.target.value })}
@@ -184,14 +185,14 @@ export function IdentityTransportStep({
           </legend>
           <div className="stg:flex stg:gap-2">
             <RadioOption
-              name="stgm-wizard-mcp-visibility"
+              name={`${baseId}-visibility`}
               value="private"
               label="Private"
               checked={data.visibility === "private"}
               onChange={() => updateData({ visibility: "private" })}
             />
             <RadioOption
-              name="stgm-wizard-mcp-visibility"
+              name={`${baseId}-visibility`}
               value="public"
               label="Public"
               checked={data.visibility === "public"}
@@ -209,14 +210,14 @@ export function IdentityTransportStep({
         </legend>
         <div className="stg:flex stg:gap-2">
           <RadioOption
-            name="stgm-wizard-mcp-transport"
+            name={`${baseId}-transport`}
             value="http"
             label="HTTP (Streamable HTTP / SSE)"
             checked={data.transportType === "http"}
             onChange={() => updateData({ transportType: "http" })}
           />
           <RadioOption
-            name="stgm-wizard-mcp-transport"
+            name={`${baseId}-transport`}
             value="stdio"
             label="Stdio (local process)"
             checked={data.transportType === "stdio"}
@@ -236,13 +237,13 @@ export function IdentityTransportStep({
           <div className="stg:flex stg:flex-col stg:gap-4 stg:rounded-lg stg:border stg:border-border stg:p-4">
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-http-url"
+                htmlFor={`${baseId}-http-url`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 URL <span className="stg:text-destructive">*</span>
               </label>
               <input
-                id="stgm-wizard-mcp-http-url"
+                id={`${baseId}-http-url`}
                 type="url"
                 value={data.httpUrl}
                 onChange={(e) => updateData({ httpUrl: e.target.value })}
@@ -274,13 +275,13 @@ export function IdentityTransportStep({
 
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-http-timeout"
+                htmlFor={`${baseId}-http-timeout`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 Timeout (seconds)
               </label>
               <input
-                id="stgm-wizard-mcp-http-timeout"
+                id={`${baseId}-http-timeout`}
                 type="number"
                 min={0}
                 step={1}
@@ -308,13 +309,13 @@ export function IdentityTransportStep({
           <div className="stg:flex stg:flex-col stg:gap-4 stg:rounded-lg stg:border stg:border-border stg:p-4">
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-stdio-command"
+                htmlFor={`${baseId}-stdio-command`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 Command <span className="stg:text-destructive">*</span>
               </label>
               <input
-                id="stgm-wizard-mcp-stdio-command"
+                id={`${baseId}-stdio-command`}
                 type="text"
                 value={data.stdioCommand}
                 onChange={(e) => updateData({ stdioCommand: e.target.value })}
@@ -329,13 +330,13 @@ export function IdentityTransportStep({
 
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-stdio-args"
+                htmlFor={`${baseId}-stdio-args`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 Arguments
               </label>
               <input
-                id="stgm-wizard-mcp-stdio-args"
+                id={`${baseId}-stdio-args`}
                 type="text"
                 value={data.stdioArgs}
                 onChange={(e) => updateData({ stdioArgs: e.target.value })}
@@ -353,13 +354,13 @@ export function IdentityTransportStep({
 
             <div className="stg:space-y-1.5">
               <label
-                htmlFor="stgm-wizard-mcp-stdio-workdir"
+                htmlFor={`${baseId}-stdio-workdir`}
                 className="stg:text-sm stg:font-medium stg:text-foreground"
               >
                 Working Directory
               </label>
               <input
-                id="stgm-wizard-mcp-stdio-workdir"
+                id={`${baseId}-stdio-workdir`}
                 type="text"
                 value={data.stdioWorkingDir}
                 onChange={(e) =>

package/src/mcp-server/useMcpServerConnect.ts

@@ -16,7 +16,7 @@ export interface UseMcpServerConnectReturn {
    * and classify tool approval policies via a lightweight LLM call.
    *
    * Calls the `connect` RPC which starts a Temporal workflow on the
-   * agent-runner. The RPC blocks until the workflow completes
+   * runner. The RPC blocks until the workflow completes
    * (typically 5-15 seconds, ~30s timeout).
    *
    * Platform system env vars (`STIGMER_SERVER_ADDRESS`,

package/src/mcp-server/useMcpServerDefinitionDrift.ts

@@ -0,0 +1,95 @@
+"use client";
+
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+import {
+  computeDefinitionDrift,
+  type DriftFieldId,
+} from "./internal/definitionDrift.js";
+
+/** A detected divergence from the marketplace definition. */
+export interface McpServerDefinitionDrift {
+  /** The marketplace definition the comparison ran against. */
+  readonly template: McpServer;
+  /** Connection-defining field groups that differ. Never empty. */
+  readonly changedFields: readonly DriftFieldId[];
+}
+
+/** Return value of {@link useMcpServerDefinitionDrift}. */
+export interface UseMcpServerDefinitionDriftReturn {
+  /**
+   * The detected drift, or `null` — which covers all of: still checking,
+   * no marketplace counterpart, ambiguous counterpart, configurations
+   * match, or the check failed. Consumers need no other state: this is an
+   * advisory affordance, not page data.
+   */
+  readonly drift: McpServerDefinitionDrift | null;
+}
+
+/**
+ * Detects when an org-owned MCP server's connection-defining
+ * configuration has drifted from the marketplace definition it mirrors
+ * (stigmer/stigmer#228: a template fix — e.g. monday.com's OAuth header —
+ * never reached servers copied before the fix, stranding them on a
+ * configuration that can never connect).
+ *
+ * **How the marketplace counterpart is found.** Connected copies carry no
+ * reference back to their template, so the hook uses the platform's own
+ * client-side definition of "marketplace": the search RPC's
+ * `crossOrgPublic` scope (what the library's "All" tab shows). A public
+ * row with the exact same slug from a different org is treated as the
+ * template. Zero or multiple candidates means there is nothing
+ * trustworthy to compare against — the hook stays quiet.
+ *
+ * **Fail-quiet by design.** Drift detection is advisory. No network
+ * error, missing template, or ambiguity may ever degrade the detail page,
+ * so every failure path resolves to `null` rather than an error state.
+ *
+ * Pass `null` to skip (stable no-op) — callers gate on editability, since
+ * the paired refresh action writes to the resource and the notice is
+ * meaningless to viewers who cannot act on it.
+ */
+export function useMcpServerDefinitionDrift(
+  mcpServer: McpServer | null,
+): UseMcpServerDefinitionDriftReturn {
+  const stigmer = useStigmer();
+
+  const org = mcpServer?.metadata?.org ?? null;
+  const slug = mcpServer?.metadata?.slug ?? null;
+
+  const { data: drift } = useFetch<McpServerDefinitionDrift | null>(
+    mcpServer && org && slug
+      ? async () => {
+          try {
+            const result = await stigmer.mcpServer.list({
+              org,
+              query: slug,
+              crossOrgPublic: true,
+            });
+            const candidateOrgs = [
+              ...new Set(
+                result.entries
+                  .filter((e) => e.slug === slug && e.org && e.org !== org)
+                  .map((e) => e.org),
+              ),
+            ];
+            if (candidateOrgs.length !== 1) return null;
+
+            const template = await stigmer.mcpServer.getByReference({
+              org: candidateOrgs[0],
+              slug,
+            });
+            const changedFields = computeDefinitionDrift(mcpServer, template);
+            return changedFields ? { template, changedFields } : null;
+          } catch {
+            return null;
+          }
+        }
+      : null,
+    [mcpServer, org, slug, stigmer],
+    null,
+  );
+
+  return { drift };
+}

package/src/models/ModelRegistryContext.ts

@@ -1,11 +1,17 @@
 "use client";
 
 import { createContext, useContext } from "react";
-import type { ModelInfo } from "./registry.js";
+import type { ModelInfo, VisionLimits } from "./registry.js";
 
 /** Internal state held by the model registry context provider. */
 export interface ModelRegistryState {
   readonly models: readonly ModelInfo[];
+  /**
+   * Document-level vision byte budget (stigmer/stigmer#365).
+   * `undefined` while loading or when the served document predates the
+   * `limits` block — consumers stay silent rather than assume a budget.
+   */
+  readonly visionLimits?: VisionLimits;
   readonly isLoading: boolean;
   readonly error: Error | null;
   /** Retry fetching the model registry. No-op while a fetch is in flight. */