@ampless/runtime 1.0.0-alpha.35 → 1.0.0-alpha.37

package/dist/index.d.ts

@@ -162,6 +162,23 @@ interface PluginHeadApi {
      * scoped to structured data — see `PublicPostBodyDescriptor`.
      */
     renderBodyForPost(post: Post): Promise<ReactNode>;
+    /**
+     * Per-post visible HTML (Phase 6d). Aggregates all installed plugins'
+     * `publicHtmlForPost` descriptors, sanitizes bodies under a strict
+     * `sanitize-html` allowlist, resolves namespaces, deduplicates, and
+     * returns position-bucketed ReactNodes ready to embed in theme post
+     * templates. Themes never call `dangerouslySetInnerHTML` themselves.
+     */
+    renderHtmlForPost(post: Post): Promise<PublicHtmlForPostResult>;
+}
+/**
+ * Position-bucketed result of `renderHtmlForPost`. Themes embed these
+ * directly with `{html.beforeContent}` / `{html.afterContent}`. A `null`
+ * slot means no plugins contributed HTML to that position.
+ */
+interface PublicHtmlForPostResult {
+    beforeContent: ReactNode | null;
+    afterContent: ReactNode | null;
 }
 /**
  * Escape characters that would let a value break out of an inline
@@ -463,6 +480,16 @@ interface Ampless {
      * runtime auto-escapes `<`, `>`, `&`, U+2028, U+2029 in the body.
      */
     publicBodyForPost(post: Post): Promise<ReactNode>;
+    /**
+     * Per-post visible HTML aggregated across all installed plugins
+     * (Phase 6d `publicHtmlForPost` capability). Returns a position-
+     * bucketed result — themes embed `{html.beforeContent}` and
+     * `{html.afterContent}` around the post body. The runtime sanitizes
+     * every descriptor body with `sanitize-html` under a strict allowlist
+     * before wrapping it in a keyed `<div>` — themes never call
+     * `dangerouslySetInnerHTML` themselves.
+     */
+    publicHtmlForPost(post: Post): Promise<PublicHtmlForPostResult>;
     renderBody(post: Post): string;
     renderThemeCss(cssVars: Record<string, string>): string;
     publicAssetUrl(key: string): string;
