@stacksjs/stx 0.2.342 → 0.2.343

package/dist/seo.js

@@ -1,267 +1,248 @@
+import {
+  describeValue,
+  evaluateDirectiveArgument,
+  isPlainRecord,
+  replaceDirectiveCalls,
+  reportDirectiveFailure,
+  splitTopLevelArgs,
+  warnDirective
+} from "./directive-arguments.js";
 import { ErrorCodes, inlineError } from "./error-handling.js";
 import { mergeHeadConfigs } from "./head.js";
-import { safeEvaluateObject } from "./safe-evaluator.js";
-export function processMetaDirectives(template, context, _filePath, _options) {
-  let output = template;
-  output = output.replace(/@meta\(\s*['"]([^'"]+)['"](?:,\s*['"]([^'"]+)['"]\s*)?\)/g, (_, name, content) => {
-    if (!content && name.includes(":")) {
-      const parts = name.split(":"), property = name, contextKey = parts.length > 1 ? parts[1] : "";
-      if (contextKey && context[contextKey])
-        content = context[contextKey];
-      else if (property.startsWith("og:") && context.openGraph && context.openGraph[parts[1]])
-        content = context.openGraph[parts[1]];
-      else
-        content = "";
-      return content ? `<meta property="${escapeHtml(property)}" content="${escapeHtml(content)}">` : "";
-    }
-    return content ? `<meta name="${escapeHtml(name)}" content="${escapeHtml(content)}">` : "";
-  });
-  const metaTagPat = /@metaTag\s*\(/g;
-  let metaMatch;
-  while ((metaMatch = metaTagPat.exec(output)) !== null) {
-    const mtStart = metaMatch.index, openP = mtStart + metaMatch[0].length - 1;
-    let d = 1, p = openP + 1;
-    while (p < output.length && d > 0) {
-      if (output[p] === "(")
-        d++;
-      else if (output[p] === ")") {
-        d--;
-        if (d === 0)
-          break;
-      }
-      p++;
-    }
-    if (d !== 0)
-      break;
-    const attrObject = output.substring(openP + 1, p).trim(), fullEnd = p + 1, mtReplacement = (() => {
-      try {
-        const attrs = safeEvaluateObject(attrObject, context);
-        if (!attrs)
-          return "";
-        let tag = "<meta";
-        if (attrs.name)
-          tag += ` name="${escapeHtml(String(attrs.name))}"`;
-        if (attrs.property)
-          tag += ` property="${escapeHtml(String(attrs.property))}"`;
-        if (attrs.httpEquiv)
-          tag += ` http-equiv="${escapeHtml(String(attrs.httpEquiv))}"`;
-        if (attrs.content)
-          tag += ` content="${escapeHtml(String(attrs.content))}"`;
-        tag += ">";
-        return tag;
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return inlineError("MetaTag", errorMessage, ErrorCodes.EVALUATION_ERROR);
-      }
-    })();
-    output = output.substring(0, mtStart) + mtReplacement + output.substring(fullEnd);
-    metaTagPat.lastIndex = 0;
-  }
+import { resolveMetaArguments } from "./meta-arguments.js";
+const META_CALL = /(?<![\w$@])@meta\s*\(/g, META_TAG_CALL = /(?<![\w$@])@metaTag\s*\(/g, STRUCTURED_DATA_CALL = /(?<![\w$@])@structuredData\s*\(/g, SEO_CALL = /(?<![\w$@])@seo\s*\(/g;
+function unterminated(label, filePath) {
+  return (call) => reportDirectiveFailure(label, call, "the call has no closing parenthesis", filePath, ErrorCodes.INVALID_DIRECTIVE_SYNTAX);
+}
+function renderMetaTag(tag) {
+  return "property" in tag ? `<meta property="${escapeHtml(tag.property)}" content="${escapeHtml(tag.content)}">` : `<meta name="${escapeHtml(tag.name)}" content="${escapeHtml(tag.content)}">`;
+}
+export function processMetaDirectives(template, context, filePath, _options) {
+  if (!template.includes("@meta"))
+    return template;
+  let output = replaceDirectiveCalls(template, META_CALL, (args, call) => {
+    const resolved = resolveMetaArguments(splitTopLevelArgs(args), context);
+    if (resolved.kind === "tag")
+      return renderMetaTag(resolved.tag);
+    if (resolved.kind === "empty")
+      return "";
+    return reportDirectiveFailure("Meta", call, resolved.message, filePath, resolved.code);
+  }, unterminated("Meta", filePath));
+  output = replaceDirectiveCalls(output, META_TAG_CALL, (args, call) => {
+    const result = evaluateDirectiveArgument(args, context);
+    if (!result.ok)
+      return reportDirectiveFailure("MetaTag", call, result.message, filePath, result.code);
+    if (result.value === void 0 || result.value === null)
+      return "";
+    if (!isPlainRecord(result.value))
+      return reportDirectiveFailure("MetaTag", call, `expected an object such as { name, content }, got ${describeValue(result.value)}`, filePath, ErrorCodes.TYPE_ERROR);
+    const attrs = result.value;
+    if (!attrs.name && !attrs.property && !attrs.httpEquiv)
+      return reportDirectiveFailure("MetaTag", call, "the tag needs a name, property or httpEquiv", filePath, ErrorCodes.INVALID_DIRECTIVE_SYNTAX);
+    if (attrs.content === void 0 || attrs.content === null || attrs.content === "" || attrs.content === !1)
+      return "";
+    let tag = "<meta";
+    if (attrs.name)
+      tag += ` name="${escapeHtml(attrs.name)}"`;
+    if (attrs.property)
+      tag += ` property="${escapeHtml(attrs.property)}"`;
+    if (attrs.httpEquiv)
+      tag += ` http-equiv="${escapeHtml(attrs.httpEquiv)}"`;
+    tag += ` content="${escapeHtml(attrs.content)}">`;
+    return tag;
+  }, unterminated("MetaTag", filePath));
   return output;
 }
-export function processStructuredData(template, context, _filePath) {
-  let output = template;
-  const structuredDataPattern = /@structuredData\s*\(/g;
-  let sdMatch;
-  while ((sdMatch = structuredDataPattern.exec(output)) !== null) {
-    const sdStart = sdMatch.index, openParen = sdStart + sdMatch[0].length - 1;
-    let depth = 1, pos = openParen + 1;
-    while (pos < output.length && depth > 0) {
-      if (output[pos] === "(")
-        depth++;
-      else if (output[pos] === ")") {
-        depth--;
-        if (depth === 0)
-          break;
-      }
-      pos++;
+function withSchemaContext(value) {
+  const fill = (item) => item["@context"] ? { ...item } : { ...item, "@context": "https://schema.org" };
+  if (isPlainRecord(value))
+    return fill(value);
+  if (Array.isArray(value) && value.length > 0 && value.every(isPlainRecord))
+    return value.map(fill);
+  return null;
+}
+function jsonLdScript(data) {
+  return `<script type="application/ld+json">${JSON.stringify(data).replace(/<\//g, "<\\/")}</script>`;
+}
+export function processStructuredData(template, context, filePath) {
+  if (!template.includes("@structuredData"))
+    return template;
+  return replaceDirectiveCalls(template, STRUCTURED_DATA_CALL, (args, call) => {
+    const result = evaluateDirectiveArgument(args, context);
+    if (!result.ok)
+      return reportDirectiveFailure("StructuredData", call, result.message, filePath, result.code);
+    if (result.value === void 0 || result.value === null)
+      return "";
+    const data = withSchemaContext(result.value);
+    if (!data)
+      return reportDirectiveFailure("StructuredData", call, `expected an object or an array of objects, got ${describeValue(result.value)}`, filePath, ErrorCodes.TYPE_ERROR);
+    try {
+      return jsonLdScript(data);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return reportDirectiveFailure("StructuredData", call, `the data cannot be written as JSON: ${message}`, filePath, ErrorCodes.EVALUATION_ERROR);
     }
-    if (depth !== 0)
-      break;
-    const dataObject = output.substring(openParen + 1, pos).trim(), fullEnd = pos + 1, replacement = (() => {
-      try {
-        const data = safeEvaluateObject(dataObject, context);
-        if (!data)
-          return "";
-        if (!data["@context"])
-          data["@context"] = "https://schema.org";
-        return `<script type="application/ld+json">${JSON.stringify(data).replace(/<\//g, "<\\/")}</script>`;
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return inlineError("StructuredData", errorMessage, ErrorCodes.EVALUATION_ERROR);
-      }
-    })();
-    output = output.substring(0, sdStart) + replacement + output.substring(fullEnd);
-    structuredDataPattern.lastIndex = 0;
-  }
-  return output;
+  }, unterminated("StructuredData", filePath));
 }
-export function processSeoDirective(template, context, _filePath, _options) {
-  let output = template;
-  const seoPat = /@seo\s*\(\s*\{/g;
-  let seoMatch;
-  while ((seoMatch = seoPat.exec(output)) !== null) {
-    const braceStart = output.indexOf("{", seoMatch.index + 4);
-    let depth = 1, pos = braceStart + 1, inStr = null, esc = !1;
-    while (pos < output.length && depth > 0) {
-      const c = output[pos];
-      if (esc) {
-        esc = !1;
-        pos++;
-        continue;
-      }
-      if (c === "\\" && inStr) {
-        esc = !0;
-        pos++;
-        continue;
-      }
-      if (inStr) {
-        if (c === inStr)
-          inStr = null;
-        pos++;
-        continue;
-      }
-      if (c === '"' || c === "'" || c === "`") {
-        inStr = c;
-        pos++;
-        continue;
-      }
-      if (c === "{")
-        depth++;
-      else if (c === "}")
-        depth--;
-      pos++;
+const SEO_KEYS = new Set(["title", "description", "keywords", "robots", "canonical", "openGraph", "twitter", "structuredData"]), SEO_KEY_HINTS = {
+  image: "openGraph.image",
+  url: "canonical or openGraph.url",
+  type: "openGraph.type",
+  siteName: "openGraph.siteName",
+  locale: "openGraph.locale",
+  og: "openGraph",
+  author: "@meta('author', ...)"
+};
+export function processSeoDirective(template, context, filePath, _options) {
+  if (!template.includes("@seo"))
+    return template;
+  return replaceDirectiveCalls(template, SEO_CALL, (args, call) => {
+    if (!args.trim())
+      return reportDirectiveFailure("SEO", call, "expected an object: @seo({ title, description }) or @seo(seoVariable)", filePath, ErrorCodes.INVALID_DIRECTIVE_SYNTAX);
+    const result = evaluateDirectiveArgument(args, context);
+    if (!result.ok)
+      return reportDirectiveFailure("SEO", call, result.message, filePath, result.code);
+    if (result.value === void 0 || result.value === null)
+      return "";
+    if (!isPlainRecord(result.value))
+      return reportDirectiveFailure("SEO", call, `expected an object such as { title, description }, got ${describeValue(result.value)}`, filePath, ErrorCodes.TYPE_ERROR);
+    try {
+      return renderSeoTags(result.value, call, filePath);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return reportDirectiveFailure("SEO", call, `Error processing @seo directive: ${message}`, filePath, ErrorCodes.EVALUATION_ERROR);
     }
-    if (depth !== 0)
-      break;
-    const afterBrace = output.substring(pos).match(/^\s*\)/);
-    if (!afterBrace)
-      break;
-    const fullEnd = pos + afterBrace[0].length, seoConfig = output.substring(braceStart, pos), fullMatch = output.substring(seoMatch.index, fullEnd), replacement = ((cfg) => {
-      try {
-        const config = safeEvaluateObject(cfg, context);
-        if (!config)
-          return "";
-        let metaTags = "";
-        if (config.title) {
-          metaTags += `<title>${escapeHtml(config.title)}</title>
+  }, unterminated("SEO", filePath));
+}
+function nestedConfig(config, key, call, filePath) {
+  const value = config[key];
+  if (value === void 0 || value === null || value === !1)
+    return;
+  if (isPlainRecord(value))
+    return value;
+  warnDirective(call, `${key} must be an object, got ${describeValue(value)}; its tags were left out`, filePath);
+  return;
+}
+function renderSeoTags(config, call, filePath) {
+  const unknown = Object.keys(config).filter((key) => !SEO_KEYS.has(key));
+  if (unknown.length > 0) {
+    const described = unknown.map((key) => SEO_KEY_HINTS[key] ? `${key} (use ${SEO_KEY_HINTS[key]})` : key).join(", ");
+    warnDirective(call, `@seo does not read ${described}; ${unknown.length === 1 ? "it was" : "they were"} ignored`, filePath);
+  }
+  let metaTags = "";
+  if (config.title) {
+    metaTags += `<title>${escapeHtml(config.title)}</title>
 `;
-          metaTags += `<meta name="title" content="${escapeHtml(config.title)}">
+    metaTags += `<meta name="title" content="${escapeHtml(config.title)}">
 `;
-        }
-        if (config.description)
-          metaTags += `<meta name="description" content="${escapeHtml(config.description)}">
+  }
+  if (config.description)
+    metaTags += `<meta name="description" content="${escapeHtml(config.description)}">
 `;
-        if (config.keywords) {
-          const keywordsStr = Array.isArray(config.keywords) ? config.keywords.join(", ") : config.keywords;
-          metaTags += `<meta name="keywords" content="${escapeHtml(keywordsStr)}">
+  if (config.keywords) {
+    const keywordsStr = Array.isArray(config.keywords) ? config.keywords.join(", ") : config.keywords;
+    metaTags += `<meta name="keywords" content="${escapeHtml(keywordsStr)}">
 `;
-        }
-        if (config.robots)
-          metaTags += `<meta name="robots" content="${escapeHtml(config.robots)}">
+  }
+  if (config.robots)
+    metaTags += `<meta name="robots" content="${escapeHtml(config.robots)}">
 `;
-        if (config.canonical)
-          metaTags += `<link rel="canonical" href="${escapeHtml(config.canonical)}">
+  if (config.canonical)
+    metaTags += `<link rel="canonical" href="${escapeHtml(config.canonical)}">
 `;
-        if (config.openGraph) {
-          const og = config.openGraph;
-          metaTags += `<meta property="og:type" content="${escapeHtml(og.type || "website")}">
+  const og = nestedConfig(config, "openGraph", call, filePath);
+  if (og) {
+    metaTags += `<meta property="og:type" content="${escapeHtml(og.type || "website")}">
 `;
-          if (og.title || config.title) {
-            const ogTitle = og.title || config.title || "";
-            metaTags += `<meta property="og:title" content="${escapeHtml(ogTitle)}">
+    if (og.title || config.title) {
+      const ogTitle = og.title || config.title || "";
+      metaTags += `<meta property="og:title" content="${escapeHtml(ogTitle)}">
 `;
-          }
-          if (og.description || config.description) {
-            const ogDescription = og.description || config.description || "";
-            metaTags += `<meta property="og:description" content="${escapeHtml(ogDescription)}">
+    }
+    if (og.description || config.description) {
+      const ogDescription = og.description || config.description || "";
+      metaTags += `<meta property="og:description" content="${escapeHtml(ogDescription)}">
 `;
-          }
-          if (og.url || config.canonical) {
-            const ogUrl = og.url || config.canonical || "";
-            metaTags += `<meta property="og:url" content="${escapeHtml(ogUrl)}">
+    }
+    if (og.url || config.canonical) {
+      const ogUrl = og.url || config.canonical || "";
+      metaTags += `<meta property="og:url" content="${escapeHtml(ogUrl)}">
 `;
-          }
-          if (og.image) {
-            metaTags += `<meta property="og:image" content="${escapeHtml(og.image)}">
+    }
+    if (og.image) {
+      metaTags += `<meta property="og:image" content="${escapeHtml(og.image)}">
 `;
-            if (og.imageAlt)
-              metaTags += `<meta property="og:image:alt" content="${escapeHtml(og.imageAlt)}">
+      if (og.imageAlt)
+        metaTags += `<meta property="og:image:alt" content="${escapeHtml(og.imageAlt)}">
 `;
-            if (og.imageWidth)
-              metaTags += `<meta property="og:image:width" content="${escapeHtml(String(og.imageWidth))}">
+      if (og.imageWidth)
+        metaTags += `<meta property="og:image:width" content="${escapeHtml(String(og.imageWidth))}">
 `;
-            if (og.imageHeight)
-              metaTags += `<meta property="og:image:height" content="${escapeHtml(String(og.imageHeight))}">
+      if (og.imageHeight)
+        metaTags += `<meta property="og:image:height" content="${escapeHtml(String(og.imageHeight))}">
 `;
-            if (og.imageType)
-              metaTags += `<meta property="og:image:type" content="${escapeHtml(og.imageType)}">
+      if (og.imageType)
+        metaTags += `<meta property="og:image:type" content="${escapeHtml(og.imageType)}">
 `;
-          }
-          if (og.siteName)
-            metaTags += `<meta property="og:site_name" content="${escapeHtml(og.siteName)}">
+    }
+    if (og.siteName)
+      metaTags += `<meta property="og:site_name" content="${escapeHtml(og.siteName)}">
 `;
-          if (og.locale)
-            metaTags += `<meta property="og:locale" content="${escapeHtml(og.locale)}">
+    if (og.locale)
+      metaTags += `<meta property="og:locale" content="${escapeHtml(og.locale)}">
 `;
-          if (og.profile) {
-            const profile = [
-              ["first_name", og.profile.firstName],
-              ["last_name", og.profile.lastName],
-              ["username", og.profile.username],
-              ["gender", og.profile.gender]
-            ];
-            for (const [key, value] of profile)
-              if (value)
-                metaTags += `<meta property="profile:${key}" content="${escapeHtml(value)}">
+    if (og.profile) {
+      const profile = [
+        ["first_name", og.profile.firstName],
+        ["last_name", og.profile.lastName],
+        ["username", og.profile.username],
+        ["gender", og.profile.gender]
+      ];
+      for (const [key, value] of profile)
+        if (value)
+          metaTags += `<meta property="profile:${key}" content="${escapeHtml(value)}">
 `;
-          }
-        }
-        if (config.twitter) {
-          const twitter = config.twitter;
-          metaTags += `<meta name="twitter:card" content="${escapeHtml(twitter.card || "summary_large_image")}">
+    }
+  }
+  const twitter = nestedConfig(config, "twitter", call, filePath);
+  if (twitter) {
+    metaTags += `<meta name="twitter:card" content="${escapeHtml(twitter.card || "summary_large_image")}">
 `;
-          if (twitter.title || config.title) {
-            const twitterTitle = twitter.title || config.title || "";
-            metaTags += `<meta name="twitter:title" content="${escapeHtml(twitterTitle)}">
+    if (twitter.title || config.title) {
+      const twitterTitle = twitter.title || config.title || "";
+      metaTags += `<meta name="twitter:title" content="${escapeHtml(twitterTitle)}">
 `;
-          }
-          if (twitter.description || config.description) {
-            const twitterDesc = twitter.description || config.description || "";
-            metaTags += `<meta name="twitter:description" content="${escapeHtml(twitterDesc)}">
+    }
+    if (twitter.description || config.description) {
+      const twitterDesc = twitter.description || config.description || "";
+      metaTags += `<meta name="twitter:description" content="${escapeHtml(twitterDesc)}">
 `;
-          }
-          if (twitter.image || config.openGraph && config.openGraph.image) {
-            const twitterImage = twitter.image || (config.openGraph ? config.openGraph.image : "") || "";
-            metaTags += `<meta name="twitter:image" content="${escapeHtml(twitterImage)}">
+    }
+    if (twitter.image || og && og.image) {
+      const twitterImage = twitter.image || (og ? og.image : "") || "";
+      metaTags += `<meta name="twitter:image" content="${escapeHtml(twitterImage)}">
 `;
-            const twitterImageAlt = twitter.imageAlt || (!twitter.image && config.openGraph ? config.openGraph.imageAlt : void 0);
-            if (twitterImageAlt)
-              metaTags += `<meta name="twitter:image:alt" content="${escapeHtml(twitterImageAlt)}">
+      const twitterImageAlt = twitter.imageAlt || (!twitter.image && og ? og.imageAlt : void 0);
+      if (twitterImageAlt)
+        metaTags += `<meta name="twitter:image:alt" content="${escapeHtml(twitterImageAlt)}">
 `;
-          }
-          if (twitter.site)
-            metaTags += `<meta name="twitter:site" content="${escapeHtml(twitter.site)}">
+    }
+    if (twitter.site)
+      metaTags += `<meta name="twitter:site" content="${escapeHtml(twitter.site)}">
 `;
-          if (twitter.creator)
-            metaTags += `<meta name="twitter:creator" content="${escapeHtml(twitter.creator)}">
+    if (twitter.creator)
+      metaTags += `<meta name="twitter:creator" content="${escapeHtml(twitter.creator)}">
 `;
-        }
-        if (config.structuredData) {
-          const jsonStr = JSON.stringify(config.structuredData).replace(/<\//g, "<\\/");
-          metaTags += `<script type="application/ld+json">${jsonStr}</script>
+  }
+  if (config.structuredData !== void 0 && config.structuredData !== null) {
+    const data = withSchemaContext(config.structuredData);
+    if (data)
+      metaTags += `${jsonLdScript(data)}
 `;
-        }
-        return metaTags.trim();
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return inlineError("SEO", `Error processing @seo directive: ${errorMessage}`, ErrorCodes.EVALUATION_ERROR);
-      }
-    })(seoConfig);
-    output = output.substring(0, seoMatch.index) + replacement + output.substring(fullEnd);
-    seoPat.lastIndex = seoMatch.index + replacement.length;
+    else
+      warnDirective(call, `structuredData must be an object or an array of objects, got ${describeValue(config.structuredData)}; it was left out`, filePath);
   }
-  return output;
+  return metaTags.trim();
 }
 export function injectSeoTags(html, context, options) {
   if (options.seo?.enabled === !1)
@@ -367,35 +348,20 @@ function readPageDescription(head) {
   }
   return "";
 }
-function escapeHtml(str) {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
-const PROPERTY_NAMESPACES = ["og:", "article:", "book:", "profile:", "fb:", "music:", "video:"];
-function unquoteParam(raw) {
-  const text = raw.trim(), first = text[0];
-  if ((first === "'" || first === '"' || first === "`") && text.length > 1 && text.at(-1) === first)
-    return { value: text.slice(1, -1), quoted: !0 };
-  return { value: text, quoted: !1 };
+function escapeHtml(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
 export const metaDirective = {
   name: "meta",
-  handler: (_content, params, context, _filePath) => {
-    if (params.length < 1)
-      return inlineError("Meta", "meta directive requires at least the meta name", ErrorCodes.INVALID_DIRECTIVE_SYNTAX);
-    const name = unquoteParam(params[0]).value;
-    let metaContent;
-    if (params.length > 1) {
-      const arg = unquoteParam(params[1]);
-      metaContent = arg.quoted ? arg.value : String(context?.[arg.value] ?? arg.value);
-    } else {
-      const segment = name.includes(":") ? name.slice(name.indexOf(":") + 1) : name, openGraph = context?.openGraph;
-      metaContent = String(context?.[segment] ?? openGraph?.[segment] ?? "");
-    }
-    if (!metaContent)
+  rawParams: !0,
+  handler: (_content, params, context, filePath) => {
+    const resolved = resolveMetaArguments(params, context ?? {});
+    if (resolved.kind === "error")
+      return reportDirectiveFailure("Meta", `@meta(${params.join(", ")})`, resolved.message, filePath, resolved.code);
+    if (resolved.kind === "empty")
       return "";
-    const tag = PROPERTY_NAMESPACES.some((prefix) => name.startsWith(prefix)) ? { property: name, content: metaContent } : { name, content: metaContent };
     if (context)
-      context.__stx_runtime_head = mergeHeadConfigs(context.__stx_runtime_head ?? {}, { meta: [tag] });
+      context.__stx_runtime_head = mergeHeadConfigs(context.__stx_runtime_head ?? {}, { meta: [resolved.tag] });
     return "";
   },
   hasEndTag: !1
@@ -410,7 +376,7 @@ export const metaDirective = {
         data["@context"] = "https://schema.org";
       if (!data["@type"])
         return inlineError("StructuredData", "structuredData requires @type property", ErrorCodes.INVALID_DIRECTIVE_SYNTAX);
-      return `<script type="application/ld+json">${JSON.stringify(data)}</script>`;
+      return jsonLdScript(data);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       return inlineError("StructuredData", errorMessage, ErrorCodes.EVALUATION_ERROR);

package/dist/ssg.js

@@ -1,5 +1,5 @@
 // @bun
-import{Bk as Fq,wk as Uq,xk as Iq}from"./chunk-byjy9far.js";import{Ck as Eq,Dk as Tq,Ek as Dq}from"./chunk-c0n802j1.js";import{Zk as _q,al as zq,bl as Aq}from"./chunk-4wpxbkbe.js";import"./chunk-gbkq5qnw.js";import"./chunk-fvsefztj.js";import{Np as P,Sm as Oq,mo as l,po as Hq,vr as n}from"./chunk-j82hfkcf.js";import"./chunk-rh7mwwb4.js";import"./chunk-1t3j8a0q.js";import"./chunk-01ggk8k8.js";import"./chunk-25b8z7xa.js";import"./chunk-hk8j3eps.js";import{lt as Xq}from"./chunk-xe93ae3r.js";import{qt as d}from"./chunk-1spzqjve.js";import"./chunk-f2qbjr3z.js";import"./chunk-1xwfws06.js";import"./chunk-r1rfwm01.js";import{Xt as Bq}from"./chunk-ahpmjg3f.js";import"./chunk-bt8w146r.js";import"./chunk-6p6b01kp.js";import"./chunk-x7dv5rq7.js";import"./chunk-e0kzyf1g.js";import"./chunk-wv8h3d68.js";import{bw as Yq,cw as Vq,dw as jq,ew as Gq,fw as Lq,gw as Nq}from"./chunk-beextc84.js";import"./chunk-yr7camcd.js";import{xw as y}from"./chunk-p5d8sb50.js";import O from"fs";import j from"path";import{createHash as xq}from"crypto";function yq(q){try{return new Bun.Transpiler({loader:"js",minifyWhitespace:!0}).transformSync(q).replace(/\}(var |let |const |function )/g,"};$1").trim()}catch{return q}}var Pq=/<script\s+type="stx\/island"\s+data-stx-island="([^"]+)"([^>]*)>([\s\S]*?)<\/script>/g;function Cq(q){return Bun.hash(q).toString(16)}function Qq(q,Z={}){if(!q.includes('type="stx/island"'))return{html:q,chunks:[]};let $=new Map,Q=q.replace(Pq,(J,W,z,A)=>{let G=A.trim();if(!G)return J;if(/\bdata-stx-src=/.test(z))return J;if(Z.minify)G=yq(G);let X=Cq(G);if(!$.has(X))$.set(X,G);let B=Z.integrity?` data-stx-integrity="sha384-${xq("sha384").update(G).digest("base64")}"`:"";return`<script type="stx/island" data-stx-island="${W}" data-stx-src="/_stx/islands/${X}.js"${B}${z}></script>`}),K=Array.from($,([J,W])=>({hash:J,code:W}));return{html:Q,chunks:K}}var gq=new Set(["visible","idle"]);function Zq(q){if(!q.includes("data-stx-src="))return q;let Z=new Map,$=/data-stx-scope="([^"]+)"[^>]*?stx-hydrate="([^"]+)"/g,Q;while((Q=$.exec(q))!==null)Z.set(Q[1],Q[2]);let K=new Set,J=/data-stx-island="([^"]+)"[^>]*?data-stx-src="([^"]+)"/g,W;while((W=J.exec(q))!==null)if(gq.has(Z.get(W[1])||""))K.add(W[2]);let z=q.lastIndexOf("</head>");if(K.size===0||z===-1)return q;let A=Array.from(K).filter((G)=>!q.includes(`rel="prefetch" href="${G}"`)).map((G)=>`<link rel="prefetch" href="${G}" as="script">`).join("");if(!A)return q;return q.slice(0,z)+A+q.slice(z)}var fq=["STX_SITE_URL","SITE_URL","URL","VERCEL_URL","CF_PAGES_URL"];function h(q){let Z=q.trim();if(!Z)return null;let $=/^https?:\/\//i.test(Z)?Z:`https://${Z}`;try{return new URL($).origin+new URL($).pathname.replace(/\/$/,"")}catch{return null}}function mq(q){for(let Z of fq){let $=q[Z];if(!$)continue;let Q=h($);if(Q)return{url:Q,source:"env",via:Z}}return null}function $q(q){if(!q||typeof q!=="object")return null;let Z=q,$=Z.site?.url??Z.url??Z.app?.url;return typeof $==="string"?h($):null}async function dq(q){let{existsSync:Z}=await import("fs"),$=await import("path");for(let Q of["site.config.ts","site.config.js",".config/site.config.ts"]){let K=$.resolve(q,Q);if(!Z(K))continue;try{let J=await import(K),W=$q(J.default??J);if(W)return W}catch{}}return null}async function Kq(q={}){let Z=q.cwd??process.cwd(),$=q.env??process.env;if(q.explicit){let W=h(q.explicit);if(W)return{url:W,source:"option"}}let Q=$q(q.stxConfig);if(Q)return{url:Q,source:"stx.config",via:"site.url"};let K=await dq(Z);if(K)return{url:K,source:"site.config",via:"url"};let J=mq($);if(J)return J;return{url:"http://localhost",source:"fallback"}}function Wq(){return["No site URL configured \u2014 sitemap.xml and robots.txt will point at http://localhost.","  Set one in stx.config.ts (site: { url: 'https://example.com' }), in site.config.ts,","  via --domain, or with SITE_URL in the build environment."].join(`
+import{Bk as Fq,wk as Uq,xk as Iq}from"./chunk-wnmegbw0.js";import{Ck as Eq,Dk as Tq,Ek as Dq}from"./chunk-c0n802j1.js";import{Zk as _q,al as zq,bl as Aq}from"./chunk-57dxdvjh.js";import"./chunk-2853ye06.js";import"./chunk-fvsefztj.js";import{Jp as P,Sm as Oq,io as l,lo as Hq,rr as n}from"./chunk-xgw269cf.js";import"./chunk-aqxwwq6w.js";import"./chunk-t00ga194.js";import"./chunk-hrdd26r4.js";import"./chunk-7r79j1hs.js";import"./chunk-ay336sqb.js";import{ht as Xq}from"./chunk-6xs80tka.js";import{mt as d}from"./chunk-vaggjvsm.js";import"./chunk-q9ckfwhh.js";import"./chunk-kbah2k8e.js";import"./chunk-k3dtvay1.js";import{Tt as Bq}from"./chunk-eh3meyd3.js";import"./chunk-rzg9pars.js";import"./chunk-1qtd4ex2.js";import"./chunk-ec18ftcg.js";import"./chunk-fbmjw0bh.js";import"./chunk-53sjbp3z.js";import{lw as Yq,mw as Vq,nw as jq,ow as Gq,pw as Lq,qw as Nq}from"./chunk-kgbz86sa.js";import"./chunk-s60eccqk.js";import{Hw as y}from"./chunk-0s3ry262.js";import O from"fs";import j from"path";import{createHash as xq}from"crypto";function yq(q){try{return new Bun.Transpiler({loader:"js",minifyWhitespace:!0}).transformSync(q).replace(/\}(var |let |const |function )/g,"};$1").trim()}catch{return q}}var Pq=/<script\s+type="stx\/island"\s+data-stx-island="([^"]+)"([^>]*)>([\s\S]*?)<\/script>/g;function Cq(q){return Bun.hash(q).toString(16)}function Qq(q,Z={}){if(!q.includes('type="stx/island"'))return{html:q,chunks:[]};let $=new Map,Q=q.replace(Pq,(J,W,z,A)=>{let G=A.trim();if(!G)return J;if(/\bdata-stx-src=/.test(z))return J;if(Z.minify)G=yq(G);let X=Cq(G);if(!$.has(X))$.set(X,G);let B=Z.integrity?` data-stx-integrity="sha384-${xq("sha384").update(G).digest("base64")}"`:"";return`<script type="stx/island" data-stx-island="${W}" data-stx-src="/_stx/islands/${X}.js"${B}${z}></script>`}),K=Array.from($,([J,W])=>({hash:J,code:W}));return{html:Q,chunks:K}}var gq=new Set(["visible","idle"]);function Zq(q){if(!q.includes("data-stx-src="))return q;let Z=new Map,$=/data-stx-scope="([^"]+)"[^>]*?stx-hydrate="([^"]+)"/g,Q;while((Q=$.exec(q))!==null)Z.set(Q[1],Q[2]);let K=new Set,J=/data-stx-island="([^"]+)"[^>]*?data-stx-src="([^"]+)"/g,W;while((W=J.exec(q))!==null)if(gq.has(Z.get(W[1])||""))K.add(W[2]);let z=q.lastIndexOf("</head>");if(K.size===0||z===-1)return q;let A=Array.from(K).filter((G)=>!q.includes(`rel="prefetch" href="${G}"`)).map((G)=>`<link rel="prefetch" href="${G}" as="script">`).join("");if(!A)return q;return q.slice(0,z)+A+q.slice(z)}var fq=["STX_SITE_URL","SITE_URL","URL","VERCEL_URL","CF_PAGES_URL"];function h(q){let Z=q.trim();if(!Z)return null;let $=/^https?:\/\//i.test(Z)?Z:`https://${Z}`;try{return new URL($).origin+new URL($).pathname.replace(/\/$/,"")}catch{return null}}function mq(q){for(let Z of fq){let $=q[Z];if(!$)continue;let Q=h($);if(Q)return{url:Q,source:"env",via:Z}}return null}function $q(q){if(!q||typeof q!=="object")return null;let Z=q,$=Z.site?.url??Z.url??Z.app?.url;return typeof $==="string"?h($):null}async function dq(q){let{existsSync:Z}=await import("fs"),$=await import("path");for(let Q of["site.config.ts","site.config.js",".config/site.config.ts"]){let K=$.resolve(q,Q);if(!Z(K))continue;try{let J=await import(K),W=$q(J.default??J);if(W)return W}catch{}}return null}async function Kq(q={}){let Z=q.cwd??process.cwd(),$=q.env??process.env;if(q.explicit){let W=h(q.explicit);if(W)return{url:W,source:"option"}}let Q=$q(q.stxConfig);if(Q)return{url:Q,source:"stx.config",via:"site.url"};let K=await dq(Z);if(K)return{url:K,source:"site.config",via:"url"};let J=mq($);if(J)return J;return{url:"http://localhost",source:"fallback"}}function Wq(){return["No site URL configured \u2014 sitemap.xml and robots.txt will point at http://localhost.","  Set one in stx.config.ts (site: { url: 'https://example.com' }), in site.config.ts,","  via --domain, or with SITE_URL in the build environment."].join(`
 `)}class wq{cacheDir;cache=new Map;loaded=!1;salt;constructor(q,Z=""){this.cacheDir=q,this.salt=Z}async load(){if(this.loaded)return;let q=j.join(this.cacheDir,"build-cache.json");if(await Bun.file(q).exists())try{let Z=JSON.parse(await Bun.file(q).text());for(let[$,Q]of Object.entries(Z))this.cache.set($,Q)}catch{}this.loaded=!0}async save(){await O.promises.mkdir(this.cacheDir,{recursive:!0});let q=j.join(this.cacheDir,"build-cache.json"),Z={};for(let[$,Q]of this.cache)Z[$]=Q;await Bun.write(q,JSON.stringify(Z))}getHash(q,Z){let $=O.statSync(q),Q=`${this.salt}|${q}:${$.mtimeMs}`;for(let J of Z)if(O.existsSync(J)){let W=O.statSync(J);Q+=`:${J}:${W.mtimeMs}`}let K=0;for(let J=0;J<Q.length;J++){let W=Q.charCodeAt(J);K=(K<<5)-K+W,K=K&K}return Math.abs(K).toString(36)}get(q,Z){let $=this.cache.get(q);if(!$)return null;let Q=this.getHash(Z,$.dependencies??[]);if($.hash!==Q)return this.cache.delete(q),null;return $.html}set(q,Z,$,Q){let K=this.getHash(Z,$);this.cache.set(q,{hash:K,html:Q,generatedAt:Date.now(),dependencies:$})}}class Rq{cacheDir;constructor(q){this.cacheDir=q}getFilePath(q){let Z=q.replace(/[^a-zA-Z0-9]/g,"_")+".json";return j.join(this.cacheDir,"isr",Z)}async get(q){let Z=this.getFilePath(q);if(!await Bun.file(Z).exists())return null;try{return JSON.parse(await Bun.file(Z).text())}catch{return null}}async set(q,Z){let $=this.getFilePath(q);await O.promises.mkdir(j.dirname($),{recursive:!0}),await Bun.write($,JSON.stringify(Z))}async invalidate(q){let Z=this.getFilePath(q);if(await Bun.file(Z).exists())await O.promises.unlink(Z)}async invalidatePattern(q){let Z=j.join(this.cacheDir,"isr");if(!O.existsSync(Z))return;let $=await O.promises.readdir(Z);for(let Q of $){let K=Q.replace(/_/g,"/").replace(".json","");if(q.test(K))await O.promises.unlink(j.join(Z,Q))}}async needsRevalidation(q){let Z=await this.get(q);if(!Z)return!0;return Date.now()>Z.revalidateAfter}}async function pq(q){try{let $=(await Bun.file(q).text()).match(/<script\s+server\b[^>]*>([\s\S]*?)<\/script>/i);if(!$)return null;let Q=$[1];if(!Q.includes("getStaticPaths"))return null;let K=Q.match(/(?:export\s+)?(?:async\s+)?function\s+getStaticPaths\s*\([^)]*\)\s*\{([\s\S]*?)\n[\t ]*\}/);if(!K)return null;return await Function(`
       return (async function getStaticPaths() {
         ${K[1]}
@@ -41,7 +41,7 @@ ${q.map((Q)=>{let K=new URL(Q.loc,Z).href,J=`  <url>
 ${$.join(`
 `)}
   </channel>
-</rss>`}async function aq(q={}){let Z=Date.now();Aq();let $=await n(process.cwd()),Q=$.build||{},K=await Kq({explicit:q.domain||Q.domain,stxConfig:$});if(K.source==="fallback"&&(q.sitemap??Q.sitemap??!0))console.warn(Wq());let J={router:q.router??$?.router??{},pagesDir:q.pagesDir||Q.pagesDir||"pages",outputDir:q.outputDir||Q.outputDir||"dist",baseUrl:q.baseUrl||Q.baseUrl||"/",domain:K.url,revalidate:q.revalidate??Q.revalidate??!1,sitemap:q.sitemap??Q.sitemap??!0,sitemapExclude:q.sitemapExclude||Q.sitemapExclude||[],robots:q.robots??Q.robots??!0,rss:q.rss??Q.rss??!1,concurrency:q.concurrency||Q.concurrency||10,cache:q.cache??Q.cache??!0,cacheDir:q.cacheDir||Q.cacheDir||d(process.cwd(),"ssg-cache"),contentLoaders:q.contentLoaders||[],hooks:q.hooks||{},minify:q.minify??Q.minify??!0,generate404:q.generate404??Q.generate404??!0,publicDir:q.publicDir||Q.publicDir||"public",trailingSlash:q.trailingSlash??Q.trailingSlash??!1,cleanOutput:q.cleanOutput??Q.cleanOutput??!0,cacheSalt:q.cacheSalt??"",partialsDir:q.partialsDir||$?.partialsDir||"",componentsDir:q.componentsDir||$?.componentsDir||"",failOnIncludeError:q.failOnIncludeError??!0,chunkIslands:q.chunkIslands===!0,prefetchIslands:q.prefetchIslands===!0,integrityIslands:q.integrityIslands===!0},W={totalPages:0,successCount:0,failedCount:0,cachedCount:0,buildTime:0,pages:[],errors:[]},z=new Set,A=0,G={},X={};await J.hooks.onBuildStart?.();try{if(J.cleanOutput&&O.existsSync(J.outputDir))await O.promises.rm(J.outputDir,{recursive:!0});await O.promises.mkdir(J.outputDir,{recursive:!0});let L=J.cacheSalt;if(!L){let{resolveUserCssConfig:Y,fingerprintConfig:N}=await import("./chunk-gkq323fg.js");try{L=N(await Y(process.cwd()))}catch{}}let{prepareImageDelivery:_}=await import("./chunk-8tsr51hj.js"),F=await _(J.publicDir,J.outputDir);if(F.count>0)console.log(`Optimized ${F.count} image(s) for responsive delivery`),L=[L,F.fingerprint].filter(Boolean).join(":");let C=new wq(J.cacheDir,L);if(J.cache)await C.load();try{let{generateCss:Y}=await import("./chunk-gkq323fg.js");await Y('<div class="bg-black"></div>')}catch{}Yq();let kq=$?.routeMiddleware?.dir||"middleware";await jq(process.cwd(),kq);let p=Vq();if(p.length>0)console.log(`Loaded ${p.length} middleware: ${p.join(", ")}`);let bq=$?.routeMiddleware?.global||[];Fq($?.layoutsDir,d(process.cwd()));let i=l(".",{pagesDir:J.pagesDir,pagesDirs:$?._layerPageDirs});console.log(`Found ${i.length} routes`);let g=[];for(let Y of i){let N=await uq(Y);for(let H of N)g.push({route:Y,url:H.url,params:H.params,props:H.props,revalidate:H.revalidate??J.revalidate})}W.totalPages=g.length,console.log(`Generating ${W.totalPages} pages...`);let b=[],s=[];for(let Y=0;Y<g.length;Y+=J.concurrency)s.push(g.slice(Y,Y+J.concurrency));for(let Y of s)await Promise.all(Y.map(async(N)=>{let{route:H,url:V,params:S,props:Sq,revalidate:a}=N;try{await J.hooks.onPageStart?.(V);let w=await Bun.file(H.filePath).text(),R=JJ(w),vq=R?.middleware?Array.isArray(R.middleware)?R.middleware:[R.middleware]:[],t=[...bq,...vq];if(t.length>0){let D=Gq(V,S,R||{}),M=Lq(D,null,void 0,{isServer:!0}),E=await Nq(t,M);if(E.redirect){let U=typeof E.redirect==="string"?E.redirect:E.redirect.path||E.redirect,x=QJ(String(U),V),k=ZJ(V,J);await O.promises.mkdir(j.dirname(k),{recursive:!0}),await Bun.write(k,x),W.successCount++,W.pages.push({route:V,outputPath:k,size:Buffer.byteLength(x),cached:!1}),b.push({loc:V,lastmod:new Date().toISOString()}),console.log(`  \u21B3 ${V} \u2192 redirect to ${U}`);return}if(E.abort){let U=typeof E.abort==="string"?E.abort:E.abort?.error?.message||"aborted";console.warn(`  \u21B3 ${V} \u2014 middleware aborted: ${U}`);return}}let e=w.match(/definePageMeta\s*\(\s*\{[\s\S]*?validate\s*:\s*((?:\([^)]*\)|[^,}])*(?:\{[\s\S]*?\})?)/m);if(e)try{if(!await Function("route",`
+</rss>`}async function aq(q={}){let Z=Date.now();Aq();let $=await n(process.cwd()),Q=$.build||{},K=await Kq({explicit:q.domain||Q.domain,stxConfig:$});if(K.source==="fallback"&&(q.sitemap??Q.sitemap??!0))console.warn(Wq());let J={router:q.router??$?.router??{},pagesDir:q.pagesDir||Q.pagesDir||"pages",outputDir:q.outputDir||Q.outputDir||"dist",baseUrl:q.baseUrl||Q.baseUrl||"/",domain:K.url,revalidate:q.revalidate??Q.revalidate??!1,sitemap:q.sitemap??Q.sitemap??!0,sitemapExclude:q.sitemapExclude||Q.sitemapExclude||[],robots:q.robots??Q.robots??!0,rss:q.rss??Q.rss??!1,concurrency:q.concurrency||Q.concurrency||10,cache:q.cache??Q.cache??!0,cacheDir:q.cacheDir||Q.cacheDir||d(process.cwd(),"ssg-cache"),contentLoaders:q.contentLoaders||[],hooks:q.hooks||{},minify:q.minify??Q.minify??!0,generate404:q.generate404??Q.generate404??!0,publicDir:q.publicDir||Q.publicDir||"public",trailingSlash:q.trailingSlash??Q.trailingSlash??!1,cleanOutput:q.cleanOutput??Q.cleanOutput??!0,cacheSalt:q.cacheSalt??"",partialsDir:q.partialsDir||$?.partialsDir||"",componentsDir:q.componentsDir||$?.componentsDir||"",failOnIncludeError:q.failOnIncludeError??!0,chunkIslands:q.chunkIslands===!0,prefetchIslands:q.prefetchIslands===!0,integrityIslands:q.integrityIslands===!0},W={totalPages:0,successCount:0,failedCount:0,cachedCount:0,buildTime:0,pages:[],errors:[]},z=new Set,A=0,G={},X={};await J.hooks.onBuildStart?.();try{if(J.cleanOutput&&O.existsSync(J.outputDir))await O.promises.rm(J.outputDir,{recursive:!0});await O.promises.mkdir(J.outputDir,{recursive:!0});let L=J.cacheSalt;if(!L){let{resolveUserCssConfig:Y,fingerprintConfig:N}=await import("./chunk-pwhf5kte.js");try{L=N(await Y(process.cwd()))}catch{}}let{prepareImageDelivery:_}=await import("./chunk-4pg6wbt6.js"),F=await _(J.publicDir,J.outputDir);if(F.count>0)console.log(`Optimized ${F.count} image(s) for responsive delivery`),L=[L,F.fingerprint].filter(Boolean).join(":");let C=new wq(J.cacheDir,L);if(J.cache)await C.load();try{let{generateCss:Y}=await import("./chunk-pwhf5kte.js");await Y('<div class="bg-black"></div>')}catch{}Yq();let kq=$?.routeMiddleware?.dir||"middleware";await jq(process.cwd(),kq);let p=Vq();if(p.length>0)console.log(`Loaded ${p.length} middleware: ${p.join(", ")}`);let bq=$?.routeMiddleware?.global||[];Fq($?.layoutsDir,d(process.cwd()));let i=l(".",{pagesDir:J.pagesDir,pagesDirs:$?._layerPageDirs});console.log(`Found ${i.length} routes`);let g=[];for(let Y of i){let N=await uq(Y);for(let H of N)g.push({route:Y,url:H.url,params:H.params,props:H.props,revalidate:H.revalidate??J.revalidate})}W.totalPages=g.length,console.log(`Generating ${W.totalPages} pages...`);let b=[],s=[];for(let Y=0;Y<g.length;Y+=J.concurrency)s.push(g.slice(Y,Y+J.concurrency));for(let Y of s)await Promise.all(Y.map(async(N)=>{let{route:H,url:V,params:S,props:Sq,revalidate:a}=N;try{await J.hooks.onPageStart?.(V);let w=await Bun.file(H.filePath).text(),R=JJ(w),vq=R?.middleware?Array.isArray(R.middleware)?R.middleware:[R.middleware]:[],t=[...bq,...vq];if(t.length>0){let D=Gq(V,S,R||{}),M=Lq(D,null,void 0,{isServer:!0}),E=await Nq(t,M);if(E.redirect){let U=typeof E.redirect==="string"?E.redirect:E.redirect.path||E.redirect,x=QJ(String(U),V),k=ZJ(V,J);await O.promises.mkdir(j.dirname(k),{recursive:!0}),await Bun.write(k,x),W.successCount++,W.pages.push({route:V,outputPath:k,size:Buffer.byteLength(x),cached:!1}),b.push({loc:V,lastmod:new Date().toISOString()}),console.log(`  \u21B3 ${V} \u2192 redirect to ${U}`);return}if(E.abort){let U=typeof E.abort==="string"?E.abort:E.abort?.error?.message||"aborted";console.warn(`  \u21B3 ${V} \u2014 middleware aborted: ${U}`);return}}let e=w.match(/definePageMeta\s*\(\s*\{[\s\S]*?validate\s*:\s*((?:\([^)]*\)|[^,}])*(?:\{[\s\S]*?\})?)/m);if(e)try{if(!await Function("route",`
                 const validate = ${e[1]};
                 return validate(route);
               `)({params:S})){console.warn(`Validation failed for ${V}, skipping...`);return}}catch{}let I=null,qq=!1;if(J.cache){if(I=C.get(V,H.filePath),I)qq=!0,W.cachedCount++}if(!I){let D=await Mq(H,S,Sq,J,$);if(I=D.html,J.failOnIncludeError&&D.includeFailures.length>0)throw Error(`${D.includeFailures.length} include(s) failed to resolve, so this page would have shipped with an error banner where the markup should be:

package/dist/types/directive-types.d.ts

@@ -292,6 +292,18 @@ export interface CustomDirective {
     handler: CustomDirectiveHandler;
     /** Whether the directive has a closing tag (e.g., @directive...@enddirective) */
     hasEndTag?: boolean;
+    /**
+     * Pass each argument exactly as written, quotes included, split only at
+     * top-level commas, instead of with its quotes stripped.
+     *
+     * Stripping quotes erases the difference between `'title'` (the word) and
+     * `title` (a variable), and splitting at every comma breaks `fn(a, b)` apart,
+     * so a directive that evaluates its arguments needs this. The call is also
+     * matched by balance rather than a pattern, so `'Smile :)'` and nested calls
+     * stay inside it. Parse a literal with `parseStringLiteral` and evaluate the
+     * rest with `evaluateDirectiveArgument` (directive-arguments.ts).
+     */
+    rawParams?: boolean;
     /** Optional description for documentation */
     description?: string;
 }