@frontmcp/uipack 1.8.0 → 1.8.2

package/README.md

@@ -125,17 +125,18 @@ const result = await fetcher.fetchBatch({
 
 ### Shell
 
-| Export                                                | Type     | Purpose                                                               |
-| ----------------------------------------------------- | -------- | --------------------------------------------------------------------- |
-| `buildShell(content, config)`                         | function | Main entry point -> `ShellResult`                                     |
-| `buildCSPMetaTag(config?)`                            | function | Generate `<meta>` CSP tag                                             |
-| `buildCSPDirectives(config?)`                         | function | Merge custom domains with defaults                                    |
-| `buildDataInjectionScript(toolName, input?, output?)` | function | `<script>` setting `window.__mcp*` globals                            |
-| `createTemplateHelpers(toolName)`                     | function | `escapeHtml`, `formatDate`, `formatCurrency`, `uniqueId`, `jsonEmbed` |
-| `resolveShellTemplate(opts)`                          | function | Resolve custom shell from npm/URL/inline                              |
-| `applyShellTemplate(template, values)`                | function | Apply values to resolved template                                     |
-| `validateShellTemplate(template)`                     | function | Validate a custom shell template                                      |
-| `DEFAULT_CDN_DOMAINS`                                 | constant | jsDelivr, Cloudflare, Google Fonts                                    |
+| Export                                                       | Type     | Purpose                                                                                         |
+| ------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------- |
+| `buildShell(content, config)`                                | function | Main entry point -> `ShellResult`                                                               |
+| `buildCSPMetaTag(config?)`                                   | function | Generate `<meta>` CSP tag                                                                       |
+| `buildCSPDirectives(config?)`                                | function | Merge custom domains with defaults                                                              |
+| `buildDataInjectionScript(toolName, input?, output?)`        | function | `<script>` setting `window.__mcp*` globals                                                      |
+| `createTemplateHelpers(toolName)`                            | function | `html`, `trustedHtml`, `escapeHtml`, `formatDate`, `formatCurrency`, `uniqueId`, `jsonEmbed`    |
+| `` html`…` ``, `trustedHtml(markup)`, `isTrustedHtml(value)` | function | Build / mark / detect `TrustedHtml` template markup (interpolated values in `html` are escaped) |
+| `resolveShellTemplate(opts)`                                 | function | Resolve custom shell from npm/URL/inline                                                        |
+| `applyShellTemplate(template, values)`                       | function | Apply values to resolved template                                                               |
+| `validateShellTemplate(template)`                            | function | Validate a custom shell template                                                                |
+| `DEFAULT_CDN_DOMAINS`                                        | constant | jsDelivr, Cloudflare, Google Fonts                                                              |
 
 ### Component
 

package/adapters/content-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content-detector.d.ts","sourceRoot":"","sources":["../../src/adapters/content-detector.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAyBzF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAsCrE"}
+{"version":3,"file":"content-detector.d.ts","sourceRoot":"","sources":["../../src/adapters/content-detector.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AA2BzF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAsCrE"}

package/adapters/index.js

@@ -514,8 +514,9 @@ function escapeHtml(str) {
   const s = String(str);
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
 }
-function escapeScriptClose(jsonString) {
-  return jsonString.replace(/<\//g, "<\\/");
+var SCRIPT_UNSAFE_CHARACTERS = /[<>&\u2028\u2029]/g;
+function toUnicodeEscape(character) {
+  return `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`;
 }
 function safeJsonForScript(value) {
   if (value === void 0) {
@@ -531,7 +532,7 @@ function safeJsonForScript(value) {
     if (jsonString === void 0) {
       return "null";
     }
-    return escapeScriptClose(jsonString);
+    return jsonString.replace(SCRIPT_UNSAFE_CHARACTERS, toUnicodeEscape);
   } catch {
     return '{"error":"Value could not be serialized"}';
   }
@@ -1828,14 +1829,16 @@ var REQUIRED_PLACEHOLDERS = ["CONTENT"];
 var OPTIONAL_PLACEHOLDERS = ["CSP", "DATA", "BRIDGE", "TITLE"];
 
 // libs/uipack/src/shell/custom-shell-applier.ts
+var PLACEHOLDER_PATTERN = new RegExp(`\\{\\{(${SHELL_PLACEHOLDER_NAMES.join("|")})\\}\\}`, "g");
+var VALUE_KEYS = {
+  CSP: "csp",
+  DATA: "data",
+  BRIDGE: "bridge",
+  CONTENT: "content",
+  TITLE: "title"
+};
 function applyShellTemplate(template, values) {
-  let result = template;
-  result = result.replaceAll(SHELL_PLACEHOLDERS.CSP, values.csp);
-  result = result.replaceAll(SHELL_PLACEHOLDERS.DATA, values.data);
-  result = result.replaceAll(SHELL_PLACEHOLDERS.BRIDGE, values.bridge);
-  result = result.replaceAll(SHELL_PLACEHOLDERS.CONTENT, values.content);
-  result = result.replaceAll(SHELL_PLACEHOLDERS.TITLE, values.title);
-  return result;
+  return template.replace(PLACEHOLDER_PATTERN, (_token, name) => values[VALUE_KEYS[name]]);
 }
 
 // libs/uipack/src/shell/custom-shell-validator.ts
@@ -1854,6 +1857,29 @@ function validateShellTemplate(template) {
   };
 }
 
+// libs/uipack/src/shell/trusted-html.ts
+var TRUSTED_HTML = /* @__PURE__ */ Symbol.for("@frontmcp/uipack/trusted-html");
+function trustedHtml(markup) {
+  const value = String(markup);
+  return Object.freeze({ [TRUSTED_HTML]: value, toString: () => value });
+}
+function isTrustedHtml(value) {
+  return typeof value === "object" && value !== null && typeof value[TRUSTED_HTML] === "string";
+}
+function interpolate(value) {
+  if (isTrustedHtml(value)) return value[TRUSTED_HTML];
+  if (Array.isArray(value)) return value.map(interpolate).join("");
+  if (value === false) return "";
+  return escapeHtml(value);
+}
+function html(strings, ...values) {
+  let markup = strings[0];
+  for (let index = 0; index < values.length; index++) {
+    markup += interpolate(values[index]) + strings[index + 1];
+  }
+  return trustedHtml(markup);
+}
+
 // libs/uipack/src/shell/data-injector.ts
 function hasSizing(sizing) {
   if (!sizing) return false;
@@ -1907,9 +1933,9 @@ function createTemplateHelpers() {
     uniqueId: (prefix = "mcp") => {
       return `${prefix}-${++_uniqueIdCounter}`;
     },
-    jsonEmbed: (data) => {
-      return escapeScriptClose(JSON.stringify(data));
-    }
+    jsonEmbed: (data) => safeJsonForScript(data),
+    html,
+    trustedHtml
   };
 }
 
@@ -1987,12 +2013,12 @@ function buildShell(content, config) {
     sizing
   });
   if (!withShell) {
-    const html2 = `${dataScript}
+    const html3 = `${dataScript}
 ${content}`;
     return {
-      html: html2,
-      hash: simpleHash(html2),
-      size: Buffer.byteLength(html2, "utf-8")
+      html: html3,
+      hash: simpleHash(html3),
+      size: Buffer.byteLength(html3, "utf-8")
     };
   }
   if (customShell) {
@@ -2025,7 +2051,7 @@ ${content}`;
     const bridgeScript = generateBridgeIIFE({ minify: true });
     headParts.push(`<script>${bridgeScript}</script>`);
   }
-  const html = `<!DOCTYPE html>
+  const html2 = `<!DOCTYPE html>
 <html lang="en">
 <head>
 ${headParts.map((p) => `  ${p}`).join("\n")}
@@ -2035,9 +2061,9 @@ ${content}
 </body>
 </html>`;
   return {
-    html,
-    hash: simpleHash(html),
-    size: Buffer.byteLength(html, "utf-8")
+    html: html2,
+    hash: simpleHash(html2),
+    size: Buffer.byteLength(html2, "utf-8")
   };
 }
 function buildCustomShell(content, customShell, ctx) {
@@ -2070,7 +2096,7 @@ ${sizingStyle}` : dataScript;
     const bridgeScript = generateBridgeIIFE({ minify: true });
     bridgeHtml = `<script>${bridgeScript}</script>`;
   }
-  const html = applyShellTemplate(template, {
+  const html2 = applyShellTemplate(template, {
     csp: cspTag,
     data: dataWithSizing,
     bridge: bridgeHtml,
@@ -2078,9 +2104,9 @@ ${sizingStyle}` : dataScript;
     title: ctx.title ? escapeHtmlForTag(ctx.title) : ""
   });
   return {
-    html,
-    hash: simpleHash(html),
-    size: Buffer.byteLength(html, "utf-8")
+    html: html2,
+    hash: simpleHash(html2),
+    size: Buffer.byteLength(html2, "utf-8")
   };
 }
 function simpleHash(str) {
@@ -2377,10 +2403,10 @@ function resolveFileSource(source, options = {}) {
   };
 }
 function resolveFunctionSource(source, input, output) {
-  const html = source(input, output);
+  const html2 = source(input, output);
   return {
     mode: "inline",
-    html,
+    html: html2,
     exportName: "default",
     meta: { mcpAware: false, renderer: "html" },
     peerDependencies: []
@@ -2585,6 +2611,7 @@ var MERMAID_PREFIXES = [
   "xychart"
 ];
 var PDF_MAGIC = "JVBERi";
+var BASE64_PATTERN = /^[A-Za-z0-9+/=\r\n]+$/;
 function detectContentType(value) {
   if (value === null || value === void 0) {
     return "text";
@@ -2599,7 +2626,7 @@ function detectContentType(value) {
   if (typeof value === "string") {
     const trimmed = value.trimStart();
     if (trimmed.startsWith(PDF_MAGIC)) {
-      return "pdf";
+      return BASE64_PATTERN.test(trimmed.trimEnd()) ? "pdf" : "text";
     }
     for (const prefix of MERMAID_PREFIXES) {
       if (trimmed.startsWith(prefix)) {
@@ -2661,7 +2688,7 @@ function buildPdfHtml(base64) {
 import * as pdfjsLib from 'https://esm.sh/pdfjs-dist@4/build/pdf.min.mjs';
 pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://esm.sh/pdfjs-dist@4/build/pdf.worker.min.mjs';
 
-const base64 = ${JSON.stringify(base64)};
+const base64 = ${safeJsonForScript(base64)};
 const binaryStr = atob(base64);
 const bytes = new Uint8Array(binaryStr.length);
 for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i);
@@ -2756,6 +2783,30 @@ function buildCspConfig(resolver) {
   }
   return { resourceDomains: cspResourceDomains, connectDomains: cspConnectDomains };
 }
+var STRING_RESULT_DOCS = "https://docs.agentfront.dev/frontmcp/guides/building-tool-ui#trusted-markup";
+var noticedStringResultTools = /* @__PURE__ */ new Set();
+function noticeStringResult(toolName, logger) {
+  if (noticedStringResultTools.has(toolName)) return;
+  noticedStringResultTools.add(toolName);
+  logger.warn(
+    `[frontmcp] The UI template of tool "${toolName}" returned a plain string containing markup, which is rendered as HTML. FrontMCP 1.9 will HTML-escape plain string results by default. Build the markup with ctx.helpers.html\`\u2026\` (interpolated values are escaped) or wrap safe markup with ctx.helpers.trustedHtml(), then set ui.escapeStringResults: true (or escapeStringResults: false to keep the current behaviour without this notice). See ${STRING_RESULT_DOCS}`
+  );
+}
+function renderUnwrappedResult(rawResult, options) {
+  if (isTrustedHtml(rawResult)) {
+    return String(rawResult);
+  }
+  if (typeof rawResult !== "string") {
+    return `<pre>${escapeHtml(JSON.stringify(rawResult, null, 2))}</pre>`;
+  }
+  if (detectContentType(rawResult) !== "html" || options.escapeStringResults === true) {
+    return escapeHtml(rawResult);
+  }
+  if (options.escapeStringResults === void 0) {
+    noticeStringResult(options.toolName, options.logger ?? console);
+  }
+  return rawResult;
+}
 function renderToolTemplate(options) {
   const { toolName, input, output, template, resolver, platformType, sizing } = options;
   const uiType = detectUIType(template);
@@ -2768,7 +2819,7 @@ function renderToolTemplate(options) {
     resolver,
     sizing
   };
-  let html;
+  let html2;
   let hash = "";
   let size = 0;
   if (typeof template === "object" && template !== null && "file" in template) {
@@ -2777,44 +2828,43 @@ function renderToolTemplate(options) {
       { source: template, inlineReact: resourceMode === "inline" },
       { ...shellConfig, csp: cspConfig }
     );
-    html = result.html;
+    html2 = result.html;
     hash = result.hash;
     size = result.size;
   } else if (typeof template === "function") {
     if (uiType === "react") {
       const shellResult = buildShell('<div id="root"></div>', shellConfig);
-      html = shellResult.html;
+      html2 = shellResult.html;
       hash = shellResult.hash;
       size = shellResult.size;
     } else {
       const helpers = createTemplateHelpers();
       const ctx = { input, output, helpers };
       const rawResult = template(ctx);
-      const wrapped = wrapDetectedContent(rawResult);
+      const wrapped = isTrustedHtml(rawResult) ? void 0 : wrapDetectedContent(rawResult);
       if (wrapped) {
-        html = wrapped;
+        html2 = wrapped;
       } else {
-        const textContent = typeof rawResult === "string" ? rawResult : `<pre>${JSON.stringify(rawResult, null, 2)}</pre>`;
-        const shellResult = buildShell(textContent, shellConfig);
-        html = shellResult.html;
+        const shellResult = buildShell(renderUnwrappedResult(rawResult, options), shellConfig);
+        html2 = shellResult.html;
         hash = shellResult.hash;
         size = shellResult.size;
       }
     }
   } else if (typeof template === "string") {
     const shellResult = buildShell(template, shellConfig);
-    html = shellResult.html;
+    html2 = shellResult.html;
     hash = shellResult.hash;
     size = shellResult.size;
   } else {
     const shellResult = buildShell('<div id="root"></div>', shellConfig);
-    html = shellResult.html;
+    html2 = shellResult.html;
     hash = shellResult.hash;
     size = shellResult.size;
   }
   const htmlKey = "ui/html";
   const meta = {
-    [htmlKey]: html,
+    [htmlKey]: html2,
     "ui/type": uiType,
     "ui/mimeType": MCP_APPS_MIME_TYPE
   };
@@ -2825,10 +2875,10 @@ function renderToolTemplate(options) {
     if (sizing.aspectRatio !== void 0) meta["ui/aspectRatio"] = sizing.aspectRatio;
   }
   return {
-    html,
+    html: html2,
     uiType,
     hash,
-    size: size || Buffer.byteLength(html, "utf8"),
+    size: size || Buffer.byteLength(html2, "utf8"),
     meta
   };
 }

package/adapters/template-renderer.d.ts

@@ -36,6 +36,16 @@ export interface RenderToolTemplateOptions {
      * shell, and is mirrored onto the returned `meta` as `ui/preferredHeight` etc.
      */
     sizing?: WidgetSizing;
+    /**
+     * HTML-escape a plain string returned by a template function; results built with
+     * `html` / `trustedHtml` stay markup. When unset, strings that look like HTML render as
+     * markup and a one-time notice per tool is logged; `false` keeps that without the notice.
+     */
+    escapeStringResults?: boolean;
+    /** Receives the one-time string-result notice. Defaults to `console`. */
+    logger?: {
+        warn: (message: string) => void;
+    };
 }
 /**
  * Result of rendering a tool template.
@@ -57,7 +67,7 @@ export interface RenderToolTemplateResult {
  *
  * Supported template types:
  * - FileSource object `{ file: './widget.tsx' }` — bundled with esbuild, React loaded from esm.sh
- * - HTML template builder function `(ctx) => string`
+ * - HTML template builder function `(ctx) => string | TrustedHtml`
  * - Static HTML/MDX string
  *
  * React function references (`template: MyComponent`) are NOT supported for bundling.

package/adapters/template-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-renderer.d.ts","sourceRoot":"","sources":["../../src/adapters/template-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAKnD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAsBD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,wBAAwB,CAyG/F"}
+{"version":3,"file":"template-renderer.d.ts","sourceRoot":"","sources":["../../src/adapters/template-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAOnD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,yEAAyE;IACzE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AA6DD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,wBAAwB,CAsG/F"}

package/component/index.js

@@ -450,8 +450,9 @@ function createEsmShResolver(options = {}) {
 }
 
 // libs/uipack/src/utils/index.ts
-function escapeScriptClose(jsonString) {
-  return jsonString.replace(/<\//g, "<\\/");
+var SCRIPT_UNSAFE_CHARACTERS = /[<>&\u2028\u2029]/g;
+function toUnicodeEscape(character) {
+  return `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`;
 }
 function safeJsonForScript(value) {
   if (value === void 0) {
@@ -467,7 +468,7 @@ function safeJsonForScript(value) {
     if (jsonString === void 0) {
       return "null";
     }
-    return escapeScriptClose(jsonString);
+    return jsonString.replace(SCRIPT_UNSAFE_CHARACTERS, toUnicodeEscape);
   } catch {
     return '{"error":"Value could not be serialized"}';
   }
@@ -2070,14 +2071,16 @@ var REQUIRED_PLACEHOLDERS = ["CONTENT"];
 var OPTIONAL_PLACEHOLDERS = ["CSP", "DATA", "BRIDGE", "TITLE"];
 
 // libs/uipack/src/shell/custom-shell-applier.ts
+var PLACEHOLDER_PATTERN = new RegExp(`\\{\\{(${SHELL_PLACEHOLDER_NAMES.join("|")})\\}\\}`, "g");
+var VALUE_KEYS = {
+  CSP: "csp",
+  DATA: "data",
+  BRIDGE: "bridge",
+  CONTENT: "content",
+  TITLE: "title"
+};
 function applyShellTemplate(template, values) {
-  let result = template;
-  result = result.replaceAll(SHELL_PLACEHOLDERS.CSP, values.csp);
-  result = result.replaceAll(SHELL_PLACEHOLDERS.DATA, values.data);
-  result = result.replaceAll(SHELL_PLACEHOLDERS.BRIDGE, values.bridge);
-  result = result.replaceAll(SHELL_PLACEHOLDERS.CONTENT, values.content);
-  result = result.replaceAll(SHELL_PLACEHOLDERS.TITLE, values.title);
-  return result;
+  return template.replace(PLACEHOLDER_PATTERN, (_token, name) => values[VALUE_KEYS[name]]);
 }
 
 // libs/uipack/src/shell/custom-shell-validator.ts