@ampless/runtime 1.0.0-alpha.25 → 1.0.0-alpha.27

package/dist/index.d.ts

@@ -153,7 +153,37 @@ interface PluginHeadApi {
     renderHead(): Promise<ReactNode>;
     /** React children safe to drop just before `</body>`. */
     renderBodyEnd(): Promise<ReactNode>;
+    /**
+     * Per-post body descriptors (Phase 4). Themes call this from their
+     * post template to render plugin-supplied `<script
+     * type="application/ld+json">` descriptors keyed off the specific
+     * post being viewed. Limited to `inlineScript` with
+     * `scriptType: 'application/ld+json'` so the per-post surface stays
+     * scoped to structured data — see `PublicPostBodyDescriptor`.
+     */
+    renderBodyForPost(post: Post): Promise<ReactNode>;
 }
+/**
+ * Escape characters that would let a value break out of an inline
+ * `<script type="application/ld+json">` body. Applied automatically by
+ * the runtime to ANY inlineScript descriptor whose `scriptType` is
+ * `'application/ld+json'`, regardless of which surface
+ * (`publicHead` / `publicBodyEnd` / `publicBodyForPost`) emitted it.
+ * Plugin authors do not need to call this themselves; it's exported so
+ * other hand-rolled inline-JSON-LD code paths can reuse it.
+ *
+ * Each character is replaced with its `\uXXXX` form — a JSON-legal way
+ * to encode the same character inside a JSON string, so the JSON
+ * payload still parses but the HTML parser can no longer see a closing
+ * `</script>` sequence:
+ *
+ *   '<'      → '\u003c'
+ *   '>'      → '\u003e'
+ *   '&'      → '\u0026'
+ *   U+2028   → '\u2028'
+ *   U+2029   → '\u2029'
+ */
+declare function escapeJsonLdInlineBody(value: string): string;
 /**
  * Create the head/body renderer for a `Config`. The constructor-time
  * pass logs a single dev warning when two plugins share an
@@ -384,6 +414,16 @@ interface Ampless {
     siteMetadata(): Promise<Metadata>;
     publicHead(): Promise<ReactNode>;
     publicBodyEnd(): Promise<ReactNode>;
+    /**
+     * Per-post body descriptors (Phase 4 `schema` capability). Theme
+     * post templates render the result so plugins like
+     * `@ampless/plugin-schema-jsonld` can emit
+     * `<script type="application/ld+json">` Article schema keyed off
+     * the specific post being viewed. Limited to inline-script
+     * descriptors with `scriptType: 'application/ld+json'` — the
+     * runtime auto-escapes `<`, `>`, `&`, U+2028, U+2029 in the body.
+     */
+    publicBodyForPost(post: Post): Promise<ReactNode>;
     renderBody(post: Post): string;
     renderThemeCss(cssVars: Record<string, string>): string;
     publicAssetUrl(key: string): string;
@@ -410,4 +450,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, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, createAmpless, createPluginHead, createPluginSettings, htmlToMarkdown, 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 PublicMediaShape, type PublicPostConnectionShape, type PublicPostShape, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, markdownToHtml, renderBody, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };

package/dist/index.js

@@ -289,6 +289,42 @@ function applyAttrs(target, attrs, ownerLabel) {
     target[k] = v;
   }
 }
