@assistant-ui/mcp-docs-server 0.1.38 → 0.2.0

package/dist/tools/tests/mcp-test-client.js

@@ -0,0 +1,68 @@
+import { InMemoryTransport } from "@modelcontextprotocol/server";
+//#region src/tools/tests/mcp-test-client.ts
+function isJsonRpcResponse(message) {
+	return typeof message === "object" && message !== null && "id" in message && typeof message.id === "number" && ("result" in message || "error" in message);
+}
+async function createMcpTestClient(server) {
+	const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+	const pendingRequests = /* @__PURE__ */ new Map();
+	let nextRequestId = 1;
+	clientTransport.onmessage = (message) => {
+		if (!isJsonRpcResponse(message)) return;
+		const pendingRequest = pendingRequests.get(message.id);
+		if (!pendingRequest) return;
+		pendingRequests.delete(message.id);
+		if (message.error) {
+			pendingRequest.reject(/* @__PURE__ */ new Error(`MCP request failed (${message.error.code}): ${message.error.message}`));
+			return;
+		}
+		pendingRequest.resolve(message.result);
+	};
+	await clientTransport.start();
+	await server.connect(serverTransport);
+	const request = (rawRequest) => {
+		const id = nextRequestId++;
+		return new Promise((resolve, reject) => {
+			pendingRequests.set(id, {
+				resolve,
+				reject
+			});
+			clientTransport.send({
+				jsonrpc: "2.0",
+				id,
+				...rawRequest
+			}).catch((error) => {
+				pendingRequests.delete(id);
+				reject(error instanceof Error ? error : new Error(String(error)));
+			});
+		});
+	};
+	return {
+		initialize: async () => {
+			const result = await request({
+				method: "initialize",
+				params: {
+					protocolVersion: "2025-11-25",
+					capabilities: {},
+					clientInfo: {
+						name: "mcp-docs-server-tests",
+						version: "1.0.0"
+					}
+				}
+			});
+			await clientTransport.send({
+				jsonrpc: "2.0",
+				method: "notifications/initialized"
+			});
+			return result;
+		},
+		request,
+		close: async () => {
+			await clientTransport.close();
+		}
+	};
+}
+//#endregion
+export { createMcpTestClient };
+
+//# sourceMappingURL=mcp-test-client.js.map

package/dist/tools/tests/mcp-test-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-test-client.js","names":[],"sources":["../../../src/tools/tests/mcp-test-client.ts"],"sourcesContent":["import {\n  InMemoryTransport,\n  type McpServer,\n} from \"@modelcontextprotocol/server\";\n\ntype RawMcpRequest = {\n  method: string;\n  params?: unknown;\n};\n\ntype JsonRpcResponse = {\n  id: number;\n  result?: unknown;\n  error?: {\n    code: number;\n    message: string;\n  };\n};\n\ntype PendingRequest = {\n  resolve: (result: unknown) => void;\n  reject: (error: Error) => void;\n};\n\nexport type McpTestClient = {\n  initialize: () => Promise<unknown>;\n  request: <Result>(request: RawMcpRequest) => Promise<Result>;\n  close: () => Promise<void>;\n};\n\nfunction isJsonRpcResponse(message: unknown): message is JsonRpcResponse {\n  return (\n    typeof message === \"object\" &&\n    message !== null &&\n    \"id\" in message &&\n    typeof message.id === \"number\" &&\n    (\"result\" in message || \"error\" in message)\n  );\n}\n\nexport async function createMcpTestClient(\n  server: McpServer,\n): Promise<McpTestClient> {\n  const [clientTransport, serverTransport] =\n    InMemoryTransport.createLinkedPair();\n  const pendingRequests = new Map<number, PendingRequest>();\n  let nextRequestId = 1;\n\n  clientTransport.onmessage = (message) => {\n    if (!isJsonRpcResponse(message)) return;\n\n    const pendingRequest = pendingRequests.get(message.id);\n    if (!pendingRequest) return;\n\n    pendingRequests.delete(message.id);\n    if (message.error) {\n      pendingRequest.reject(\n        new Error(\n          `MCP request failed (${message.error.code}): ${message.error.message}`,\n        ),\n      );\n      return;\n    }\n\n    pendingRequest.resolve(message.result);\n  };\n\n  await clientTransport.start();\n  await server.connect(serverTransport);\n\n  const request = <Result>(rawRequest: RawMcpRequest): Promise<Result> => {\n    const id = nextRequestId++;\n\n    return new Promise((resolve, reject) => {\n      pendingRequests.set(id, { resolve, reject });\n      void clientTransport\n        .send({ jsonrpc: \"2.0\", id, ...rawRequest })\n        .catch((error: unknown) => {\n          pendingRequests.delete(id);\n          reject(error instanceof Error ? error : new Error(String(error)));\n        });\n    }) as Promise<Result>;\n  };\n\n  return {\n    initialize: async () => {\n      const result = await request({\n        method: \"initialize\",\n        params: {\n          protocolVersion: \"2025-11-25\",\n          capabilities: {},\n          clientInfo: {\n            name: \"mcp-docs-server-tests\",\n            version: \"1.0.0\",\n          },\n        },\n      });\n\n      await clientTransport.send({\n        jsonrpc: \"2.0\",\n        method: \"notifications/initialized\",\n      });\n\n      return result;\n    },\n    request,\n    close: async () => {\n      await clientTransport.close();\n    },\n  };\n}\n"],"mappings":";;AA8BA,SAAS,kBAAkB,SAA8C;CACvE,OACE,OAAO,YAAY,YACnB,YAAY,QACZ,QAAQ,WACR,OAAO,QAAQ,OAAO,aACrB,YAAY,WAAW,WAAW;AAEvC;AAEA,eAAsB,oBACpB,QACwB;CACxB,MAAM,CAAC,iBAAiB,mBACtB,kBAAkB,iBAAiB;CACrC,MAAM,kCAAkB,IAAI,IAA4B;CACxD,IAAI,gBAAgB;CAEpB,gBAAgB,aAAa,YAAY;EACvC,IAAI,CAAC,kBAAkB,OAAO,GAAG;EAEjC,MAAM,iBAAiB,gBAAgB,IAAI,QAAQ,EAAE;EACrD,IAAI,CAAC,gBAAgB;EAErB,gBAAgB,OAAO,QAAQ,EAAE;EACjC,IAAI,QAAQ,OAAO;GACjB,eAAe,uBACb,IAAI,MACF,uBAAuB,QAAQ,MAAM,KAAK,KAAK,QAAQ,MAAM,SAC/D,CACF;GACA;EACF;EAEA,eAAe,QAAQ,QAAQ,MAAM;CACvC;CAEA,MAAM,gBAAgB,MAAM;CAC5B,MAAM,OAAO,QAAQ,eAAe;CAEpC,MAAM,WAAmB,eAA+C;EACtE,MAAM,KAAK;EAEX,OAAO,IAAI,SAAS,SAAS,WAAW;GACtC,gBAAgB,IAAI,IAAI;IAAE;IAAS;GAAO,CAAC;GAC3C,gBACG,KAAK;IAAE,SAAS;IAAO;IAAI,GAAG;GAAW,CAAC,CAAC,CAC3C,OAAO,UAAmB;IACzB,gBAAgB,OAAO,EAAE;IACzB,OAAO,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC,CAAC;GAClE,CAAC;EACL,CAAC;CACH;CAEA,OAAO;EACL,YAAY,YAAY;GACtB,MAAM,SAAS,MAAM,QAAQ;IAC3B,QAAQ;IACR,QAAQ;KACN,iBAAiB;KACjB,cAAc,CAAC;KACf,YAAY;MACV,MAAM;MACN,SAAS;KACX;IACF;GACF,CAAC;GAED,MAAM,gBAAgB,KAAK;IACzB,SAAS;IACT,QAAQ;GACV,CAAC;GAED,OAAO;EACT;EACA;EACA,OAAO,YAAY;GACjB,MAAM,gBAAgB,MAAM;EAC9B;CACF;AACF"}

package/dist/tools/tests/test-setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-setup.d.ts","names":[],"sources":["../../../src/tools/tests/test-setup.ts"],"mappings":";cAca,WAAA;2BACkB,IAAA,UAAW,OAAA;AAAA"}
+{"version":3,"file":"test-setup.d.ts","names":[],"sources":["../../../src/tools/tests/test-setup.ts"],"mappings":";cAsBa;EACY,WAAA,cAAM,cAAW"}

package/dist/tools/tests/test-setup.js

@@ -2,6 +2,7 @@ import { PACKAGE_DIR } from "../../constants.js";
 import { docsTools } from "../docs.js";
 import { examplesTools } from "../examples.js";
 import { searchTools } from "../search.js";
