@sonordev/site-kit 7.1.2 → 7.3.0

package/dist/forms/useForm.d.ts

@@ -9,7 +9,7 @@
  * const { form, fields, values, errors, setFieldValue, submit, isSubmitting } = useForm('contact-form')
  *
  * return (
- *   <form onSubmit={(e) => { e.preventDefault(); submit() }}>
+ *   <form {...toolAttributes} onSubmit={handleSubmit}>
  *     {fields.map(field => (
  *       <MyCustomInput
  *         key={field.slug}
@@ -24,7 +24,9 @@
  * )
  * ```
  */
-import type { ManagedFormConfig, FormField, FormSubmitResult } from './types';
+import type { DeclarativeToolFormAttributes } from '../mcp/declarative';
+import type { FormEvent } from 'react';
+import type { ManagedFormConfig, FormField, FormSubmitOptions, FormSubmitOutcome, FormSubmitResult } from './types';
 export interface UseFormOptions {
     /** Project ID (defaults to SiteKitLayout config) */
     projectId?: string;
@@ -98,8 +100,23 @@ export interface UseFormReturn {
     validateField: (field: FormField) => string | null;
     /** Check if a field is visible (conditional logic) */
     isFieldVisible: (field: FormField) => boolean;
-    /** Submit the form */
-    submit: () => Promise<void>;
+    /**
+     * Submit the form. Resolves with what happened (sent, invalid, failed,
+     * busy); ignoring the result is fine.
+     */
+    submit: (options?: FormSubmitOptions) => Promise<FormSubmitOutcome>;
+    /**
+     * A ready-made `<form onSubmit>`: prevents the native submit, moves to the
+     * next step or submits, and hands an AI agent that submitted through
+     * WebMCP the outcome. Prefer it to calling `submit()` yourself.
+     */
+    handleSubmit: (event: FormEvent<HTMLFormElement>) => void;
+    /**
+     * WebMCP attributes for your `<form>` (`toolname`, `tooldescription`), so
+     * a browser agent can fill it as a tool. Spread them on the form element.
+     * Null until the form config loads.
+     */
+    toolAttributes: DeclarativeToolFormAttributes | null;
     /** Submission state */
     isSubmitting: boolean;
     isComplete: boolean;

package/dist/forms/webmcp.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @sonordev/site-kit/forms - managed forms as WebMCP tools
+ *
+ * Every managed form carries the declarative WebMCP attributes (`toolname`,
+ * `tooldescription`), so a browser agent can treat it as a tool: it fills the
+ * same controls a person would and the submit runs the same validation and
+ * files the same lead. There is deliberately no `toolautosubmit`. The agent
+ * fills the fields and the person it's helping presses Send, which is the
+ * right default for anything that files a lead or sends a message.
+ *
+ * Browsers that don't implement WebMCP ignore the attributes. Each field's
+ * label is what an agent reads to understand it (FormField adds the help
+ * text as `toolparamdescription` where there is some).
+ *
+ * Single source of truth for a managed form's tool name and description, and
+ * for reading an agent's submit (`SubmitEvent.agentInvoked`, `respondWith`).
+ * FormClient, FormSpotlight, FormStage, StaticForm and useForm all use it.
+ */
+import { type DeclarativeToolFormAttributes } from '../mcp/declarative';
+import type { ManagedFormConfig } from './types';
+/** `contact-page` -> `submit_contact_page`. Stable, snake_case, unique per form. */
+export declare function formToolName(config: Pick<ManagedFormConfig, 'slug'>): string;
+/** The tool description an agent reads to decide whether this form is the one. */
+export declare function formToolDescription(config: Pick<ManagedFormConfig, 'name' | 'form_type' | 'description'>): string;
+/** Spread onto the managed form's `<form>` element. */
+export declare function formToolAttributes(config: Pick<ManagedFormConfig, 'slug' | 'name' | 'form_type' | 'description'>): DeclarativeToolFormAttributes;
+export interface AgentSubmit {
+    /** True when the browser reports that an AI agent submitted the form. */
+    invoked: boolean;
+    /**
+     * Hand the agent the outcome of its submit. Call it synchronously inside
+     * the submit handler, after `preventDefault()`. A no-op unless an agent
+     * submitted and the browser supports `respondWith`.
+     */
+    respond: (outcome: Promise<unknown>) => void;
+}
+/** Read an agent's submit off a native SubmitEvent (`e.nativeEvent` in React). */
+export declare function readAgentSubmit(event: Event | null | undefined): AgentSubmit;

package/dist/images/index.js

@@ -1,6 +1,6 @@
-export { ManagedImage, assignImageToSlot, clearImageSlot, fetchManagedImage, fetchManagedImages, listImageFiles, uploadImage } from '../chunk-ILU5I6RW.js';
+export { ManagedImage, assignImageToSlot, clearImageSlot, fetchManagedImage, fetchManagedImages, listImageFiles, uploadImage } from '../chunk-ZHS2XFLV.js';
 export { ManagedFavicon, getManagedFaviconUrl } from '../chunk-GW7GSBO7.js';
-import '../chunk-3SDOQUUF.js';
-import '../chunk-VDF5DFWT.js';
-import '../chunk-AH5Q262S.js';
+import '../chunk-BEBR4OJD.js';
+import '../chunk-WGG6GTKW.js';
+import '../chunk-56KNHB4U.js';
 import '../chunk-PKBMQBKP.js';

package/dist/index.d.ts

@@ -15,7 +15,10 @@
 export { SITE_KIT_VERSION } from './shared/version';
 export type { ManagedMetadataResult, ManagedSchemaProps, ManagedFAQData } from './seo/types';
 export type { AnalyticsConfig, AnalyticsEvent, PageView } from './analytics/types';
-export type { EngageElement, WidgetConfig, ChatConfig } from './engage/types';
+export type { ChatConfig } from './chat/types';
+export type { SitePopup } from './website/popup-types';
+/** Deprecated names (engage was retired): SitePopup and SitePopupConfig. */
+export type { EngageElement, WidgetConfig } from './engage/types';
 export type { ManagedFormConfig, FormSubmission, FormSubmitResult, FormField } from './forms/types';
 export type { Article as ArticleType, ArticleAuthor, ArticleCategory } from './articles/types';
 export type { CommerceOffering, CommerceCategory, CommerceVariant, CommerceSchedule, OfferingType, Cart, CartItem, } from './commerce/types';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { SITE_KIT_VERSION } from './chunk-AH5Q262S.js';
+export { SITE_KIT_VERSION } from './chunk-56KNHB4U.js';
 import './chunk-PKBMQBKP.js';

package/dist/layout/SiteKitClientProviders.d.ts

@@ -2,7 +2,7 @@
  * SiteKitClientProviders — Client Island
  *
  * This is the 'use client' boundary for SiteKitLayout.
- * It composes the client-only providers (Analytics, Engage, Signal, SitemapSync)
+ * It composes the client-only providers (Analytics, chat, popups, Signal, SitemapSync)
  * that require React context or browser APIs.
  *
  * All modules are lazy-loaded via next/dynamic so their JS is only downloaded
@@ -10,7 +10,7 @@
  *
  * All modules share a unified identity (visitor ID + session ID) read from
  * the storage-backed singleton (shared/identity), ensuring consistent
- * tracking across Analytics, Signal, and Engage.
+ * tracking across Analytics, Signal, chat and popups.
  *
  * 4.0 INVARIANT — CHILDREN ARE NEVER WRAPPED. Every module here renders as a
  * childless sibling AFTER {children}; nothing provides context around page
@@ -56,7 +56,7 @@ export interface SiteKitClientProvidersProps {
      */
     design?: boolean | DesignConfig;
     /**
-     * Defer Analytics / Engage / SitemapSync until window load + idle or first
+     * Defer Analytics / chat / popups / SitemapSync until window load + idle or first
      * interaction (default true). Pass false to restore legacy eager mounting
      * on hydration. SignalBridge is never deferred — it must apply experiment
      * variants as early as possible.

package/dist/layout/SiteKitLayout.d.ts

@@ -11,7 +11,7 @@
  *
  * Client-side (island):
  *   - AnalyticsProvider (page views, scroll depth, heatmap, web vitals)
- *   - EngageWidget (popups, nudges, chat)
+ *   - SitePopups (Website → Popups & Banners) and SiteChat (Website chat)
  *   - SignalBridge (A/B experiments, behavior tracking)
  *   - SitemapSync (keeps Sonor seo_pages in sync)
  *
@@ -37,7 +37,7 @@
  *
  * @example Opt out of specific features:
  * ```tsx
- * <SiteKitLayout engage={false} signal={false}>
+ * <SiteKitLayout chat={false} popups={false} signal={false}>
  *   {children}
  * </SiteKitLayout>
  * ```
@@ -50,7 +50,7 @@ export interface SiteKitLayoutProps {
     apiKey?: string;
     /** Sonor API URL. Defaults to env or https://api.sonor.io */
     apiUrl?: string;
-    /** Project ID (for Engage chat room routing). Auto-resolved if not provided. */
+    /** Project ID (for chat routing). Auto-resolved if not provided. */
     projectId?: string;
     /** Analytics tracking. true (default) | false | config object */
     analytics?: boolean | AnalyticsConfig;
@@ -100,7 +100,7 @@ export interface SiteKitLayoutProps {
      */
     design?: boolean | DesignConfig;
     /**
-     * Defer client modules (Analytics, Engage, SitemapSync) until window load +
+     * Defer client modules (Analytics, chat, popups, SitemapSync) until window load +
      * idle or the first user interaction, keeping their JS and mount work out of
      * the critical hydration path. Default: true. Pass false to restore legacy
      * eager mounting. SignalBridge is never deferred.

package/dist/layout/client.d.ts

@@ -2,7 +2,7 @@
  * SiteKitClientProviders — Client Island
  *
  * This is the 'use client' boundary for SiteKitLayout.
- * It composes the client-only providers (Analytics, Engage, Signal, SitemapSync)
+ * It composes the client-only providers (Analytics, chat, popups, Signal, SitemapSync)
  * that require React context or browser APIs.
  *
  * All modules are lazy-loaded via next/dynamic so their JS is only downloaded
@@ -10,7 +10,7 @@
  *
  * All modules share a unified identity (visitor ID + session ID) read from
  * the storage-backed singleton (shared/identity), ensuring consistent
- * tracking across Analytics, Signal, and Engage.
+ * tracking across Analytics, Signal, chat and popups.
  *
  * 4.0 INVARIANT — CHILDREN ARE NEVER WRAPPED. Every module here renders as a
  * childless sibling AFTER {children}; nothing provides context around page
@@ -56,7 +56,7 @@ export interface SiteKitClientProvidersProps {
      */
     design?: boolean | DesignConfig;
     /**
-     * Defer Analytics / Engage / SitemapSync until window load + idle or first
+     * Defer Analytics / chat / popups / SitemapSync until window load + idle or first
      * interaction (default true). Pass false to restore legacy eager mounting
      * on hydration. SignalBridge is never deferred — it must apply experiment
      * variants as early as possible.

package/dist/layout/client.js

@@ -1,10 +1,10 @@
 'use client';
-export { SiteKitClientProviders } from '../chunk-HF57LG73.js';
+export { SiteKitClientProviders } from '../chunk-2AD3CDRR.js';
 import '../chunk-6G43IRWR.js';
-import '../chunk-ERXXITG4.js';
-import '../chunk-NK4CSJNP.js';
+import '../chunk-VF4F5WXZ.js';
+import '../chunk-UPRSH6Q4.js';
 import '../chunk-ZTZQPYP6.js';
-import '../chunk-PHYMNUJU.js';
+import '../chunk-CYUFBKJQ.js';
 import '../chunk-YC7ELZS3.js';
 import '../chunk-FESKKJAS.js';
 import '../chunk-A4CC4ZG3.js';
@@ -12,7 +12,7 @@ import '../chunk-24QZEO3Q.js';
 import '../chunk-GJWI74ZZ.js';
 import '../chunk-43OCZ3JA.js';
 import '../chunk-EKBEOXTH.js';
-import '../chunk-3SDOQUUF.js';
-import '../chunk-VDF5DFWT.js';
-import '../chunk-AH5Q262S.js';
+import '../chunk-BEBR4OJD.js';
+import '../chunk-WGG6GTKW.js';
+import '../chunk-56KNHB4U.js';
 import '../chunk-PKBMQBKP.js';

package/dist/layout/index.js

@@ -1,12 +1,12 @@
-import { SiteKitClientProviders } from '../chunk-HF57LG73.js';
+import { SiteKitClientProviders } from '../chunk-2AD3CDRR.js';
 import '../chunk-6G43IRWR.js';
-import '../chunk-ERXXITG4.js';
-import '../chunk-NK4CSJNP.js';
+import '../chunk-VF4F5WXZ.js';
+import '../chunk-UPRSH6Q4.js';
 import '../chunk-ZTZQPYP6.js';
 import { ManagedFavicon } from '../chunk-GW7GSBO7.js';
-import '../chunk-PHYMNUJU.js';
+import '../chunk-CYUFBKJQ.js';
 import '../chunk-YC7ELZS3.js';
-import { resolveClientCredential } from '../chunk-6WIQCXOO.js';
+import { resolveClientCredential } from '../chunk-DNPNYWVL.js';
 import '../chunk-VX5CMNMM.js';
 import { ManagedScripts } from '../chunk-MVLMXC44.js';
 import { resolveApiOrigin } from '../chunk-X6F6SO4S.js';
@@ -17,9 +17,9 @@ import '../chunk-24QZEO3Q.js';
 import '../chunk-GJWI74ZZ.js';
 import '../chunk-43OCZ3JA.js';
 import '../chunk-EKBEOXTH.js';
-import '../chunk-3SDOQUUF.js';
-import '../chunk-VDF5DFWT.js';
-import '../chunk-AH5Q262S.js';
+import '../chunk-BEBR4OJD.js';
+import '../chunk-WGG6GTKW.js';
+import '../chunk-56KNHB4U.js';
 import '../chunk-PKBMQBKP.js';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 

package/dist/layout/types.d.ts

@@ -3,7 +3,7 @@
  * Kept in a shared file so both server (SiteKitLayout) and client
  * (SiteKitClientProviders) components can reference them.
  */
-import type { ChatLauncherPlacement } from '../engage/types';
+import type { ChatLauncherPlacement } from '../chat/types';
 import type { SiteDesignConfig } from '../website/design';
 /**
  * The site's design, for popups (Website → Popups & Banners). site-kit
@@ -47,9 +47,10 @@ export interface AnalyticsConfig {
     allowLocalhost?: boolean;
 }
 /**
- * Launcher placement (`position`, `offsetBottom`, `zIndex`) comes from
- * ChatLauncherPlacement in engage/types, the one definition every Engage
- * config surface extends.
+ * The deprecated `engage` prop's config. Launcher placement (`position`,
+ * `offsetBottom`, `zIndex`) comes from ChatLauncherPlacement in chat/types,
+ * the one definition every chat config surface extends; `zIndex` also stacks
+ * popups.
  */
 export interface EngageConfig extends ChatLauncherPlacement {
     chatEnabled?: boolean;

package/dist/llms/agent-access.d.ts

@@ -14,6 +14,10 @@ export interface AgentAccessOptions {
     endpoint?: string;
     /** The server card's path (default `/.well-known/mcp-server-card`). */
     card?: string;
+    /** Optional AI catalog path. Only set when the site serves this experimental discovery document. */
+    catalog?: string;
+    /** Place discovery before the first content section, preserving the title and introduction. */
+    position?: 'after-intro' | 'end';
     /** Tool names worth naming, e.g. the built-in ones. Optional. */
     tools?: string[];
 }

package/dist/llms/contract.js

@@ -1,2 +1,2 @@
-export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, isEmittableReviewNode, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag } from '../chunk-4Y5FWDPM.js';
+export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, clipAtWordBoundary, isEmittableReviewNode, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag } from '../chunk-NZ4RXN3G.js';
 import '../chunk-PKBMQBKP.js';

package/dist/llms/index.js

@@ -1,19 +1,19 @@
-export { createLLMsFullTxtHandler, createLLMsTxtHandler, formatSourcedFactsSection, llmsResponseHeaders } from '../chunk-WWSHFRDL.js';
+export { createLLMsFullTxtHandler, createLLMsTxtHandler, formatSourcedFactsSection, llmsResponseHeaders } from '../chunk-WDQB4OXY.js';
 export { buildAiDiscoveryHeaders, wantsLlmsDiscoveryLink } from '../chunk-PO2TRJPY.js';
 export { AI_RETRIEVAL_CRAWLERS, AI_TRAINING_CRAWLERS, buildAiCrawlerRules, createRobotsTxtHandler } from '../chunk-QLTDFUJ7.js';
-export { LEGACY_PUBLICATION_PATH, SEO_REVALIDATION_MAX_BODY_BYTES, SEO_REVALIDATION_MAX_ITEMS, createLlmsRevalidateHandler, createSeoRevalidationHandler, parseSeoRevalidationPayload } from '../chunk-VGH4MDTU.js';
+export { LEGACY_PUBLICATION_PATH, SEO_REVALIDATION_MAX_BODY_BYTES, SEO_REVALIDATION_MAX_ITEMS, createLlmsRevalidateHandler, createSeoRevalidationHandler, parseSeoRevalidationPayload } from '../chunk-NI2XNEMR.js';
 import '../chunk-XTRZGXB2.js';
 export { AEOBlock, AEOCitedContent, AEOClaim, AEOComparison, AEODefinition, AEOEntity, AEOProvenanceList, AEOStep, AEOSteps, AEOSummary, DEFAULT_SPEAKABLE_SELECTORS, SpeakableSchema, createSpeakableSchema, getSpeakableSelectorsForPage } from '../chunk-PSAG45YF.js';
-export { AGENT_ACCESS_HEADING, appendAgentAccessSection, describesMcp, detectMcpServer, formatAgentAccessSection, generateLLMsFullTxt, generateLLMsTxt, writeLLMsTxtToPublic } from '../chunk-QEDHRBAT.js';
-export { getBusinessInfo, getFAQItems, getLLMsData, getOptimizedLLMsTxt, getPageSummaries, getServices } from '../chunk-GLHQ3LRO.js';
+export { AGENT_ACCESS_HEADING, appendAgentAccessSection, describesMcp, detectMcpServer, formatAgentAccessSection, generateLLMsFullTxt, generateLLMsTxt, writeLLMsTxtToPublic } from '../chunk-Z65DHMTW.js';
+export { getBusinessInfo, getFAQItems, getLLMsData, getOptimizedLLMsTxt, getPageSummaries, getServices } from '../chunk-6U3VLV2C.js';
 import '../chunk-L5UOHS6E.js';
 import '../chunk-WMVK77ND.js';
 import '../chunk-VX5CMNMM.js';
-export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag } from '../chunk-4Y5FWDPM.js';
+export { LLMS_DISCLAIMER_MAX_LENGTH, LLMS_PUBLIC_SUMMARY_MAX_LENGTH, LLM_GEO_CONTRACT_VERSION, MANAGED_LLM_SCHEMA_KNOWN_KEYS, pickManagedLlmSchemaForJsonLd, sanitizeLlmsDisclaimerLine, sanitizeLlmsPublicSummary, sanitizePrimaryLanguageTag } from '../chunk-NZ4RXN3G.js';
 import '../chunk-4KZ6W3ZH.js';
 import '../chunk-MJP63SSS.js';
 import '../chunk-YVKRYQRG.js';
 import '../chunk-FESKKJAS.js';
 import '../chunk-A4CC4ZG3.js';
-import '../chunk-AH5Q262S.js';
+import '../chunk-56KNHB4U.js';
 import '../chunk-PKBMQBKP.js';

package/dist/maps/index.js

@@ -1,8 +1,8 @@
 'use client';
 import { monotonicMs } from '../chunk-MH2DSGC6.js';
-import { sonorFetch } from '../chunk-3SDOQUUF.js';
-import '../chunk-VDF5DFWT.js';
-import '../chunk-AH5Q262S.js';
+import { sonorFetch } from '../chunk-BEBR4OJD.js';
+import '../chunk-WGG6GTKW.js';
+import '../chunk-56KNHB4U.js';
 import '../chunk-PKBMQBKP.js';
 import { useState, useCallback, useEffect } from 'react';
 import { APIProvider, Map as Map$1, AdvancedMarker, Pin, InfoWindow } from '@vis.gl/react-google-maps';

package/dist/mcp/WebMcpTools.d.ts

@@ -29,11 +29,12 @@ export interface WebMcpToolsProps {
     /** MCP endpoint on this origin (default `/api/mcp`). */
     endpoint?: string;
     /**
-     * Wait for the page to go quiet before registering (default true).
+     * Wait for the page to go quiet before registering (default false).
      *
-     * Registration is not user-visible and must never compete with hydration.
-     * An agent arriving at the page polls or listens for `toolchange`, so a
-     * couple of hundred milliseconds costs nothing; a blocked LCP costs a lot.
+     * Supported browsers discover tools as soon as this component mounts, so
+     * an agent need not wait for window load, idle, or a human interaction.
+     * Pass true to retain load + idle activation. Unsupported browsers never
+     * fetch a catalog or register tools, regardless of this setting.
      */
     defer?: boolean;
     /**

package/dist/mcp/client.js

@@ -6,21 +6,28 @@ import { useEffect } from 'react';
 function getModelContext() {
   if (typeof window === "undefined") return null;
   const doc = document;
-  if (doc.modelContext) return doc.modelContext;
   const nav = navigator;
-  return nav.modelContext ?? null;
+  for (const context of [doc.modelContext, nav.modelContext]) {
+    if (typeof context?.registerTool === "function" || typeof context?.provideContext === "function") {
+      return context;
+    }
+  }
+  return null;
 }
 function isWebMcpAvailable() {
   return getModelContext() !== null;
 }
+var EMPTY_TOOLS = [];
+var EMPTY_LOCAL_TOOLS = [];
 function WebMcpTools({
-  tools = [],
-  localTools = [],
+  tools = EMPTY_TOOLS,
+  localTools = EMPTY_LOCAL_TOOLS,
   endpoint = "/api/mcp",
-  defer = true,
+  defer = false,
   discover = true
 }) {
-  const ready = useDeferredActivation(defer);
+  const deferredReady = useDeferredActivation(defer);
+  const ready = !defer || deferredReady;
   useEffect(() => {
     if (!ready) return;
     const modelContext = getModelContext();
@@ -113,7 +120,7 @@ function WebMcpTools({
           await modelContext.provideContext({ tools: definitions });
         }
       } catch (error) {
-        if (process.env.NODE_ENV !== "production") {
+        if (!controller.signal.aborted && process.env.NODE_ENV !== "production") {
           console.warn("[site-kit/mcp] WebMCP registration failed:", error);
         }
       }

package/dist/mcp/discovery.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Experimental domain discovery from the MCP Server Cards discovery draft.
+ * The catalog points at the existing card; it never copies tools or identity
+ * metadata whose authoritative source is the server/card itself.
+ *
+ * @see https://github.com/modelcontextprotocol/ext-server-card/blob/main/docs/discovery.md
+ */
+import type { McpServerInfo } from './types';
+import { MCP_SERVER_CARD_MEDIA_TYPE } from './serverCard';
+export declare const MCP_AI_CATALOG_PATH = "/.well-known/ai-catalog.json";
+export declare const MCP_AI_CATALOG_MEDIA_TYPE = "application/ai-catalog+json";
+export interface McpAiCatalog {
+    specVersion: '1.0';
+    entries: {
+        identifier: string;
+        type: typeof MCP_SERVER_CARD_MEDIA_TYPE;
+        url: string;
+    }[];
+}
+export interface BuildMcpAiCatalogOptions {
+    /** Reuse the server identity; `io.example/weather` becomes `mcp:weather`. */
+    info: Pick<McpServerInfo, 'name'>;
+    /** Explicit public site origin. Never inferred from an untrusted Host header. */
+    baseUrl: string;
+    /** Origin-relative card path, e.g. `/api/mcp/server-card`. */
+    serverCardPath: string;
+}
+/** Build the small, experimental catalog without duplicating the server card. */
+export declare function buildMcpAiCatalog(options: BuildMcpAiCatalogOptions): McpAiCatalog;
+export interface McpAiCatalogHandlerOptions extends BuildMcpAiCatalogOptions {
+    /** Seconds for `Cache-Control: public, max-age=…` (default 3600). */
+    maxAge?: number;
+}
+export interface McpDiscoveryRouteHandlers {
+    GET: (request?: Request) => Promise<Response>;
+    OPTIONS: () => Promise<Response>;
+}
+/**
+ * Serve the experimental catalog at `MCP_AI_CATALOG_PATH`. This static-safe
+ * handler leaves conditional ETag requests to the host/CDN, like llms.txt and
+ * the default card handler; it never reads incoming request headers.
+ */
+export declare function createMcpAiCatalogHandler(options: McpAiCatalogHandlerOptions): McpDiscoveryRouteHandlers;
+/** Shared public response policy for catalogs and cards; not an auth surface. */
+export declare function createMcpDiscoveryHandlers(document: unknown, options: {
+    mediaType: string;
+    maxAge?: number;
+}): McpDiscoveryRouteHandlers;

package/dist/mcp/handlers.d.ts

@@ -14,7 +14,8 @@
  */
 import { MCP_SUPPORTED_PROTOCOL_VERSIONS, type DispatchOutcome, type JsonRpcRequest, type McpServerDefinition } from './protocol';
 import type { McpToolCallRecord } from './types';
-import { type BuildMcpServerCardOptions } from './serverCard';
+import { type BuildMcpServerCardOptions, MCP_SERVER_CARD_MEDIA_TYPE } from './serverCard';
+import { type McpDiscoveryRouteHandlers } from './discovery';
 /**
  * Undo the spec's Base64 sentinel wrapper: `=?base64?{b64}?=`.
  * Values that aren't wrapped come back untouched.
@@ -74,18 +75,23 @@ export declare function createMcpHandler(options: McpHandlerOptions): McpRouteHa
 export interface McpServerCardHandlerOptions extends BuildMcpServerCardOptions {
     /** Seconds for `Cache-Control: public, max-age=…` (default 3600). */
     maxAge?: number;
+    /**
+     * Use the draft media type for a new canonical card URL. Existing routes
+     * default to application/json for compatibility. Both remain static-safe.
+     */
+    contentType?: 'application/json' | typeof MCP_SERVER_CARD_MEDIA_TYPE;
 }
-export interface McpServerCardRouteHandlers {
-    GET: () => Promise<Response>;
-    OPTIONS: () => Promise<Response>;
+export interface McpServerCardRouteHandlers extends McpDiscoveryRouteHandlers {
 }
 /**
- * Serve the SEP-2127 server card. Mount at BOTH well-known paths.
+ * Serve the server card. Keep both existing well-known paths available; the
+ * experimental AI Catalog can also point to an alias under the MCP endpoint.
  *
- * The handler never reads the incoming Request, so the route stays statically
+ * The handler never reads Request, so the route stays statically
  * prerenderable — the same constraint the llms.txt handlers document, and for
  * the same reason: touching `request.headers` opts the route into dynamic
- * rendering and it stops being served from the CDN.
+ * rendering. ETag validation is left to the host/CDN. Canonical card routes
+ * can use `contentType: MCP_SERVER_CARD_MEDIA_TYPE`; legacy aliases keep JSON.
  *
  * @example
  * ```ts

package/dist/mcp/index.d.ts

@@ -8,8 +8,8 @@
  *
  *   1. Remote MCP endpoint — `createMcpHandler`. Streamable HTTP, dual-era
  *      (2026-07-28 modern + the `initialize` handshake older clients speak).
- *   2. Discovery — `createMcpServerCardHandler`, the SEP-2127 card served at
- *      `/.well-known/mcp-server-card` and `/.well-known/mcp.json`.
+ *   2. Discovery — `createMcpAiCatalogHandler` (experimental draft) points to
+ *      `createMcpServerCardHandler`; existing well-known card URLs still work.
  *   3. In-page WebMCP — `<WebMcpTools>` (imperative) and
  *      `declarativeToolForm` (declarative), for browser-driving agents.
  *
@@ -20,8 +20,10 @@ export type { JsonSchemaNode, JsonSchemaObject, McpContent, McpTextContent, McpR
 export { defineMcpTool } from './types';
 export { MCP_PROTOCOL_VERSION_MODERN, MCP_PROTOCOL_VERSIONS_LEGACY, MCP_SUPPORTED_PROTOCOL_VERSIONS, META_PROTOCOL_VERSION, META_CLIENT_INFO, META_SERVER_INFO, MCP_ERROR_HEADER_MISMATCH, MCP_ERROR_UNSUPPORTED_PROTOCOL_VERSION, JSONRPC_METHOD_NOT_FOUND, dispatch, toToolResult, toolErrorResult, toToolDescriptor, validateArgs, isSupportedVersion, } from './protocol';
 export type { JsonRpcRequest, JsonRpcResponse, JsonRpcError, DispatchOutcome, DispatchOptions, McpServerDefinition, McpToolDescriptor, } from './protocol';
-export { buildMcpServerCard, validateMcpServerCard, MCP_SERVER_CARD_SCHEMA, MCP_SERVER_CARD_PATH, MCP_SERVER_CARD_LEGACY_PATH, SITE_KIT_CARD_META_KEY, } from './serverCard';
+export { buildMcpServerCard, validateMcpServerCard, MCP_SERVER_CARD_SCHEMA, MCP_SERVER_CARD_PATH, MCP_SERVER_CARD_LEGACY_PATH, MCP_SERVER_CARD_MEDIA_TYPE, SITE_KIT_CARD_META_KEY, } from './serverCard';
 export type { McpServerCard, McpRemote, BuildMcpServerCardOptions, } from './serverCard';
+export { buildMcpAiCatalog, createMcpAiCatalogHandler, MCP_AI_CATALOG_PATH, MCP_AI_CATALOG_MEDIA_TYPE, } from './discovery';
+export type { McpAiCatalog, BuildMcpAiCatalogOptions, McpAiCatalogHandlerOptions, McpDiscoveryRouteHandlers, } from './discovery';
 export { createMcpHandler, createMcpServerCardHandler, decodeHeaderValue, toolCallRecord, WEBMCP_SURFACE_HEADER, } from './handlers';
 export type { McpHandlerOptions, McpRouteHandlers, McpServerCardHandlerOptions, McpServerCardRouteHandlers, } from './handlers';
 export { declarativeToolForm, declarativeToolField } from './declarative';