@ampless/runtime 1.0.0-alpha.26 → 1.0.0-alpha.28

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Post, MediaMetadata, Config, ThemeModule, ThemeManifest } from 'ampless';
+import { Post, MediaMetadata, Config, ThemeModule, ThemeManifest, PluginPackageManifest } from 'ampless';
 export { Config, Post, ThemeManifest } from 'ampless';
 import { Metadata } from 'next';
 import { ReactNode } from 'react';
@@ -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
@@ -239,6 +269,45 @@ interface ThemeConfigApi {
  */
 declare function renderThemeCss(cssVars: Record<string, string>): string;
 
+/**
+ * Resolve `<packageName>/package.json`, read it, and return the
+ * `amplessPlugin` field as a typed `PluginPackageManifest`. Returns
+ * `null` for any failure — the caller skips cross-check rather than
+ * aborting plugin loading.
+ *
+ * Failure modes that resolve to `null`:
+ *   - Package not installed at this resolution root
+ *     (`ERR_MODULE_NOT_FOUND`)
+ *   - `package.json` not in the package's `exports`
+ *     (`ERR_PACKAGE_PATH_NOT_EXPORTED`) — see the spec under
+ *     `docs/tmp/plugin-extension-phase5.md` §B
+ *   - `readFileSync` throws (e.g. ENOENT, permissions)
+ *   - JSON parse error
+ *   - `amplessPlugin` field absent or not an object
+ *   - `amplessPlugin` field present but structurally invalid (e.g.
+ *     `apiVersion` not a number, `capabilities` not an array of
+ *     strings, `trustLevel` not one of the three allowed values) —
+ *     see `isValidManifest`
+ *
+ * The structural check matters: without it, a downstream consumer
+ * like `crossCheckStaticManifest`'s `for ... of` over the manifest's
+ * `capabilities` would crash on `capabilities: {}` or `capabilities: 42`,
+ * which is at odds with the "non-apiVersion mismatches warn rather
+ * than throw" policy.
+ *
+ * After this function returns a non-null value, the caller can trust
+ * every field it inspects has the declared type; mismatches against
+ * the factory return value are still surfaced as warnings (or, for
+ * `apiVersion`, throws) by the caller itself.
+ */
+declare function loadPackageManifest(packageName: string): PluginPackageManifest | null;
+/**
+ * Maximum `apiVersion` value this runtime can host. Plugins declaring
+ * a higher value are rejected at constructor time — the runtime can't
+ * safely call into surfaces it doesn't know about yet.
+ */
+declare const SUPPORTED_API_VERSION: 1;
+
 declare function renderBody(post: Post): string;
 /**
  * Convert a tiptap doc to its HTML form. Same renderer the public
@@ -384,6 +453,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 +489,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, 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

@@ -234,6 +234,53 @@ import {
   isValidPluginKey,
   resolvePluginSettings
 } from "ampless";
+
+// src/plugin-package-manifest.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+var TRUST_LEVELS = ["untrusted", "trusted", "privileged"];
+function isValidManifest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  if (typeof v.apiVersion !== "number") return false;
+  if (typeof v.name !== "string") return false;
+  if (typeof v.trustLevel !== "string") return false;
+  if (!TRUST_LEVELS.includes(v.trustLevel)) return false;
+  if (!Array.isArray(v.capabilities)) return false;
+  for (const c of v.capabilities) {
+    if (typeof c !== "string") return false;
+  }
+  return true;
+}
+function loadPackageManifest(packageName) {
+  let resolvedUrl;
+  try {
+    resolvedUrl = import.meta.resolve(`${packageName}/package.json`);
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    raw = readFileSync(fileURLToPath(resolvedUrl), "utf8");
+  } catch {
+    return null;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof pkg !== "object" || pkg === null || !("amplessPlugin" in pkg)) {
+    return null;
+  }
+  const manifest = pkg.amplessPlugin;
+  if (!isValidManifest(manifest)) return null;
+  return manifest;
+}
+var SUPPORTED_API_VERSION = 1;
+
+// src/plugin-head.ts
 function isPlugin2(p) {
   return typeof p === "object" && p !== null && "apiVersion" in p;
 }
@@ -277,6 +324,50 @@ function warn(message) {
   if (!isDev()) return;
   console.warn(`[ampless plugin-head] ${message}`);
 }
+function crossCheckStaticManifest(plugin, label) {
+  const packageName = plugin.packageName;
+  const manifest = loadPackageManifest(packageName);
+  if (!manifest) return;
+  if (typeof manifest.apiVersion !== "number") {
+    throw new Error(
+      `${label}: package.json#amplessPlugin.apiVersion is not a number (got ${JSON.stringify(manifest.apiVersion)}). Update the plugin's package.json or remove the amplessPlugin field.`
+    );
+  }
+  if (manifest.apiVersion > SUPPORTED_API_VERSION) {
+    throw new Error(
+      `${label}: package.json#amplessPlugin.apiVersion ${manifest.apiVersion} is newer than this runtime supports (max ${SUPPORTED_API_VERSION}). Upgrade @ampless/runtime, or pin an older version of the plugin.`
+    );
+  }
+  if (manifest.apiVersion !== plugin.apiVersion) {
+    throw new Error(
+      `${label}: apiVersion mismatch \u2014 package.json declares ${manifest.apiVersion}, factory declares ${plugin.apiVersion}. The two must agree.`
+    );
+  }
+  if (manifest.name !== plugin.name) {
+    warn(
+      `${label}: name mismatch \u2014 package.json#amplessPlugin.name is "${manifest.name}", factory returns name="${plugin.name}". Align them so admin UI / capability gates can identify the plugin consistently.`
+    );
+  }
+  if (manifest.trustLevel !== plugin.trust_level) {
+    warn(
+      `${label}: trustLevel mismatch \u2014 package.json declares "${manifest.trustLevel}", factory declares trust_level="${plugin.trust_level}". The processor IAM policies are wired off trust_level; drift here usually means the deployment lambda runs in the wrong context.`
+    );
+  }
+  const factoryCaps = Array.isArray(plugin.capabilities) ? plugin.capabilities : [];
+  const manifestCaps = manifest.capabilities;
+  if (!setsEqual(factoryCaps, manifestCaps)) {
+    warn(
+      `${label}: capabilities mismatch \u2014 package.json declares [${manifestCaps.join(", ")}], factory declares [${factoryCaps.join(", ")}]. The static manifest is what npm registry / admin UI surfaces show before the plugin loads, so it should match what the factory actually returns.`
+    );
+  }
+}
+function setsEqual(a, b) {
+  const sa = new Set(a);
+  const sb = new Set(b);
+  if (sa.size !== sb.size) return false;
+  for (const c of sb) if (!sa.has(c)) return false;
+  return true;
+}
 function applyAttrs(target, attrs, ownerLabel) {
   if (!attrs) return;
   for (const [k, v] of Object.entries(attrs)) {
@@ -289,6 +380,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 +446,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 +514,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 +586,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 = [];
@@ -490,6 +640,9 @@ function createPluginHead(cmsConfig, pluginSettings) {
       }
     }
     validPlugins.push(plugin);
+    if (plugin.packageName) {
+      crossCheckStaticManifest(plugin, label);
+    }
     const caps = plugin.capabilities;
     if (caps) {
       if (caps.includes("publicHead") && !plugin.publicHead) {
@@ -512,6 +665,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 +697,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 +1192,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),
@@ -1046,11 +1214,14 @@ function createAmpless(opts) {
 export {
   COLOR_SCHEME_SETTING_KEY,
   DEFAULT_COLOR_SCHEME,
+  SUPPORTED_API_VERSION,
   _resetStreamS3Cache,
   createAmpless,
   createPluginHead,
   createPluginSettings,
+  escapeJsonLdInlineBody,
   htmlToMarkdown,
+  loadPackageManifest,
   markdownToHtml,
   renderBody,
   renderThemeCss,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/runtime",
-  "version": "1.0.0-alpha.26",
+  "version": "1.0.0-alpha.28",
   "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.20",
-    "@ampless/plugin-og-image": "0.2.0-alpha.20"
+    "ampless": "1.0.0-alpha.22",
+    "@ampless/plugin-og-image": "0.2.0-alpha.22"
   },
   "peerDependencies": {
     "next": "^15 || ^16",