+function escapeJsonLdInlineBody(value) {
+  return value.replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function inlineScriptTypeAllowed(surface, scriptType) {
+  if (scriptType === "application/ld+json") return true;
+  if (scriptType === void 0) {
+    return surface === "head" || surface === "body-end";
+  }
+  return false;
+}
+function renderInlineScript(descriptor, pluginLabel, index, surface) {
+  if (!descriptor.id) {
+    warn(
+      `${pluginLabel}: inlineScript descriptor #${index} dropped \u2014 missing required "id".`
+    );
+    return null;
+  }
+  if (!inlineScriptTypeAllowed(surface, descriptor.scriptType)) {
+    const got = descriptor.scriptType === void 0 ? "undefined" : `"${descriptor.scriptType}"`;
+    const allowed = surface === "body-for-post" ? `"application/ld+json" (required on publicBodyForPost \u2014 the per-post surface is scoped to JSON-LD)` : `undefined or "application/ld+json"`;
+    warn(
+      `${pluginLabel}: inlineScript "${descriptor.id}" dropped \u2014 scriptType ${got} not allowed on ${surface}. Allowed: ${allowed}.`
+    );
+    return null;
+  }
+  const body = descriptor.scriptType === "application/ld+json" ? escapeJsonLdInlineBody(descriptor.body) : descriptor.body;
+  const props = {
+    id: descriptor.id,
+    dangerouslySetInnerHTML: { __html: body }
+  };
+  if (descriptor.scriptType) props.type = descriptor.scriptType;
+  return {
+    id: descriptor.id,
+    element: createElement("script", props)
+  };
+}
 function renderHeadDescriptor(descriptor, pluginLabel, index) {
   switch (descriptor.type) {
     case "script": {
@@ -319,22 +355,8 @@ function renderHeadDescriptor(descriptor, pluginLabel, index) {
         element: createElement("script", props)
       };
     }
-    case "inlineScript": {
-      if (!descriptor.id) {
-        warn(
-          `${pluginLabel}: inlineScript descriptor #${index} dropped \u2014 missing required "id".`
-        );
-        return null;
-      }
-      const props = {
-        id: descriptor.id,
-        dangerouslySetInnerHTML: { __html: descriptor.body }
-      };
-      return {
-        id: descriptor.id,
-        element: createElement("script", props)
-      };
-    }
+    case "inlineScript":
+      return renderInlineScript(descriptor, pluginLabel, index, "head");
     case "meta": {
       const props = { content: descriptor.content };
       if (descriptor.name) props.name = descriptor.name;
@@ -401,8 +423,20 @@ function renderBodyDescriptor(descriptor, pluginLabel, index) {
       element: createElement("iframe", props)
     };
   }
+  if (descriptor.type === "inlineScript") {
+    return renderInlineScript(descriptor, pluginLabel, index, "body-end");
+  }
   return renderHeadDescriptor(descriptor, pluginLabel, index);
 }
+function renderPostBodyDescriptor(descriptor, pluginLabel, index) {
+  if (descriptor.type !== "inlineScript") {
+    warn(
+      `${pluginLabel}: publicBodyForPost descriptor #${index} dropped \u2014 only inlineScript with scriptType "application/ld+json" is allowed on this surface.`
+    );
+    return null;
+  }
+  return renderInlineScript(descriptor, pluginLabel, index, "body-for-post");
+}
 function dedupeAndKey(entries) {
   const lastIndexById = /* @__PURE__ */ new Map();
   for (let i = 0; i < entries.length; i++) {
@@ -461,6 +495,31 @@ function collectFor(plugins, site, snapshot, surface, renderOne) {
   const keyed = dedupeAndKey(entries);
   return createElement(Fragment, null, ...keyed);
 }
+function collectForPost(plugins, site, snapshot, post) {
+  const entries = [];
+  for (const plugin of plugins) {
+    const factory = plugin.publicBodyForPost;
+    if (!factory) continue;
+    const ctx = makeCtx(plugin, site, snapshot);
+    let descriptors;
+    try {
+      descriptors = factory.call(plugin, post, ctx) ?? [];
+    } catch (err) {
+      warn(
+        `plugin "${plugin.instanceId ?? plugin.name}" threw inside publicBodyForPost callback: ${err instanceof Error ? err.message : String(err)}`
+      );
+      continue;
+    }
+    const label = `plugin "${plugin.instanceId ?? plugin.name}"`;
+    for (let i = 0; i < descriptors.length; i++) {
+      const entry = renderPostBodyDescriptor(descriptors[i], label, i);
+      if (entry) entries.push(entry);
+    }
+  }
+  if (entries.length === 0) return null;
+  const keyed = dedupeAndKey(entries);
+  return createElement(Fragment, null, ...keyed);
+}
 function createPluginHead(cmsConfig, pluginSettings) {
   const plugins = (cmsConfig.plugins ?? []).filter(isPlugin2);
   const validPlugins = [];
@@ -512,6 +571,16 @@ function createPluginHead(cmsConfig, pluginSettings) {
           `${label}: implements \`publicBodyEnd\` but "publicBody" is not in declared capabilities. Add it so admin UI / capability gates see the surface.`
         );
       }
+      if (caps.includes("schema") && !plugin.publicBodyForPost) {
+        warn(
+          `${label}: declares capability "schema" but no \`publicBodyForPost\` implementation. Drop the capability or add the function.`
+        );
+      }
+      if (plugin.publicBodyForPost && !caps.includes("schema")) {
+        warn(
+          `${label}: implements \`publicBodyForPost\` but "schema" is not in declared capabilities. Add it so admin UI / capability gates see the surface.`
+        );
+      }
     }
   }
   return {
@@ -534,6 +603,10 @@ function createPluginHead(cmsConfig, pluginSettings) {
         (p) => p.publicBodyEnd,
         renderBodyDescriptor
       );
+    },
+    async renderBodyForPost(post) {
+      const snapshot = await pluginSettings.loadAll();
+      return collectForPost(validPlugins, cmsConfig.site, snapshot, post);
     }
   };
 }
@@ -1025,6 +1098,7 @@ function createAmpless(opts) {
     siteMetadata: () => seo.siteMetadata(),
     publicHead: () => pluginHead.renderHead(),
     publicBodyEnd: () => pluginHead.renderBodyEnd(),
+    publicBodyForPost: (post) => pluginHead.renderBodyForPost(post),
     renderBody: (post) => renderBody(post),
     renderThemeCss: (cssVars) => renderThemeCss(cssVars),
     publicAssetUrl: (key) => storage.publicAssetUrl(key),
@@ -1050,6 +1124,7 @@ export {
   createAmpless,
   createPluginHead,
   createPluginSettings,
+  escapeJsonLdInlineBody,
   htmlToMarkdown,
   markdownToHtml,
   renderBody,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/runtime",
-  "version": "1.0.0-alpha.25",
+  "version": "1.0.0-alpha.27",
   "description": "Public-side runtime for ampless: post fetching, theme dispatch, middleware, public route handlers",
   "license": "MIT",
   "type": "module",
@@ -49,8 +49,8 @@
     "lucide-react": "^1.16.0",
     "marked": "^18.0.4",
     "tailwind-merge": "^3.6.0",
-    "ampless": "1.0.0-alpha.19",
-    "@ampless/plugin-og-image": "0.2.0-alpha.19"
+    "ampless": "1.0.0-alpha.21",
+    "@ampless/plugin-og-image": "0.2.0-alpha.21"
   },
   "peerDependencies": {
     "next": "^15 || ^16",