@frontmcp/uipack 1.8.1 → 1.8.2

package/esm/index.mjs

@@ -2917,6 +2917,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;
@@ -2970,7 +2993,9 @@ function createTemplateHelpers() {
     uniqueId: (prefix = "mcp") => {
       return `${prefix}-${++_uniqueIdCounter}`;
     },
-    jsonEmbed: (data) => safeJsonForScript(data)
+    jsonEmbed: (data) => safeJsonForScript(data),
+    html,
+    trustedHtml
   };
 }
 
@@ -3048,12 +3073,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) {
@@ -3086,7 +3111,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")}
@@ -3096,9 +3121,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) {
@@ -3131,7 +3156,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,
@@ -3139,9 +3164,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) {
@@ -3548,10 +3573,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: []
@@ -3997,11 +4022,29 @@ function buildCspConfig(resolver) {
   }
   return { resourceDomains: cspResourceDomains, connectDomains: cspConnectDomains };
 }
-function renderUnwrappedResult(rawResult) {
+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>`;
   }
-  return detectContentType(rawResult) === "html" ? rawResult : escapeHtml(rawResult);
+  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;
@@ -4015,7 +4058,7 @@ function renderToolTemplate(options) {
     resolver,
     sizing
   };
-  let html;
+  let html2;
   let hash = "";
   let size = 0;
   if (typeof template === "object" && template !== null && "file" in template) {
@@ -4024,43 +4067,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 shellResult = buildShell(renderUnwrappedResult(rawResult), 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
   };
@@ -4071,10 +4114,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
   };
 }
@@ -4217,6 +4260,7 @@ export {
   getRegisteredPackages,
   getSubpathFromSpecifier,
   globalTypeCache,
+  html,
   isBundlingMode,
   isDisplayMode,
   isFileSource,
@@ -4229,6 +4273,7 @@ export {
   isPackageRegistered,
   isRelativeImport,
   isResourceMode,
+  isTrustedHtml,
   isUIRenderFailure,
   isUIType,
   isUrlShellSource,
@@ -4248,6 +4293,7 @@ export {
   safeStringify,
   sanitizeCSPDomains,
   transpileReactSource,
+  trustedHtml,
   validateCSPDomain,
   validateImportMap,
   validateShellTemplate,

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/uipack",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "FrontMCP UIpack - HTML shell builder, pluggable import resolver, and NPM component loader for MCP UI (React-free core)",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -61,6 +61,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.8.1"
+    "@frontmcp/lazy-zod": "1.8.2"
   }
 }

package/esm/shell/index.mjs

@@ -1343,6 +1343,29 @@ function safeJsonForScript(value) {
   }
 }
 
+// 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;
@@ -1396,7 +1419,9 @@ function createTemplateHelpers() {
     uniqueId: (prefix = "mcp") => {
       return `${prefix}-${++_uniqueIdCounter}`;
     },
-    jsonEmbed: (data) => safeJsonForScript(data)
+    jsonEmbed: (data) => safeJsonForScript(data),
+    html,
+    trustedHtml
   };
 }
 
@@ -1474,12 +1499,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) {
@@ -1512,7 +1537,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")}
@@ -1522,9 +1547,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) {
@@ -1557,7 +1582,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,
@@ -1565,9 +1590,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) {
@@ -1708,11 +1733,14 @@ export {
   clearShellTemplateCache,
   createTemplateHelpers,
   hasSizing,
+  html,
   isInlineShellSource,
   isNpmShellSource,
+  isTrustedHtml,
   isUrlShellSource,
   resolveShellTemplate,
   sanitizeCSPDomains,
+  trustedHtml,
   validateCSPDomain,
   validateShellTemplate
 };

package/index.d.ts

@@ -17,7 +17,7 @@ export * from './utils';
 export { generateBridgeIIFE, generatePlatformBundle, UNIVERSAL_BRIDGE_SCRIPT, BRIDGE_SCRIPT_TAGS, type IIFEGeneratorOptions, } from './bridge-runtime';
 export { type TypeFetchResult, type TypeFetchError, type TypeFetchErrorCode, type TypeFetchBatchRequest, type TypeFetchBatchResult, type TypeCacheEntry, type TypeCacheStats, type DtsImport, type DtsParseResult, type TypeFetcherOptions, type PackageResolution, DEFAULT_TYPE_FETCHER_OPTIONS, TYPE_CACHE_PREFIX, DEFAULT_TYPE_CACHE_TTL, type TypeCacheAdapter, type TypeCacheOptions, DEFAULT_CACHE_OPTIONS as DEFAULT_TYPE_CACHE_OPTIONS, MemoryTypeCache, globalTypeCache, parseDtsImports, isRelativeImport, getPackageFromSpecifier, getSubpathFromSpecifier, parseImportStatement, combineDtsContents, TypeFetcher, createTypeFetcher, } from './typings';
 export * from './resolver';
-export { type ShellConfig, type ShellResult, type CSPConfig, type ShellMountDescriptor, type ShellDataInjectionDescriptor, buildShell, DEFAULT_CDN_DOMAINS, DEFAULT_CSP_DIRECTIVES, RESTRICTIVE_CSP_DIRECTIVES, buildCSPDirectives, buildCSPMetaTag, validateCSPDomain, sanitizeCSPDomains, buildDataInjectionScript, buildCustomDataInjectionScript, createTemplateHelpers, type ShellPlaceholderName, type InlineShellSource, type UrlShellSource, type NpmShellSource, type CustomShellSource, type ShellTemplateValidation, type ResolvedShellTemplate, type ShellPlaceholderValues, type ResolveShellOptions, SHELL_PLACEHOLDER_NAMES, SHELL_PLACEHOLDERS, REQUIRED_PLACEHOLDERS, OPTIONAL_PLACEHOLDERS, isInlineShellSource, isUrlShellSource, isNpmShellSource, validateShellTemplate, applyShellTemplate, resolveShellTemplate, clearShellTemplateCache, } from './shell';
+export { type ShellConfig, type ShellResult, type CSPConfig, type ShellMountDescriptor, type ShellDataInjectionDescriptor, buildShell, DEFAULT_CDN_DOMAINS, DEFAULT_CSP_DIRECTIVES, RESTRICTIVE_CSP_DIRECTIVES, buildCSPDirectives, buildCSPMetaTag, validateCSPDomain, sanitizeCSPDomains, buildDataInjectionScript, buildCustomDataInjectionScript, createTemplateHelpers, html, trustedHtml, isTrustedHtml, type TrustedHtml, type ShellPlaceholderName, type InlineShellSource, type UrlShellSource, type NpmShellSource, type CustomShellSource, type ShellTemplateValidation, type ResolvedShellTemplate, type ShellPlaceholderValues, type ResolveShellOptions, SHELL_PLACEHOLDER_NAMES, SHELL_PLACEHOLDERS, REQUIRED_PLACEHOLDERS, OPTIONAL_PLACEHOLDERS, isInlineShellSource, isUrlShellSource, isNpmShellSource, validateShellTemplate, applyShellTemplate, resolveShellTemplate, clearShellTemplateCache, } from './shell';
 export * from './component';
 export * from './adapters';
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,cAAc,SAAS,CAAC;AAKxB,cAAc,SAAS,CAAC;AAKxB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,4BAA4B,EAC5B,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,qBAAqB,IAAI,0BAA0B,EACnD,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAKnB,cAAc,YAAY,CAAC;AAM3B,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EACjC,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,8BAA8B,EAC9B,qBAAqB,EAErB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,SAAS,CAAC;AAKjB,cAAc,aAAa,CAAC;AAK5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,cAAc,SAAS,CAAC;AAKxB,cAAc,SAAS,CAAC;AAKxB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,4BAA4B,EAC5B,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,qBAAqB,IAAI,0BAA0B,EACnD,eAAe,EACf,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAKnB,cAAc,YAAY,CAAC;AAM3B,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,4BAA4B,EACjC,UAAU,EACV,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,8BAA8B,EAC9B,qBAAqB,EAErB,IAAI,EACJ,WAAW,EACX,aAAa,EACb,KAAK,WAAW,EAEhB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,SAAS,CAAC;AAKjB,cAAc,aAAa,CAAC;AAK5B,cAAc,YAAY,CAAC"}

package/index.js

@@ -84,6 +84,7 @@ __export(index_exports, {
   getRegisteredPackages: () => getRegisteredPackages,
   getSubpathFromSpecifier: () => getSubpathFromSpecifier,
   globalTypeCache: () => globalTypeCache,
+  html: () => html,
   isBundlingMode: () => isBundlingMode,
   isDisplayMode: () => isDisplayMode,
   isFileSource: () => isFileSource,
@@ -96,6 +97,7 @@ __export(index_exports, {
   isPackageRegistered: () => isPackageRegistered,
   isRelativeImport: () => isRelativeImport,
   isResourceMode: () => isResourceMode,
+  isTrustedHtml: () => isTrustedHtml,
   isUIRenderFailure: () => isUIRenderFailure,
   isUIType: () => isUIType,
   isUrlShellSource: () => isUrlShellSource,
@@ -115,6 +117,7 @@ __export(index_exports, {
   safeStringify: () => safeStringify,
   sanitizeCSPDomains: () => sanitizeCSPDomains,
   transpileReactSource: () => transpileReactSource,
+  trustedHtml: () => trustedHtml,
   validateCSPDomain: () => validateCSPDomain,
   validateImportMap: () => validateImportMap,
   validateShellTemplate: () => validateShellTemplate,
@@ -3034,6 +3037,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;
@@ -3087,7 +3113,9 @@ function createTemplateHelpers() {
     uniqueId: (prefix = "mcp") => {
       return `${prefix}-${++_uniqueIdCounter}`;
     },
-    jsonEmbed: (data) => safeJsonForScript(data)
+    jsonEmbed: (data) => safeJsonForScript(data),
+    html,
+    trustedHtml
   };
 }
 
@@ -3165,12 +3193,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) {
@@ -3203,7 +3231,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")}
@@ -3213,9 +3241,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) {
@@ -3248,7 +3276,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,
@@ -3256,9 +3284,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) {
@@ -3665,10 +3693,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: []
@@ -4114,11 +4142,29 @@ function buildCspConfig(resolver) {
   }
   return { resourceDomains: cspResourceDomains, connectDomains: cspConnectDomains };
 }
-function renderUnwrappedResult(rawResult) {
+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>`;
   }