@@ -489,4 +516,4 @@ interface Ampless {
  */
 declare function createAmpless(opts: CreateAmplessOpts): Ampless;
 
-export { type Ampless, type AmplessOutputs, COLOR_SCHEME_SETTING_KEY, type ColorScheme, type CreateAmplessOpts, DEFAULT_COLOR_SCHEME, type DataOutput, type EffectiveSiteSettings, type EffectiveThemeConfig, type ListPostsByTagOptions, type ListPostsOptions, type ListPostsResult, type MediaApi, type PluginHeadApi, type PluginSettingsApi, type PluginSettingsSnapshot, type PostsApi, type PublicMediaShape, type PublicPostConnectionShape, type PublicPostShape, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, SUPPORTED_API_VERSION, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, loadPackageManifest, markdownToHtml, renderBody, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };
+export { type Ampless, type AmplessOutputs, COLOR_SCHEME_SETTING_KEY, type ColorScheme, type CreateAmplessOpts, DEFAULT_COLOR_SCHEME, type DataOutput, type EffectiveSiteSettings, type EffectiveThemeConfig, type ListPostsByTagOptions, type ListPostsOptions, type ListPostsResult, type MediaApi, type PluginHeadApi, type PluginSettingsApi, type PluginSettingsSnapshot, type PostsApi, type PublicHtmlForPostResult, type PublicMediaShape, type PublicPostConnectionShape, type PublicPostShape, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, SUPPORTED_API_VERSION, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, loadPackageManifest, markdownToHtml, renderBody, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };

package/dist/index.js

@@ -230,6 +230,7 @@ import {
   Fragment,
   createElement
 } from "react";
+import sanitizeHtml from "sanitize-html";
 import {
   isValidPluginKey,
   resolvePluginSettings
@@ -604,6 +605,81 @@ function collectFor(plugins, site, snapshot, surface, renderOne) {
   const keyed = dedupeAndKey(entries);
   return createElement(Fragment, null, ...keyed);
 }
+var SANITIZE_OPTIONS = {
+  allowedTags: ["p", "span", "strong", "em", "a", "code", "br", "ul", "ol", "li"],
+  allowedAttributes: {
+    "*": ["class", "data-words", "data-minutes", "data-ampless-*"],
+    a: ["href", "rel", "target"]
+  },
+  allowedSchemes: ["http", "https"],
+  allowedSchemesAppliedToAttributes: ["href"],
+  allowProtocolRelative: false,
+  transformTags: {
+    a: (tagName, attribs) => {
+      const out = { ...attribs };
+      if (out["target"] === "_blank") {
+        const parts = (out["rel"] ?? "").split(/\s+/).filter(Boolean);
+        if (!parts.includes("noopener")) parts.push("noopener");
+        if (!parts.includes("noreferrer")) parts.push("noreferrer");
+        out["rel"] = parts.join(" ");
+      }
+      return { tagName, attribs: out };
+    }
+  }
+};
+function validateHtmlDescriptor(descriptor, pluginLabel, index) {
+  if (descriptor === null || typeof descriptor !== "object") {
+    warn(
+      `${pluginLabel}: publicHtmlForPost descriptor #${index} dropped \u2014 must be an object.`
+    );
+    return false;
+  }
+  const d = descriptor;
+  if (d.type !== "html") {
+    warn(
+      `${pluginLabel}: publicHtmlForPost descriptor #${index} dropped \u2014 "type" must be "html" (got ${typeof d.type === "string" ? `"${d.type}"` : typeof d.type}).`
+    );
+    return false;
+  }
+  if (typeof d.id !== "string") {
+    warn(
+      `${pluginLabel}: publicHtmlForPost descriptor #${index} dropped \u2014 "id" must be a string.`
+    );
+    return false;
+  }
+  if (typeof d.body !== "string") {
+    warn(
+      `${pluginLabel}: publicHtmlForPost descriptor "${d.id}" dropped \u2014 "body" must be a string.`
+    );
+    return false;
+  }
+  if (d.position !== "beforeContent" && d.position !== "afterContent") {
+    warn(
+      `${pluginLabel}: publicHtmlForPost descriptor "${d.id}" dropped \u2014 "position" must be "beforeContent" or "afterContent" (got ${typeof d.position === "string" ? `"${d.position}"` : typeof d.position}).`
+    );
+    return false;
+  }
+  return true;
+}
+function validateHtmlId(id, pluginLabel) {
+  if (id.length === 0) {
+    warn(`${pluginLabel}: publicHtmlForPost descriptor dropped \u2014 "id" must not be empty.`);
+    return false;
+  }
+  if (/[\x00-\x1f]/.test(id)) {
+    warn(
+      `${pluginLabel}: publicHtmlForPost descriptor "${id}" dropped \u2014 "id" contains control characters.`
+    );
+    return false;
+  }
+  if (id.length > 64) {
+    warn(
+      `${pluginLabel}: publicHtmlForPost descriptor "${id.slice(0, 32)}\u2026" dropped \u2014 "id" exceeds 64 characters.`
+    );
+    return false;
+  }
+  return true;
+}
 function collectForPost(plugins, site, snapshot, post) {
   const entries = [];
   for (const plugin of plugins) {
@@ -629,6 +705,63 @@ function collectForPost(plugins, site, snapshot, post) {
   const keyed = dedupeAndKey(entries);
   return createElement(Fragment, null, ...keyed);
 }
+function collectHtmlForPost(plugins, site, snapshot, post) {
+  const before = [];
+  const after = [];
+  const seenBefore = /* @__PURE__ */ new Set();
+  const seenAfter = /* @__PURE__ */ new Set();
+  for (const plugin of plugins) {
+    const factory = plugin.publicHtmlForPost;
+    if (!factory) continue;
+    const namespace = plugin.instanceId ?? plugin.name;
+    const label = `plugin "${plugin.instanceId ?? plugin.name}"`;
+    const ctx = makeCtx(plugin, site, snapshot);
+    let descriptors;
+    try {
+      descriptors = factory.call(plugin, post, ctx) ?? [];
+    } catch (err) {
+      warn(
+        `${label}: threw inside publicHtmlForPost callback: ${err instanceof Error ? err.message : String(err)}`
+      );
+      continue;
+    }
+    for (let i = 0; i < descriptors.length; i++) {
+      const raw = descriptors[i];
+      if (!validateHtmlDescriptor(raw, label, i)) continue;
+      const descriptor = raw;
+      if (!validateHtmlId(descriptor.id, label)) continue;
+      const dedupeKey = `${namespace}:${descriptor.id}`;
+      const position = descriptor.position;
+      const seenSet = position === "beforeContent" ? seenBefore : seenAfter;
+      const bucket = position === "beforeContent" ? before : after;
+      if (seenSet.has(dedupeKey)) {
+        warn(
+          `${label}: publicHtmlForPost descriptor "${descriptor.id}" at position "${position}" is a duplicate \u2014 keeping the first occurrence.`
+        );
+        continue;
+      }
+      seenSet.add(dedupeKey);
+      const cleanHtml = sanitizeHtml(descriptor.body, SANITIZE_OPTIONS);
+      bucket.push({ key: dedupeKey, cleanHtml, namespace });
+    }
+  }
+  function toReactNode(entries, position) {
+    if (entries.length === 0) return null;
+    const elements = entries.map(
+      ({ key, cleanHtml, namespace }) => createElement("div", {
+        key,
+        "data-ampless-plugin": namespace,
+        "data-ampless-position": position,
+        dangerouslySetInnerHTML: { __html: cleanHtml }
+      })
+    );
+    return createElement(Fragment, null, ...elements);
+  }
+  return {
+    beforeContent: toReactNode(before, "beforeContent"),
+    afterContent: toReactNode(after, "afterContent")
+  };
+}
 function createPluginHead(cmsConfig, pluginSettings) {
   const plugins = (cmsConfig.plugins ?? []).filter(isPlugin2);
   const validPlugins = [];
@@ -693,6 +826,16 @@ function createPluginHead(cmsConfig, pluginSettings) {
           `${label}: implements \`publicBodyForPost\` but "schema" is not in declared capabilities. Add it so admin UI / capability gates see the surface.`
         );
       }
+      if (caps.includes("publicHtmlForPost") && !plugin.publicHtmlForPost) {
+        warn(
+          `${label}: declares capability "publicHtmlForPost" but no \`publicHtmlForPost\` implementation. Drop the capability or add the function.`
+        );
+      }
+      if (plugin.publicHtmlForPost && !caps.includes("publicHtmlForPost")) {
+        warn(
+          `${label}: implements \`publicHtmlForPost\` but "publicHtmlForPost" is not in declared capabilities. Add it so admin UI / capability gates see the surface.`
+        );
+      }
     }
   }
   return {
@@ -719,6 +862,10 @@ function createPluginHead(cmsConfig, pluginSettings) {
     async renderBodyForPost(post) {
       const snapshot = await pluginSettings.loadAll();
       return collectForPost(validPlugins, cmsConfig.site, snapshot, post);
+    },
+    async renderHtmlForPost(post) {
+      const snapshot = await pluginSettings.loadAll();
+      return collectHtmlForPost(validPlugins, cmsConfig.site, snapshot, post);
     }
   };
 }
@@ -1211,6 +1358,7 @@ function createAmpless(opts) {
     publicHead: () => pluginHead.renderHead(),
     publicBodyEnd: () => pluginHead.renderBodyEnd(),
     publicBodyForPost: (post) => pluginHead.renderBodyForPost(post),
+    publicHtmlForPost: (post) => pluginHead.renderHtmlForPost(post),
     renderBody: (post) => renderBody(post),
     renderThemeCss: (cssVars) => renderThemeCss(cssVars),
     publicAssetUrl: (key) => storage.publicAssetUrl(key),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/runtime",
-  "version": "1.0.0-alpha.35",
+  "version": "1.0.0-alpha.37",
   "description": "Public-side runtime for ampless: post fetching, theme dispatch, middleware, public route handlers",
   "license": "MIT",
   "type": "module",
@@ -48,19 +48,21 @@
     "clsx": "^2.1.1",
     "lucide-react": "^1.16.0",
     "marked": "^18.0.4",
+    "sanitize-html": "^2.17.4",
     "tailwind-merge": "^3.6.0",
-    "ampless": "1.0.0-alpha.27",
-    "@ampless/plugin-og-image": "0.2.0-alpha.27"
+    "@ampless/plugin-og-image": "0.2.0-alpha.29",
+    "ampless": "1.0.0-alpha.29"
   },
   "peerDependencies": {
+    "@aws-amplify/adapter-nextjs": "^1",
+    "aws-amplify": "^6",
     "next": "^15 || ^16",
     "react": "^18 || ^19",
-    "react-dom": "^18 || ^19",
-    "aws-amplify": "^6",
-    "@aws-amplify/adapter-nextjs": "^1"
+    "react-dom": "^18 || ^19"
   },
   "devDependencies": {
     "@types/react": "^19.2.15",
+    "@types/sanitize-html": "^2.16.1",
     "next": "^16.2.6",
     "react": "^19.2.6"
   },