+import { xuluxTemplateDetailsTool, xuluxTemplatePreviewTool, xuluxTemplatesListTool } from "../xulux-templates.js";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { beforeAll } from "vitest";
@@ -9,7 +10,10 @@ import { beforeAll } from "vitest";
 const tools = {
 	assistantUIDocs: docsTools,
 	assistantUIExamples: examplesTools,
-	assistantUISearch: searchTools
+	assistantUISearch: searchTools,
+	assistantUITemplates: xuluxTemplatesListTool,
+	assistantUITemplateDetails: xuluxTemplateDetailsTool,
+	assistantUITemplatePreview: xuluxTemplatePreviewTool
 };
 const testContext = { callTool: async (name, args) => {
 	const tool = tools[name];

package/dist/tools/tests/test-setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-setup.js","names":[],"sources":["../../../src/tools/tests/test-setup.ts"],"sourcesContent":["import { beforeAll } from \"vitest\";\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { PACKAGE_DIR } from \"../../constants.js\";\nimport { docsTools } from \"../docs.js\";\nimport { examplesTools } from \"../examples.js\";\nimport { searchTools } from \"../search.js\";\n\nconst tools = {\n  assistantUIDocs: docsTools,\n  assistantUIExamples: examplesTools,\n  assistantUISearch: searchTools,\n};\n\nexport const testContext = {\n  callTool: async (name: string, args: any) => {\n    const tool = tools[name as keyof typeof tools];\n    if (!tool) {\n      throw new Error(`Tool ${name} not found`);\n    }\n    const result = await tool.execute(args);\n\n    const text = result.content?.[0]?.text;\n    if (text === undefined) {\n      throw new Error(`Tool ${name} returned no content`);\n    }\n    try {\n      return JSON.parse(text);\n    } catch (error) {\n      throw new Error(\n        `Tool ${name} returned invalid JSON. Output: ${text}\\nParse error: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  },\n};\n\nbeforeAll(() => {\n  const docsPath = join(PACKAGE_DIR, \".docs\");\n  if (!existsSync(docsPath)) {\n    throw new Error(\"Documentation not prepared. Run: pnpm build\");\n  }\n});\n"],"mappings":";;;;;;;;AAQA,MAAM,QAAQ;CACZ,iBAAiB;CACjB,qBAAqB;CACrB,mBAAmB;AACrB;AAEA,MAAa,cAAc,EACzB,UAAU,OAAO,MAAc,SAAc;CAC3C,MAAM,OAAO,MAAM;CACnB,IAAI,CAAC,MACH,MAAM,IAAI,MAAM,QAAQ,KAAK,WAAW;CAI1C,MAAM,QAAO,MAFQ,KAAK,QAAQ,IAAI,EAAA,CAElB,UAAU,EAAE,EAAE;CAClC,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,MAAM,QAAQ,KAAK,qBAAqB;CAEpD,IAAI;EACF,OAAO,KAAK,MAAM,IAAI;CACxB,SAAS,OAAO;EACd,MAAM,IAAI,MACR,QAAQ,KAAK,kCAAkC,KAAK,iBAAiB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAC5H;CACF;AACF,EACF;AAEA,gBAAgB;CAEd,IAAI,CAAC,WADY,KAAK,aAAa,OACZ,CAAC,GACtB,MAAM,IAAI,MAAM,6CAA6C;AAEjE,CAAC"}
+{"version":3,"file":"test-setup.js","names":[],"sources":["../../../src/tools/tests/test-setup.ts"],"sourcesContent":["import { beforeAll } from \"vitest\";\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { PACKAGE_DIR } from \"../../constants.js\";\nimport { docsTools } from \"../docs.js\";\nimport { examplesTools } from \"../examples.js\";\nimport { searchTools } from \"../search.js\";\nimport {\n  xuluxTemplatesListTool,\n  xuluxTemplateDetailsTool,\n  xuluxTemplatePreviewTool,\n} from \"../xulux-templates.js\";\n\nconst tools = {\n  assistantUIDocs: docsTools,\n  assistantUIExamples: examplesTools,\n  assistantUISearch: searchTools,\n  assistantUITemplates: xuluxTemplatesListTool,\n  assistantUITemplateDetails: xuluxTemplateDetailsTool,\n  assistantUITemplatePreview: xuluxTemplatePreviewTool,\n};\n\nexport const testContext = {\n  callTool: async (name: string, args: any) => {\n    const tool = tools[name as keyof typeof tools];\n    if (!tool) {\n      throw new Error(`Tool ${name} not found`);\n    }\n    const result = await tool.execute(args);\n\n    const text = result.content?.[0]?.text;\n    if (text === undefined) {\n      throw new Error(`Tool ${name} returned no content`);\n    }\n    try {\n      return JSON.parse(text);\n    } catch (error) {\n      throw new Error(\n        `Tool ${name} returned invalid JSON. Output: ${text}\\nParse error: ${error instanceof Error ? error.message : String(error)}`,\n      );\n    }\n  },\n};\n\nbeforeAll(() => {\n  const docsPath = join(PACKAGE_DIR, \".docs\");\n  if (!existsSync(docsPath)) {\n    throw new Error(\"Documentation not prepared. Run: pnpm build\");\n  }\n});\n"],"mappings":";;;;;;;;;AAaA,MAAM,QAAQ;CACZ,iBAAiB;CACjB,qBAAqB;CACrB,mBAAmB;CACnB,sBAAsB;CACtB,4BAA4B;CAC5B,4BAA4B;AAC9B;AAEA,MAAa,cAAc,EACzB,UAAU,OAAO,MAAc,SAAc;CAC3C,MAAM,OAAO,MAAM;CACnB,IAAI,CAAC,MACH,MAAM,IAAI,MAAM,QAAQ,KAAK,WAAW;CAI1C,MAAM,QAAO,MAFQ,KAAK,QAAQ,IAAI,EAAA,CAElB,UAAU,EAAE,EAAE;CAClC,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,MAAM,QAAQ,KAAK,qBAAqB;CAEpD,IAAI;EACF,OAAO,KAAK,MAAM,IAAI;CACxB,SAAS,OAAO;EACd,MAAM,IAAI,MACR,QAAQ,KAAK,kCAAkC,KAAK,iBAAiB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAC5H;CACF;AACF,EACF;AAEA,gBAAgB;CAEd,IAAI,CAAC,WADY,KAAK,aAAa,OACZ,CAAC,GACtB,MAAM,IAAI,MAAM,6CAA6C;AAEjE,CAAC"}