-  return detectContentType(rawResult) === "html" ? rawResult : escapeHtml(rawResult);
+  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;
@@ -4132,7 +4178,7 @@ function renderToolTemplate(options) {
     resolver,
     sizing
   };
-  let html;
+  let html2;
   let hash = "";
   let size = 0;
   if (typeof template === "object" && template !== null && "file" in template) {
@@ -4141,43 +4187,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 shellResult = buildShell(renderUnwrappedResult(rawResult), 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
   };
@@ -4188,10 +4234,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
   };
 }
@@ -4335,6 +4381,7 @@ function buildCDNInfoForUIType(uiType) {
   getRegisteredPackages,
   getSubpathFromSpecifier,
   globalTypeCache,
+  html,
   isBundlingMode,
   isDisplayMode,
   isFileSource,
@@ -4347,6 +4394,7 @@ function buildCDNInfoForUIType(uiType) {
   isPackageRegistered,
   isRelativeImport,
   isResourceMode,
+  isTrustedHtml,
   isUIRenderFailure,
   isUIType,
   isUrlShellSource,
@@ -4366,6 +4414,7 @@ function buildCDNInfoForUIType(uiType) {
   safeStringify,
   sanitizeCSPDomains,
   transpileReactSource,
+  trustedHtml,
   validateCSPDomain,
   validateImportMap,
   validateShellTemplate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/uipack",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "FrontMCP UIpack - HTML shell builder, pluggable import resolver, and NPM component loader for MCP UI (React-free core)",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -61,6 +61,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.8.1"
+    "@frontmcp/lazy-zod": "1.8.2"
   }
 }