package/dist/tools/xulux-templates.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+//#region src/tools/xulux-templates.d.ts
+declare const emptyInputSchema: z.ZodObject<{}, z.core.$strip>;
+declare const detailsInputSchema: z.ZodObject<{
+  templateId: z.ZodString;
+  versionId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const previewInputSchema: z.ZodObject<{
+  templateId: z.ZodString;
+  versionId: z.ZodOptional<z.ZodString>;
+  config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const xuluxTemplatesListTool: {
+  name: string;
+  description: string;
+  parameters: z.ZodObject<{}, z.core.$strip>;
+  execute: (_args: z.infer<typeof emptyInputSchema>) => Promise<{
+    content: Array<{
+      type: "text";
+      text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+  }>;
+};
+declare const xuluxTemplateDetailsTool: {
+  name: string;
+  description: string;
+  parameters: z.ZodObject<{
+    templateId: z.ZodString;
+    versionId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  execute: (args: z.infer<typeof detailsInputSchema>) => Promise<{
+    content: Array<{
+      type: "text";
+      text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+  }>;
+};
+declare const xuluxTemplatePreviewTool: {
+  name: string;
+  description: string;
+  parameters: z.ZodObject<{
+    templateId: z.ZodString;
+    versionId: z.ZodOptional<z.ZodString>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>;
+  execute: (args: z.infer<typeof previewInputSchema>) => Promise<{
+    content: Array<{
+      type: "text";
+      text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+  }>;
+};
+//#endregion
+export { xuluxTemplateDetailsTool, xuluxTemplatePreviewTool, xuluxTemplatesListTool };
+//# sourceMappingURL=xulux-templates.d.ts.map

package/dist/tools/xulux-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xulux-templates.d.ts","names":[],"sources":["../../src/tools/xulux-templates.ts"],"mappings":";;cAUM,kBAAgB,EAAA,cAAA,EAAA,KAAA;cAEhB,oBAAkB,EAAA;;;GAQtB,EAAA,KAAA;cAEI,oBAAkB,EAAA;;;;GActB,EAAA,KAAA;cAeW;;;;EAQY,UAAA,OAAA,EAAE,aAAa,sBAAiB;;;;;;;;cAiB5C;;;;;;;EASW,UAAA,MAAA,EAAE,aAAa,wBAAmB;;;;;;;;cAwB7C;;;;;;;;EASW,UAAA,MAAA,EAAE,aAAa,wBAAmB"}

package/dist/tools/xulux-templates.js

@@ -0,0 +1,82 @@
+import { logger } from "../utils/logger.js";
+import { formatMCPResponse } from "../utils/mcp-format.js";
+import { getXuluxCatalog } from "../xulux/catalog-client.js";
+import { createTemplatePreview, getTemplateDetails, listTemplates } from "../xulux/template-service.js";
+import { z } from "zod";
+//#region src/tools/xulux-templates.ts
+const emptyInputSchema = z.object({});
+const detailsInputSchema = z.object({
+	templateId: z.string().describe("The template id from assistantUITemplates"),
+	versionId: z.string().optional().describe("Optional version id. When provided, exampleConfig reflects that version's resolved defaults.")
+});
+const previewInputSchema = z.object({
+	templateId: z.string().describe("The template id from assistantUITemplates"),
+	versionId: z.string().optional().describe("Version id to use. Uses the template default if omitted."),
+	config: z.record(z.string(), z.unknown()).optional().describe("Customization config for the preview. Must contain only the top-level keys: hostUi, assistant, and brandTheme. Use the schemas from assistantUITemplateDetails.configRoots as the source of truth for each root. Do not pass any other root keys.")
+});
+function withDegradedNote(payload, degraded, degradedReason) {
+	if (!degraded) return payload;
+	return {
+		...payload,
+		catalogDegraded: true,
+		...degradedReason ? { catalogDegradedReason: degradedReason } : {}
+	};
+}
+const xuluxTemplatesListTool = {
+	name: "assistantUITemplates",
+	description: "List the available assistant-ui hosted app templates and fixed demos with their features, customizable surfaces, and versions. Call this first for any assistant-ui app-building request. Use the features and customizable fields to decide which template fits. If customizable is empty, the entry is a fixed demo that should be used as-is rather than configured. Call assistantUITemplateDetails on the chosen template before requesting a preview.",
+	parameters: emptyInputSchema,
+	execute: async (_args) => {
+		logger.info("Listing assistant-ui templates");
+		try {
+			const { catalog, degraded, degradedReason } = await getXuluxCatalog();
+			return formatMCPResponse(withDegradedNote(listTemplates(catalog), degraded, degradedReason));
+		} catch (error) {
+			logger.error("Failed to list assistant-ui templates", error);
+			return formatMCPResponse({
+				error: "Failed to list assistant-ui templates",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+};
+const xuluxTemplateDetailsTool = {
+	name: "assistantUITemplateDetails",
+	description: "Get the full authoring surface for a specific assistant-ui hosted template. Returns configRoots schemas (with types, defaults, and enums), rules, built-in tool input/outputShape, renderer contracts, and an exampleConfig. Fixed demos return no configRoots; use those as-is without config. Use this before calling assistantUITemplatePreview to understand exactly what config to write. If assistantUITemplatePreview returns validationWarnings, call this again and cross-reference configRoots to correct the config.",
+	parameters: detailsInputSchema,
+	execute: async (args) => {
+		logger.info(`Getting assistant-ui template details for: ${args.templateId}`);
+		try {
+			const { catalog, degraded, degradedReason } = await getXuluxCatalog();
+			return formatMCPResponse(withDegradedNote(await getTemplateDetails(catalog, args), degraded, degradedReason));
+		} catch (error) {
+			logger.error("Failed to get assistant-ui template details", error);
+			return formatMCPResponse({
+				error: "Failed to get assistant-ui template details",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+};
+const xuluxTemplatePreviewTool = {
+	name: "assistantUITemplatePreview",
+	description: "Return preview and download URLs for a selected assistant-ui hosted template. The previewUrl is a hosted app URL; show it to the user first, or open it with an available browser/in-app-browser tool if your client provides one. If you pass config, a preview session is created on the hosted template sandbox and the returned URLs reflect that configuration. Do not pass config for fixed demos that have no configRoots in assistantUITemplateDetails. This tool only returns URLs.",
+	parameters: previewInputSchema,
+	execute: async (args) => {
+		logger.info(`Creating assistant-ui template preview for: ${args.templateId}`);
+		try {
+			const { catalog, degraded, degradedReason } = await getXuluxCatalog();
+			return formatMCPResponse(withDegradedNote(await createTemplatePreview(catalog, args), degraded, degradedReason));
+		} catch (error) {
+			logger.error("Failed to create assistant-ui template preview", error);
+			return formatMCPResponse({
+				error: "Failed to create assistant-ui template preview",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+};
+//#endregion
+export { xuluxTemplateDetailsTool, xuluxTemplatePreviewTool, xuluxTemplatesListTool };
+
+//# sourceMappingURL=xulux-templates.js.map

package/dist/tools/xulux-templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xulux-templates.js","names":[],"sources":["../../src/tools/xulux-templates.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { logger } from \"../utils/logger.js\";\nimport { formatMCPResponse } from \"../utils/mcp-format.js\";\nimport { getXuluxCatalog } from \"../xulux/catalog-client.js\";\nimport {\n  createTemplatePreview,\n  getTemplateDetails,\n  listTemplates,\n} from \"../xulux/template-service.js\";\n\nconst emptyInputSchema = z.object({});\n\nconst detailsInputSchema = z.object({\n  templateId: z.string().describe(\"The template id from assistantUITemplates\"),\n  versionId: z\n    .string()\n    .optional()\n    .describe(\n      \"Optional version id. When provided, exampleConfig reflects that version's resolved defaults.\",\n    ),\n});\n\nconst previewInputSchema = z.object({\n  templateId: z.string().describe(\"The template id from assistantUITemplates\"),\n  versionId: z\n    .string()\n    .optional()\n    .describe(\"Version id to use. Uses the template default if omitted.\"),\n  config: z\n    .record(z.string(), z.unknown())\n    .optional()\n    .describe(\n      \"Customization config for the preview. Must contain only the top-level keys: hostUi, assistant, and brandTheme. \" +\n        \"Use the schemas from assistantUITemplateDetails.configRoots as the source of truth for each root. \" +\n        \"Do not pass any other root keys.\",\n    ),\n});\n\nfunction withDegradedNote<T extends Record<string, unknown>>(\n  payload: T,\n  degraded: boolean,\n  degradedReason?: string,\n): T & { catalogDegraded?: true; catalogDegradedReason?: string } {\n  if (!degraded) return payload;\n  return {\n    ...payload,\n    catalogDegraded: true,\n    ...(degradedReason ? { catalogDegradedReason: degradedReason } : {}),\n  };\n}\n\nexport const xuluxTemplatesListTool = {\n  name: \"assistantUITemplates\",\n  description:\n    \"List the available assistant-ui hosted app templates and fixed demos with their features, customizable surfaces, and versions. \" +\n    \"Call this first for any assistant-ui app-building request. Use the features and customizable fields to decide which template fits. \" +\n    \"If customizable is empty, the entry is a fixed demo that should be used as-is rather than configured. \" +\n    \"Call assistantUITemplateDetails on the chosen template before requesting a preview.\",\n  parameters: emptyInputSchema,\n  execute: async (_args: z.infer<typeof emptyInputSchema>) => {\n    logger.info(\"Listing assistant-ui templates\");\n    try {\n      const { catalog, degraded, degradedReason } = await getXuluxCatalog();\n      return formatMCPResponse(\n        withDegradedNote(listTemplates(catalog), degraded, degradedReason),\n      );\n    } catch (error) {\n      logger.error(\"Failed to list assistant-ui templates\", error);\n      return formatMCPResponse({\n        error: \"Failed to list assistant-ui templates\",\n        message: error instanceof Error ? error.message : String(error),\n      });\n    }\n  },\n};\n\nexport const xuluxTemplateDetailsTool = {\n  name: \"assistantUITemplateDetails\",\n  description:\n    \"Get the full authoring surface for a specific assistant-ui hosted template. \" +\n    \"Returns configRoots schemas (with types, defaults, and enums), rules, built-in tool input/outputShape, renderer contracts, and an exampleConfig. \" +\n    \"Fixed demos return no configRoots; use those as-is without config. \" +\n    \"Use this before calling assistantUITemplatePreview to understand exactly what config to write. \" +\n    \"If assistantUITemplatePreview returns validationWarnings, call this again and cross-reference configRoots to correct the config.\",\n  parameters: detailsInputSchema,\n  execute: async (args: z.infer<typeof detailsInputSchema>) => {\n    logger.info(\n      `Getting assistant-ui template details for: ${args.templateId}`,\n    );\n    try {\n      const { catalog, degraded, degradedReason } = await getXuluxCatalog();\n      const details = await getTemplateDetails(catalog, args);\n      return formatMCPResponse(\n        withDegradedNote(\n          details as unknown as Record<string, unknown>,\n          degraded,\n          degradedReason,\n        ),\n      );\n    } catch (error) {\n      logger.error(\"Failed to get assistant-ui template details\", error);\n      return formatMCPResponse({\n        error: \"Failed to get assistant-ui template details\",\n        message: error instanceof Error ? error.message : String(error),\n      });\n    }\n  },\n};\n\nexport const xuluxTemplatePreviewTool = {\n  name: \"assistantUITemplatePreview\",\n  description:\n    \"Return preview and download URLs for a selected assistant-ui hosted template. \" +\n    \"The previewUrl is a hosted app URL; show it to the user first, or open it with an available browser/in-app-browser tool if your client provides one. \" +\n    \"If you pass config, a preview session is created on the hosted template sandbox and the returned URLs reflect that configuration. \" +\n    \"Do not pass config for fixed demos that have no configRoots in assistantUITemplateDetails. \" +\n    \"This tool only returns URLs.\",\n  parameters: previewInputSchema,\n  execute: async (args: z.infer<typeof previewInputSchema>) => {\n    logger.info(\n      `Creating assistant-ui template preview for: ${args.templateId}`,\n    );\n    try {\n      const { catalog, degraded, degradedReason } = await getXuluxCatalog();\n      const result = await createTemplatePreview(catalog, args);\n      return formatMCPResponse(\n        withDegradedNote(\n          result as unknown as Record<string, unknown>,\n          degraded,\n          degradedReason,\n        ),\n      );\n    } catch (error) {\n      logger.error(\"Failed to create assistant-ui template preview\", error);\n      return formatMCPResponse({\n        error: \"Failed to create assistant-ui template preview\",\n        message: error instanceof Error ? error.message : String(error),\n      });\n    }\n  },\n};\n"],"mappings":";;;;;;AAUA,MAAM,mBAAmB,EAAE,OAAO,CAAC,CAAC;AAEpC,MAAM,qBAAqB,EAAE,OAAO;CAClC,YAAY,EAAE,OAAO,CAAC,CAAC,SAAS,2CAA2C;CAC3E,WAAW,EACR,OAAO,CAAC,CACR,SAAS,CAAC,CACV,SACC,8FACF;AACJ,CAAC;AAED,MAAM,qBAAqB,EAAE,OAAO;CAClC,YAAY,EAAE,OAAO,CAAC,CAAC,SAAS,2CAA2C;CAC3E,WAAW,EACR,OAAO,CAAC,CACR,SAAS,CAAC,CACV,SAAS,0DAA0D;CACtE,QAAQ,EACL,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAC/B,SAAS,CAAC,CACV,SACC,mPAGF;AACJ,CAAC;AAED,SAAS,iBACP,SACA,UACA,gBACgE;CAChE,IAAI,CAAC,UAAU,OAAO;CACtB,OAAO;EACL,GAAG;EACH,iBAAiB;EACjB,GAAI,iBAAiB,EAAE,uBAAuB,eAAe,IAAI,CAAC;CACpE;AACF;AAEA,MAAa,yBAAyB;CACpC,MAAM;CACN,aACE;CAIF,YAAY;CACZ,SAAS,OAAO,UAA4C;EAC1D,OAAO,KAAK,gCAAgC;EAC5C,IAAI;GACF,MAAM,EAAE,SAAS,UAAU,mBAAmB,MAAM,gBAAgB;GACpE,OAAO,kBACL,iBAAiB,cAAc,OAAO,GAAG,UAAU,cAAc,CACnE;EACF,SAAS,OAAO;GACd,OAAO,MAAM,yCAAyC,KAAK;GAC3D,OAAO,kBAAkB;IACvB,OAAO;IACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAChE,CAAC;EACH;CACF;AACF;AAEA,MAAa,2BAA2B;CACtC,MAAM;CACN,aACE;CAKF,YAAY;CACZ,SAAS,OAAO,SAA6C;EAC3D,OAAO,KACL,8CAA8C,KAAK,YACrD;EACA,IAAI;GACF,MAAM,EAAE,SAAS,UAAU,mBAAmB,MAAM,gBAAgB;GAEpE,OAAO,kBACL,iBACE,MAHkB,mBAAmB,SAAS,IAAI,GAIlD,UACA,cACF,CACF;EACF,SAAS,OAAO;GACd,OAAO,MAAM,+CAA+C,KAAK;GACjE,OAAO,kBAAkB;IACvB,OAAO;IACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAChE,CAAC;EACH;CACF;AACF;AAEA,MAAa,2BAA2B;CACtC,MAAM;CACN,aACE;CAKF,YAAY;CACZ,SAAS,OAAO,SAA6C;EAC3D,OAAO,KACL,+CAA+C,KAAK,YACtD;EACA,IAAI;GACF,MAAM,EAAE,SAAS,UAAU,mBAAmB,MAAM,gBAAgB;GAEpE,OAAO,kBACL,iBACE,MAHiB,sBAAsB,SAAS,IAAI,GAIpD,UACA,cACF,CACF;EACF,SAAS,OAAO;GACd,OAAO,MAAM,kDAAkD,KAAK;GACpE,OAAO,kBAAkB;IACvB,OAAO;IACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAChE,CAAC;EACH;CACF;AACF"}

package/dist/utils/cache.d.ts

@@ -0,0 +1,5 @@
+//#region src/utils/cache.d.ts
+declare function cacheListing(scan: () => Promise<string[]>): () => Promise<string[]>;
+//#endregion
+export { cacheListing };
+//# sourceMappingURL=cache.d.ts.map

package/dist/utils/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","names":[],"sources":["../../src/utils/cache.ts"],"mappings":";iBAAgB,aACd,YAAY,0BACL"}

package/dist/utils/cache.js

@@ -0,0 +1,18 @@
+//#region src/utils/cache.ts
+function cacheListing(scan) {
+	let cache = null;
+	return () => {
+		if (!cache) cache = scan().then((result) => {
+			if (result.length === 0) cache = null;
+			return result;
+		}, (error) => {
+			cache = null;
+			throw error;
+		});
+		return cache;
+	};
+}
+//#endregion
+export { cacheListing };
+
+//# sourceMappingURL=cache.js.map

package/dist/utils/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","names":[],"sources":["../../src/utils/cache.ts"],"sourcesContent":["export function cacheListing(\n  scan: () => Promise<string[]>,\n): () => Promise<string[]> {\n  let cache: Promise<string[]> | null = null;\n  return () => {\n    if (!cache) {\n      cache = scan().then(\n        (result) => {\n          if (result.length === 0) cache = null;\n          return result;\n        },\n        (error) => {\n          cache = null;\n          throw error;\n        },\n      );\n    }\n    return cache;\n  };\n}\n"],"mappings":";AAAA,SAAgB,aACd,MACyB;CACzB,IAAI,QAAkC;CACtC,aAAa;EACX,IAAI,CAAC,OACH,QAAQ,KAAK,CAAC,CAAC,MACZ,WAAW;GACV,IAAI,OAAO,WAAW,GAAG,QAAQ;GACjC,OAAO;EACT,IACC,UAAU;GACT,QAAQ;GACR,MAAM;EACR,CACF;EAEF,OAAO;CACT;AACF"}

package/dist/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","names":[],"sources":["../../src/utils/logger.ts"],"mappings":";cAEa,MAAA;8BACY,IAAA;6BAKD,IAAA;8BAKC,IAAA;6BAGD,IAAA;AAAA"}
+{"version":3,"file":"logger.d.ts","names":[],"sources":["../../src/utils/logger.ts"],"mappings":";cAEa;EACM,QAAA,oBAAM;EAKP,OAAA,oBAAM;EAKL,QAAA,oBAAM;EAGP,OAAA,oBAAM"}

package/dist/utils/mcp-format.d.ts

@@ -4,6 +4,7 @@ declare function formatMCPResponse(data: any): {
     type: "text";
     text: string;
   }>;
+  structuredContent?: Record<string, unknown>;
 };
 //#endregion
 export { formatMCPResponse };

package/dist/utils/mcp-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-format.d.ts","names":[],"sources":["../../src/utils/mcp-format.ts"],"mappings":";iBAAgB,iBAAA,CAAkB,IAAA;EAChC,OAAA,EAAS,KAAK;IAAG,IAAA;IAAc,IAAA;EAAA;AAAA"}
+{"version":3,"file":"mcp-format.d.ts","names":[],"sources":["../../src/utils/mcp-format.ts"],"mappings":";iBAAgB,kBAAkB;EAChC,SAAS;IAAQ;IAAc;;EAC/B,oBAAoB"}

package/dist/utils/mcp-format.js

@@ -1,9 +1,12 @@
 //#region src/utils/mcp-format.ts
 function formatMCPResponse(data) {
-	return { content: [{
-		type: "text",
-		text: typeof data === "string" ? data : JSON.stringify(data, null, 2)
-	}] };
+	return {
+		content: [{
+			type: "text",
+			text: typeof data === "string" ? data : JSON.stringify(data, null, 2)
+		}],
+		...typeof data === "object" && data !== null && !Array.isArray(data) && { structuredContent: data }
+	};
 }
 //#endregion
 export { formatMCPResponse };

package/dist/utils/mcp-format.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-format.js","names":[],"sources":["../../src/utils/mcp-format.ts"],"sourcesContent":["export function formatMCPResponse(data: any): {\n  content: Array<{ type: \"text\"; text: string }>;\n} {\n  return {\n    content: [\n      {\n        type: \"text\",\n        text: typeof data === \"string\" ? data : JSON.stringify(data, null, 2),\n      },\n    ],\n  };\n}\n"],"mappings":";AAAA,SAAgB,kBAAkB,MAEhC;CACA,OAAO,EACL,SAAS,CACP;EACE,MAAM;EACN,MAAM,OAAO,SAAS,WAAW,OAAO,KAAK,UAAU,MAAM,MAAM,CAAC;CACtE,CACF,EACF;AACF"}
+{"version":3,"file":"mcp-format.js","names":[],"sources":["../../src/utils/mcp-format.ts"],"sourcesContent":["export function formatMCPResponse(data: any): {\n  content: Array<{ type: \"text\"; text: string }>;\n  structuredContent?: Record<string, unknown>;\n} {\n  const text = typeof data === \"string\" ? data : JSON.stringify(data, null, 2);\n  const isStructured =\n    typeof data === \"object\" && data !== null && !Array.isArray(data);\n  return {\n    content: [{ type: \"text\", text }],\n    ...(isStructured && {\n      structuredContent: data as Record<string, unknown>,\n    }),\n  };\n}\n"],"mappings":";AAAA,SAAgB,kBAAkB,MAGhC;CAIA,OAAO;EACL,SAAS,CAAC;GAAE,MAAM;GAAQ,MAJf,OAAO,SAAS,WAAW,OAAO,KAAK,UAAU,MAAM,MAAM,CAAC;EAI1C,CAAC;EAChC,GAHA,OAAO,SAAS,YAAY,SAAS,QAAQ,CAAC,MAAM,QAAQ,IAAI,KAG5C,EAClB,mBAAmB,KACrB;CACF;AACF"}

package/dist/utils/mdx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mdx.d.ts","names":[],"sources":["../../src/utils/mdx.ts"],"mappings":";UAKU,UAAA;EACR,OAAA;EACA,WAAA,EAAa,MAAM;EACnB,OAAA;AAAA;AAAA,iBAGoB,WAAA,CACpB,QAAA,WACC,OAAO,CAAC,UAAA;AAAA,iBAsBW,eAAA,CACpB,QAAA,WACC,OAAO,CAAC,UAAA;AAAA,iBAiBK,gBAAA,CAAiB,UAAsB,EAAV,UAAU"}
+{"version":3,"file":"mdx.d.ts","names":[],"sources":["../../src/utils/mdx.ts"],"mappings":";UAKU;EACR;EACA,aAAa;EACb;;iBAGoB,YACpB,mBACC,QAAQ;iBAsBW,gBACpB,mBACC,QAAQ;iBAiBK,iBAAiB,YAAY"}

package/dist/utils/paths.d.ts

@@ -4,7 +4,7 @@ declare function listDirContents(dirPath: string): Promise<{
   files: string[];
 }>;
 declare function getAvailablePaths(): Promise<string[]>;
-declare function getAvailableDocFiles(): Promise<string[]>;
+declare const getAvailableDocFiles: () => Promise<string[]>;
 declare function findNearestPaths(requestedPath: string, availablePaths: string[]): string[];
 declare function pathExists(path: string): Promise<boolean>;
 //#endregion

package/dist/utils/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","names":[],"sources":["../../src/utils/paths.ts"],"mappings":";iBAYsB,eAAA,CAAgB,OAAA,WAAkB,OAAO;EAC7D,WAAA;EACA,KAAA;AAAA;AAAA,iBA4BoB,iBAAA,IAAqB,OAAO;AAAA,iBA0B5B,oBAAA,IAAwB,OAAO;AAAA,iBAsBrC,gBAAA,CACd,aAAA,UACA,cAAwB;AAAA,iBAoCJ,UAAA,CAAW,IAAA,WAAe,OAAO"}
+{"version":3,"file":"paths.d.ts","names":[],"sources":["../../src/utils/paths.ts"],"mappings":";iBAasB,gBAAgB,kBAAkB;EACtD;EACA;;iBA4BoB,qBAAqB;cA0B9B,4BAAoB;iBAwBjB,iBACd,uBACA;iBAoCoB,WAAW,eAAe"}

package/dist/utils/paths.js

@@ -1,5 +1,6 @@
 import { DOCS_PATH, MDX_EXTENSION } from "../constants.js";
 import { logger } from "./logger.js";
+import { cacheListing } from "./cache.js";
 import { extname, join } from "node:path";
 import { readdir, stat } from "node:fs/promises";
 //#region src/utils/paths.ts
@@ -42,7 +43,8 @@ async function getAvailablePaths() {
 	await scanDirectory(DOCS_PATH);
 	return paths.sort();
 }
-async function getAvailableDocFiles() {
+const getAvailableDocFiles = cacheListing(scanDocFiles);
+async function scanDocFiles() {
 	const files = [];
 	async function scanDirectory(dir, prefix = "") {
 		const { directories, files: dirFiles } = await listDirContents(dir);

package/dist/utils/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","names":[],"sources":["../../src/utils/paths.ts"],"sourcesContent":["import { readdir, stat } from \"node:fs/promises\";\nimport { join, extname } from \"node:path\";\nimport { DOCS_PATH, MDX_EXTENSION, MD_EXTENSION } from \"../constants.js\";\nimport { logger } from \"./logger.js\";\n\nconst SIMILARITY_THRESHOLDS = {\n  EXACT_MATCH: 1,\n  CONTAINS_MATCH: 0.8,\n  PARTIAL_MATCH: 0.5,\n  MIN_SUGGESTION: 0.3,\n} as const;\n\nexport async function listDirContents(dirPath: string): Promise<{\n  directories: string[];\n  files: string[];\n}> {\n  try {\n    const items = await readdir(dirPath, { withFileTypes: true });\n\n    const directories = items\n      .filter((item) => item.isDirectory())\n      .map((item) => item.name)\n      .filter((name) => !name.startsWith(\".\"))\n      .sort();\n\n    const files = items\n      .filter(\n        (item) =>\n          item.isFile() &&\n          (extname(item.name) === MDX_EXTENSION ||\n            extname(item.name) === MD_EXTENSION),\n      )\n      .map((item) => item.name)\n      .sort();\n\n    return { directories, files };\n  } catch (error) {\n    logger.error(`Failed to list directory contents: ${dirPath}`, error);\n    return { directories: [], files: [] };\n  }\n}\n\nexport async function getAvailablePaths(): Promise<string[]> {\n  const paths: string[] = [];\n\n  async function scanDirectory(\n    dir: string,\n    prefix: string = \"\",\n  ): Promise<void> {\n    const { directories, files } = await listDirContents(dir);\n\n    for (const file of files) {\n      const name = file.replace(MDX_EXTENSION, \"\").replace(MD_EXTENSION, \"\");\n      paths.push(prefix ? `${prefix}/${name}` : name);\n    }\n\n    for (const subdir of directories) {\n      const subdirPath = join(dir, subdir);\n      const newPrefix = prefix ? `${prefix}/${subdir}` : subdir;\n      paths.push(newPrefix);\n      await scanDirectory(subdirPath, newPrefix);\n    }\n  }\n\n  await scanDirectory(DOCS_PATH);\n  return paths.sort();\n}\n\nexport async function getAvailableDocFiles(): Promise<string[]> {\n  const files: string[] = [];\n\n  async function scanDirectory(dir: string, prefix = \"\"): Promise<void> {\n    const { directories, files: dirFiles } = await listDirContents(dir);\n\n    for (const file of dirFiles) {\n      if (extname(file) !== MDX_EXTENSION) continue;\n      const name = file.replace(MDX_EXTENSION, \"\");\n      files.push(prefix ? `${prefix}/${name}` : name);\n    }\n\n    for (const subdir of directories) {\n      const newPrefix = prefix ? `${prefix}/${subdir}` : subdir;\n      await scanDirectory(join(dir, subdir), newPrefix);\n    }\n  }\n\n  await scanDirectory(DOCS_PATH);\n  return files.sort();\n}\n\nexport function findNearestPaths(\n  requestedPath: string,\n  availablePaths: string[],\n): string[] {\n  const normalizedRequest = requestedPath\n    .toLowerCase()\n    .replace(/[^a-z0-9]/g, \"\");\n\n  const scored = availablePaths.map((path) => {\n    const normalizedPath = path.toLowerCase().replace(/[^a-z0-9]/g, \"\");\n\n    if (normalizedPath.includes(normalizedRequest)) {\n      return { path, score: SIMILARITY_THRESHOLDS.EXACT_MATCH };\n    }\n\n    if (normalizedRequest.includes(normalizedPath)) {\n      return { path, score: SIMILARITY_THRESHOLDS.CONTAINS_MATCH };\n    }\n\n    const overlap = [...normalizedRequest].filter((char) =>\n      normalizedPath.includes(char),\n    ).length;\n\n    return {\n      path,\n      score:\n        (overlap / normalizedRequest.length) *\n        SIMILARITY_THRESHOLDS.PARTIAL_MATCH,\n    };\n  });\n\n  return scored\n    .filter((item) => item.score > SIMILARITY_THRESHOLDS.MIN_SUGGESTION)\n    .sort((a, b) => b.score - a.score)\n    .slice(0, 3)\n    .map((item) => item.path);\n}\n\nexport async function pathExists(path: string): Promise<boolean> {\n  try {\n    await stat(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"paths.js","names":[],"sources":["../../src/utils/paths.ts"],"sourcesContent":["import { readdir, stat } from \"node:fs/promises\";\nimport { join, extname } from \"node:path\";\nimport { DOCS_PATH, MDX_EXTENSION, MD_EXTENSION } from \"../constants.js\";\nimport { cacheListing } from \"./cache.js\";\nimport { logger } from \"./logger.js\";\n\nconst SIMILARITY_THRESHOLDS = {\n  EXACT_MATCH: 1,\n  CONTAINS_MATCH: 0.8,\n  PARTIAL_MATCH: 0.5,\n  MIN_SUGGESTION: 0.3,\n} as const;\n\nexport async function listDirContents(dirPath: string): Promise<{\n  directories: string[];\n  files: string[];\n}> {\n  try {\n    const items = await readdir(dirPath, { withFileTypes: true });\n\n    const directories = items\n      .filter((item) => item.isDirectory())\n      .map((item) => item.name)\n      .filter((name) => !name.startsWith(\".\"))\n      .sort();\n\n    const files = items\n      .filter(\n        (item) =>\n          item.isFile() &&\n          (extname(item.name) === MDX_EXTENSION ||\n            extname(item.name) === MD_EXTENSION),\n      )\n      .map((item) => item.name)\n      .sort();\n\n    return { directories, files };\n  } catch (error) {\n    logger.error(`Failed to list directory contents: ${dirPath}`, error);\n    return { directories: [], files: [] };\n  }\n}\n\nexport async function getAvailablePaths(): Promise<string[]> {\n  const paths: string[] = [];\n\n  async function scanDirectory(\n    dir: string,\n    prefix: string = \"\",\n  ): Promise<void> {\n    const { directories, files } = await listDirContents(dir);\n\n    for (const file of files) {\n      const name = file.replace(MDX_EXTENSION, \"\").replace(MD_EXTENSION, \"\");\n      paths.push(prefix ? `${prefix}/${name}` : name);\n    }\n\n    for (const subdir of directories) {\n      const subdirPath = join(dir, subdir);\n      const newPrefix = prefix ? `${prefix}/${subdir}` : subdir;\n      paths.push(newPrefix);\n      await scanDirectory(subdirPath, newPrefix);\n    }\n  }\n\n  await scanDirectory(DOCS_PATH);\n  return paths.sort();\n}\n\nexport const getAvailableDocFiles = cacheListing(scanDocFiles);\n\nasync function scanDocFiles(): Promise<string[]> {\n  const files: string[] = [];\n\n  async function scanDirectory(dir: string, prefix = \"\"): Promise<void> {\n    const { directories, files: dirFiles } = await listDirContents(dir);\n\n    for (const file of dirFiles) {\n      if (extname(file) !== MDX_EXTENSION) continue;\n      const name = file.replace(MDX_EXTENSION, \"\");\n      files.push(prefix ? `${prefix}/${name}` : name);\n    }\n\n    for (const subdir of directories) {\n      const newPrefix = prefix ? `${prefix}/${subdir}` : subdir;\n      await scanDirectory(join(dir, subdir), newPrefix);\n    }\n  }\n\n  await scanDirectory(DOCS_PATH);\n  return files.sort();\n}\n\nexport function findNearestPaths(\n  requestedPath: string,\n  availablePaths: string[],\n): string[] {\n  const normalizedRequest = requestedPath\n    .toLowerCase()\n    .replace(/[^a-z0-9]/g, \"\");\n\n  const scored = availablePaths.map((path) => {\n    const normalizedPath = path.toLowerCase().replace(/[^a-z0-9]/g, \"\");\n\n    if (normalizedPath.includes(normalizedRequest)) {\n      return { path, score: SIMILARITY_THRESHOLDS.EXACT_MATCH };\n    }\n\n    if (normalizedRequest.includes(normalizedPath)) {\n      return { path, score: SIMILARITY_THRESHOLDS.CONTAINS_MATCH };\n    }\n\n    const overlap = [...normalizedRequest].filter((char) =>\n      normalizedPath.includes(char),\n    ).length;\n\n    return {\n      path,\n      score:\n        (overlap / normalizedRequest.length) *\n        SIMILARITY_THRESHOLDS.PARTIAL_MATCH,\n    };\n  });\n\n  return scored\n    .filter((item) => item.score > SIMILARITY_THRESHOLDS.MIN_SUGGESTION)\n    .sort((a, b) => b.score - a.score)\n    .slice(0, 3)\n    .map((item) => item.path);\n}\n\nexport async function pathExists(path: string): Promise<boolean> {\n  try {\n    await stat(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":"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"}

package/dist/utils/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","names":[],"sources":["../../src/utils/search.ts"],"mappings":";UAkBiB,YAAA;EACf,IAAA;EACA,KAAA;EACA,OAAA;AAAA;AAAA,iBA0FoB,UAAA,CACpB,KAAA,UACA,KAAA,YACC,OAAO,CAAC,YAAA"}
+{"version":3,"file":"search.d.ts","names":[],"sources":["../../src/utils/search.ts"],"mappings":";UAkBiB;EACf;EACA;EACA;;iBA0FoB,WACpB,eACA,iBACC,QAAQ"}

package/dist/utils/security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security.d.ts","names":[],"sources":["../../src/utils/security.ts"],"mappings":";iBAEgB,YAAA,CAAa,QAAgB"}
+{"version":3,"file":"security.d.ts","names":[],"sources":["../../src/utils/security.ts"],"mappings":";iBAEgB,aAAa"}

package/dist/utils/security.js.map

@@ -1 +1 @@
-{"version":3,"file":"security.js","names":[],"sources":["../../src/utils/security.ts"],"sourcesContent":["import path from \"node:path\";\n\nexport function sanitizePath(userPath: string): string {\n  if (!userPath || typeof userPath !== \"string\") {\n    throw new Error(\"Invalid path: Path must be a non-empty string\");\n  }\n\n  // Check for traversal patterns before normalization - defense in depth\n  if (userPath.includes(\"../\") || userPath.includes(\"..\\\\\")) {\n    throw new Error(\"Invalid path: Directory traversal attempt detected\");\n  }\n\n  const normalized = path.normalize(userPath);\n\n  if (path.isAbsolute(normalized)) {\n    throw new Error(\"Invalid path: Absolute paths are not allowed\");\n  }\n\n  const relativePath = path.relative(\"\", normalized);\n\n  if (relativePath.startsWith(\"..\")) {\n    throw new Error(\"Invalid path: Directory traversal attempt detected\");\n  }\n\n  if (relativePath.includes(\"..\")) {\n    throw new Error(\"Invalid path: Path contains invalid traversal sequences\");\n  }\n\n  if (relativePath.includes(\"\\0\")) {\n    throw new Error(\"Invalid path: Path contains null bytes\");\n  }\n\n  if (process.platform !== \"win32\") {\n    if (normalized.includes(\"\\\\\")) {\n      throw new Error(\"Invalid path: Backslashes not allowed\");\n    }\n  } else {\n    if (normalized.includes(\":\") || normalized.startsWith(\"\\\\\\\\\")) {\n      throw new Error(\"Invalid path: Path contains invalid Windows characters\");\n    }\n  }\n\n  const segments = relativePath.split(path.sep);\n  for (const segment of segments) {\n    if (segment.startsWith(\".\") && segment !== \".\") {\n      throw new Error(\"Invalid path: Hidden files are not allowed\");\n    }\n  }\n\n  // Always return Unix-style paths for consistency across platforms\n  return relativePath.replace(/\\\\/g, \"/\");\n}\n"],"mappings":";;AAEA,SAAgB,aAAa,UAA0B;CACrD,IAAI,CAAC,YAAY,OAAO,aAAa,UACnC,MAAM,IAAI,MAAM,+CAA+C;CAIjE,IAAI,SAAS,SAAS,KAAK,KAAK,SAAS,SAAS,MAAM,GACtD,MAAM,IAAI,MAAM,oDAAoD;CAGtE,MAAM,aAAa,KAAK,UAAU,QAAQ;CAE1C,IAAI,KAAK,WAAW,UAAU,GAC5B,MAAM,IAAI,MAAM,8CAA8C;CAGhE,MAAM,eAAe,KAAK,SAAS,IAAI,UAAU;CAEjD,IAAI,aAAa,WAAW,IAAI,GAC9B,MAAM,IAAI,MAAM,oDAAoD;CAGtE,IAAI,aAAa,SAAS,IAAI,GAC5B,MAAM,IAAI,MAAM,yDAAyD;CAG3E,IAAI,aAAa,SAAS,IAAI,GAC5B,MAAM,IAAI,MAAM,wCAAwC;CAG1D,IAAI,QAAQ,aAAa;MACnB,WAAW,SAAS,IAAI,GAC1B,MAAM,IAAI,MAAM,uCAAuC;CAAA,OAGzD,IAAI,WAAW,SAAS,GAAG,KAAK,WAAW,WAAW,MAAM,GAC1D,MAAM,IAAI,MAAM,wDAAwD;CAI5E,MAAM,WAAW,aAAa,MAAM,KAAK,GAAG;CAC5C,KAAK,MAAM,WAAW,UACpB,IAAI,QAAQ,WAAW,GAAG,KAAK,YAAY,KACzC,MAAM,IAAI,MAAM,4CAA4C;CAKhE,OAAO,aAAa,QAAQ,OAAO,GAAG;AACxC"}
+{"version":3,"file":"security.js","names":[],"sources":["../../src/utils/security.ts"],"sourcesContent":["import path from \"node:path\";\n\nexport function sanitizePath(userPath: string): string {\n  if (!userPath || typeof userPath !== \"string\") {\n    throw new Error(\"Invalid path: Path must be a non-empty string\");\n  }\n\n  // Check for traversal patterns before normalization - defense in depth\n  if (userPath.includes(\"../\") || userPath.includes(\"..\\\\\")) {\n    throw new Error(\"Invalid path: Directory traversal attempt detected\");\n  }\n\n  const normalized = path.normalize(userPath);\n\n  if (path.isAbsolute(normalized)) {\n    throw new Error(\"Invalid path: Absolute paths are not allowed\");\n  }\n\n  const relativePath = path.relative(\"\", normalized);\n\n  if (relativePath.startsWith(\"..\")) {\n    throw new Error(\"Invalid path: Directory traversal attempt detected\");\n  }\n\n  if (relativePath.includes(\"..\")) {\n    throw new Error(\"Invalid path: Path contains invalid traversal sequences\");\n  }\n\n  if (relativePath.includes(\"\\0\")) {\n    throw new Error(\"Invalid path: Path contains null bytes\");\n  }\n\n  if (process.platform !== \"win32\") {\n    if (normalized.includes(\"\\\\\")) {\n      throw new Error(\"Invalid path: Backslashes not allowed\");\n    }\n  } else {\n    if (normalized.includes(\":\") || normalized.startsWith(\"\\\\\\\\\")) {\n      throw new Error(\"Invalid path: Path contains invalid Windows characters\");\n    }\n  }\n\n  const segments = relativePath.split(path.sep);\n  for (const segment of segments) {\n    if (segment.startsWith(\".\") && segment !== \".\") {\n      throw new Error(\"Invalid path: Hidden files are not allowed\");\n    }\n  }\n\n  // Always return Unix-style paths for consistency across platforms\n  return relativePath.replace(/\\\\/g, \"/\");\n}\n"],"mappings":";;AAEA,SAAgB,aAAa,UAA0B;CACrD,IAAI,CAAC,YAAY,OAAO,aAAa,UACnC,MAAM,IAAI,MAAM,+CAA+C;CAIjE,IAAI,SAAS,SAAS,KAAK,KAAK,SAAS,SAAS,MAAM,GACtD,MAAM,IAAI,MAAM,oDAAoD;CAGtE,MAAM,aAAa,KAAK,UAAU,QAAQ;CAE1C,IAAI,KAAK,WAAW,UAAU,GAC5B,MAAM,IAAI,MAAM,8CAA8C;CAGhE,MAAM,eAAe,KAAK,SAAS,IAAI,UAAU;CAEjD,IAAI,aAAa,WAAW,IAAI,GAC9B,MAAM,IAAI,MAAM,oDAAoD;CAGtE,IAAI,aAAa,SAAS,IAAI,GAC5B,MAAM,IAAI,MAAM,yDAAyD;CAG3E,IAAI,aAAa,SAAS,IAAI,GAC5B,MAAM,IAAI,MAAM,wCAAwC;CAG1D,IAAI,QAAQ,aAAa,SACnB;MAAA,WAAW,SAAS,IAAI,GAC1B,MAAM,IAAI,MAAM,uCAAuC;CAAA,OAGzD,IAAI,WAAW,SAAS,GAAG,KAAK,WAAW,WAAW,MAAM,GAC1D,MAAM,IAAI,MAAM,wDAAwD;CAI5E,MAAM,WAAW,aAAa,MAAM,KAAK,GAAG;CAC5C,KAAK,MAAM,WAAW,UACpB,IAAI,QAAQ,WAAW,GAAG,KAAK,YAAY,KACzC,MAAM,IAAI,MAAM,4CAA4C;CAKhE,OAAO,aAAa,QAAQ,OAAO,GAAG;AACxC"}

package/dist/xulux/catalog-client.d.ts

@@ -0,0 +1,14 @@
+import { XuluxCatalogResult } from "./types.js";
+//#region src/xulux/catalog-client.d.ts
+declare const DEFAULT_CATALOG_URL = "https://www.assistant-ui.com/api/xulux/mcp-catalog";
+declare function getCatalogUrl(): string;
+declare function clearCatalogCache(): void;
+/**
+ * Returns the assistant-ui template catalog. Uses an in-memory five-minute cache, and falls
+ * back to a minimal bundled catalog (marked degraded) when the live fetch
+ * fails and no cached copy exists.
+ */
+declare function getXuluxCatalog(): Promise<XuluxCatalogResult>;
+//#endregion
+export { DEFAULT_CATALOG_URL, clearCatalogCache, getCatalogUrl, getXuluxCatalog };
+//# sourceMappingURL=catalog-client.d.ts.map

package/dist/xulux/catalog-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-client.d.ts","names":[],"sources":["../../src/xulux/catalog-client.ts"],"mappings":";;cAIa;iBAKG;iBA0CA;;;;;;iBAoBM,mBAAmB,QAAQ"}

package/dist/xulux/catalog-client.js

@@ -0,0 +1,67 @@
+import { logger } from "../utils/logger.js";
+import { FALLBACK_CATALOG, FALLBACK_NOTE } from "./fallback-catalog.js";
+//#region src/xulux/catalog-client.ts
+const DEFAULT_CATALOG_URL = "https://www.assistant-ui.com/api/xulux/mcp-catalog";
+const CATALOG_TTL_MS = 300 * 1e3;
+function getCatalogUrl() {
+	return process.env.XULUX_CATALOG_URL?.trim() || "https://www.assistant-ui.com/api/xulux/mcp-catalog";
+}
+function validateCatalog(data) {
+	if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error("Catalog response is not a JSON object.");
+	const catalog = data;
+	if (catalog.version !== 1) throw new Error(`Unsupported catalog version: ${String(catalog.version)}. Expected 1.`);
+	if (!Array.isArray(catalog.templates)) throw new Error("Catalog response has no templates array.");
+	for (const template of catalog.templates) if (!template || typeof template !== "object" || typeof template.id !== "string" || typeof template.templateId !== "string" || template.kind !== "template" && template.kind !== "example") throw new Error("Catalog response contains a malformed template entry (missing id/templateId/kind).");
+	return catalog;
+}
+let cache = null;
+function clearCatalogCache() {
+	cache = null;
+}
+async function fetchCatalog(url) {
+	const res = await fetch(url, { headers: { Accept: "application/json" } });
+	if (!res.ok) throw new Error(`Catalog fetch failed: HTTP ${res.status}`);
+	return validateCatalog(await res.json());
+}
+/**
+* Returns the assistant-ui template catalog. Uses an in-memory five-minute cache, and falls
+* back to a minimal bundled catalog (marked degraded) when the live fetch
+* fails and no cached copy exists.
+*/
+async function getXuluxCatalog() {
+	const url = getCatalogUrl();
+	const now = Date.now();
+	if (cache && cache.url === url && now - cache.fetchedAt < CATALOG_TTL_MS) return {
+		catalog: cache.catalog,
+		degraded: false
+	};
+	try {
+		const catalog = await fetchCatalog(url);
+		cache = {
+			catalog,
+			fetchedAt: now,
+			url
+		};
+		return {
+			catalog,
+			degraded: false
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logger.warn(`assistant-ui template catalog fetch failed (${url}): ${message}`);
+		if (cache && cache.url === url) return {
+			catalog: cache.catalog,
+			degraded: true,
+			degradedReason: `Live catalog refresh failed (${message}); using previously fetched catalog.`
+		};
+		return {
+			catalog: FALLBACK_CATALOG,
+			degraded: true,
+			degradedReason: `${message} ${FALLBACK_NOTE}`
+		};
+	}
+}
+//#endregion
+export { DEFAULT_CATALOG_URL, clearCatalogCache, getCatalogUrl, getXuluxCatalog };
+
+//# sourceMappingURL=catalog-client.js.map

package/dist/xulux/catalog-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-client.js","names":[],"sources":["../../src/xulux/catalog-client.ts"],"sourcesContent":["import { logger } from \"../utils/logger.js\";\nimport { FALLBACK_CATALOG, FALLBACK_NOTE } from \"./fallback-catalog.js\";\nimport type { XuluxCatalog, XuluxCatalogResult } from \"./types.js\";\n\nexport const DEFAULT_CATALOG_URL =\n  \"https://www.assistant-ui.com/api/xulux/mcp-catalog\";\n\nconst CATALOG_TTL_MS = 5 * 60 * 1000;\n\nexport function getCatalogUrl(): string {\n  const override = process.env.XULUX_CATALOG_URL?.trim();\n  return override || DEFAULT_CATALOG_URL;\n}\n\nfunction validateCatalog(data: unknown): XuluxCatalog {\n  if (!data || typeof data !== \"object\" || Array.isArray(data)) {\n    throw new Error(\"Catalog response is not a JSON object.\");\n  }\n  const catalog = data as XuluxCatalog;\n  if (catalog.version !== 1) {\n    throw new Error(\n      `Unsupported catalog version: ${String(catalog.version)}. Expected 1.`,\n    );\n  }\n  if (!Array.isArray(catalog.templates)) {\n    throw new Error(\"Catalog response has no templates array.\");\n  }\n  for (const template of catalog.templates) {\n    if (\n      !template ||\n      typeof template !== \"object\" ||\n      typeof template.id !== \"string\" ||\n      typeof template.templateId !== \"string\" ||\n      (template.kind !== \"template\" && template.kind !== \"example\")\n    ) {\n      throw new Error(\n        \"Catalog response contains a malformed template entry (missing id/templateId/kind).\",\n      );\n    }\n  }\n  return catalog;\n}\n\ninterface CacheEntry {\n  catalog: XuluxCatalog;\n  fetchedAt: number;\n  url: string;\n}\n\nlet cache: CacheEntry | null = null;\n\nexport function clearCatalogCache(): void {\n  cache = null;\n}\n\nasync function fetchCatalog(url: string): Promise<XuluxCatalog> {\n  const res = await fetch(url, {\n    headers: { Accept: \"application/json\" },\n  });\n  if (!res.ok) {\n    throw new Error(`Catalog fetch failed: HTTP ${res.status}`);\n  }\n  const data: unknown = await res.json();\n  return validateCatalog(data);\n}\n\n/**\n * Returns the assistant-ui template catalog. Uses an in-memory five-minute cache, and falls\n * back to a minimal bundled catalog (marked degraded) when the live fetch\n * fails and no cached copy exists.\n */\nexport async function getXuluxCatalog(): Promise<XuluxCatalogResult> {\n  const url = getCatalogUrl();\n  const now = Date.now();\n\n  if (cache && cache.url === url && now - cache.fetchedAt < CATALOG_TTL_MS) {\n    return { catalog: cache.catalog, degraded: false };\n  }\n\n  try {\n    const catalog = await fetchCatalog(url);\n    cache = { catalog, fetchedAt: now, url };\n    return { catalog, degraded: false };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    logger.warn(\n      `assistant-ui template catalog fetch failed (${url}): ${message}`,\n    );\n\n    // Prefer a stale cached copy over the minimal fallback.\n    if (cache && cache.url === url) {\n      return {\n        catalog: cache.catalog,\n        degraded: true,\n        degradedReason: `Live catalog refresh failed (${message}); using previously fetched catalog.`,\n      };\n    }\n\n    return {\n      catalog: FALLBACK_CATALOG,\n      degraded: true,\n      degradedReason: `${message} ${FALLBACK_NOTE}`,\n    };\n  }\n}\n"],"mappings":";;;AAIA,MAAa,sBACX;AAEF,MAAM,iBAAiB,MAAS;AAEhC,SAAgB,gBAAwB;CAEtC,OADiB,QAAQ,IAAI,mBAAmB,KAAK,KAAA;AAEvD;AAEA,SAAS,gBAAgB,MAA6B;CACpD,IAAI,CAAC,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI,GACzD,MAAM,IAAI,MAAM,wCAAwC;CAE1D,MAAM,UAAU;CAChB,IAAI,QAAQ,YAAY,GACtB,MAAM,IAAI,MACR,gCAAgC,OAAO,QAAQ,OAAO,EAAE,cAC1D;CAEF,IAAI,CAAC,MAAM,QAAQ,QAAQ,SAAS,GAClC,MAAM,IAAI,MAAM,0CAA0C;CAE5D,KAAK,MAAM,YAAY,QAAQ,WAC7B,IACE,CAAC,YACD,OAAO,aAAa,YACpB,OAAO,SAAS,OAAO,YACvB,OAAO,SAAS,eAAe,YAC9B,SAAS,SAAS,cAAc,SAAS,SAAS,WAEnD,MAAM,IAAI,MACR,oFACF;CAGJ,OAAO;AACT;AAQA,IAAI,QAA2B;AAE/B,SAAgB,oBAA0B;CACxC,QAAQ;AACV;AAEA,eAAe,aAAa,KAAoC;CAC9D,MAAM,MAAM,MAAM,MAAM,KAAK,EAC3B,SAAS,EAAE,QAAQ,mBAAmB,EACxC,CAAC;CACD,IAAI,CAAC,IAAI,IACP,MAAM,IAAI,MAAM,8BAA8B,IAAI,QAAQ;CAG5D,OAAO,gBAAgB,MADK,IAAI,KAAK,CACV;AAC7B;;;;;;AAOA,eAAsB,kBAA+C;CACnE,MAAM,MAAM,cAAc;CAC1B,MAAM,MAAM,KAAK,IAAI;CAErB,IAAI,SAAS,MAAM,QAAQ,OAAO,MAAM,MAAM,YAAY,gBACxD,OAAO;EAAE,SAAS,MAAM;EAAS,UAAU;CAAM;CAGnD,IAAI;EACF,MAAM,UAAU,MAAM,aAAa,GAAG;EACtC,QAAQ;GAAE;GAAS,WAAW;GAAK;EAAI;EACvC,OAAO;GAAE;GAAS,UAAU;EAAM;CACpC,SAAS,OAAO;EACd,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACrE,OAAO,KACL,+CAA+C,IAAI,KAAK,SAC1D;EAGA,IAAI,SAAS,MAAM,QAAQ,KACzB,OAAO;GACL,SAAS,MAAM;GACf,UAAU;GACV,gBAAgB,gCAAgC,QAAQ;EAC1D;EAGF,OAAO;GACL,SAAS;GACT,UAAU;GACV,gBAAgB,GAAG,QAAQ,GAAG;EAChC;CACF;AACF"}

package/dist/xulux/fallback-catalog.d.ts

@@ -0,0 +1,7 @@
+import { XuluxCatalog } from "./types.js";
+//#region src/xulux/fallback-catalog.d.ts
+declare const FALLBACK_NOTE: string;
+declare const FALLBACK_CATALOG: XuluxCatalog;
+//#endregion
+export { FALLBACK_CATALOG, FALLBACK_NOTE };
+//# sourceMappingURL=fallback-catalog.d.ts.map

package/dist/xulux/fallback-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-catalog.d.ts","names":[],"sources":["../../src/xulux/fallback-catalog.ts"],"mappings":";;cAWa;cAiBA,kBAAkB"}

package/dist/xulux/fallback-catalog.js

@@ -0,0 +1,47 @@
+import "./types.js";
+//#region src/xulux/fallback-catalog.ts
+const FALLBACK_NOTE = "The live assistant-ui template catalog could not be fetched, so this is minimal bundled fallback data. Template details, previews, and downloads require live catalog access. Check network access to the docs site or set XULUX_CATALOG_URL to a reachable catalog endpoint.";
+const fallbackTemplate = (overrides) => ({
+	templateId: overrides.id,
+	versionId: null,
+	assistantPlacement: "unavailable in fallback mode",
+	features: [],
+	customizable: [],
+	versions: [],
+	...overrides
+});
+const FALLBACK_CATALOG = {
+	version: 1,
+	generatedAt: "fallback",
+	docsOrigin: "https://www.assistant-ui.com",
+	templates: [
+		fallbackTemplate({
+			id: "base-assistant-ui",
+			kind: "template",
+			name: "Configurable Base Assistant UI",
+			summary: "Hosted configurable assistant-ui Base chat template with threads, composer, suggestions, and no-key demo flows."
+		}),
+		fallbackTemplate({
+			id: "webpage-assistant",
+			kind: "template",
+			name: "Webpage with Assistant",
+			summary: "Docs/website layout with a sidebar or modal assistant grounded in configurable pages."
+		}),
+		fallbackTemplate({
+			id: "product-page-assistant",
+			kind: "template",
+			name: "Product Page with Floating Assistant",
+			summary: "Mock product dashboard with a floating modal support assistant and analyze-then-handoff flow."
+		}),
+		fallbackTemplate({
+			id: "expo-react-native",
+			kind: "example",
+			name: "Expo React Native Assistant",
+			summary: "Mobile AI chat app built with Expo and assistant-ui React Native primitives."
+		})
+	]
+};
+//#endregion
+export { FALLBACK_CATALOG, FALLBACK_NOTE };
+
+//# sourceMappingURL=fallback-catalog.js.map