npm - @ampless/runtime - Versions diffs - 1.0.0-alpha.22 → 1.0.0-alpha.24 - Mend

@ampless/runtime 1.0.0-alpha.22 → 1.0.0-alpha.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/index.d.ts CHANGED Viewed

@@ -1,6 +1,7 @@
-import { Post, MediaMetadata, ThemeModule, ThemeManifest, Config } from 'ampless';
+import { Post, MediaMetadata, Config, ThemeModule, ThemeManifest } from 'ampless';
 export { Config, Post, ThemeManifest } from 'ampless';
 import { Metadata } from 'next';
+import { ReactNode } from 'react';
 import { getProperties } from 'aws-amplify/storage/server';
 import { cookies } from 'next/headers';
@@ -122,6 +123,51 @@ interface SeoApi {
     siteMetadata(): Promise<Metadata>;
 }
+/**
+ * Per-instance flat map of stored field values, keyed by the field's
+ * `key` (not the full `plugins.<instanceId>.<key>` SK). The keys
+ * here mirror the field manifest so callers can hand the map
+ * directly to `resolvePluginSettings`.
+ */
+type PluginSettingsSnapshot = Map<string, Record<string, unknown>>;
+interface PluginSettingsApi {
+    /**
+     * Fetch all `plugins.*` settings from the public cache and bucket
+     * them by `instanceId`. Returns an empty Map on any failure mode
+     * (storage unconfigured, 404, JSON parse error) — callers fall
+     * back to manifest defaults so the layout never crashes when the
+     * cache is missing.
+     */
+    loadAll(): Promise<PluginSettingsSnapshot>;
+}
+declare function createPluginSettings(storage: StorageApi): PluginSettingsApi;
+interface PluginHeadApi {
+    /**
+     * React children safe to drop into `<head>`. Async because admin-
+     * managed settings are read from S3 on the first call per request.
+     * Within a single request both `renderHead` and `renderBodyEnd` share
+     * the same fetched snapshot via Next.js fetch dedup on the
+     * `site-settings` cache tag.
+     */
+    renderHead(): Promise<ReactNode>;
+    /** React children safe to drop just before `</body>`. */
+    renderBodyEnd(): Promise<ReactNode>;
+}
+/**
+ * Create the head/body renderer for a `Config`. The constructor-time
+ * pass logs a single dev warning when two plugins share an
+ * `instanceId ?? name`; everything else happens at render time so
+ * descriptors reflect per-request site config.
+ *
+ * `pluginSettings` (Phase 2) is the runtime accessor that pulls
+ * admin-managed `settings.public` values from the S3 site-settings
+ * cache. Within a single request we fetch once via `loadAll()` and
+ * bind a per-plugin `ctx.setting(key)` accessor before invoking
+ * either `publicHead` or `publicBodyEnd`.
+ */
+declare function createPluginHead(cmsConfig: Config, pluginSettings: PluginSettingsApi): PluginHeadApi;
 interface ThemesRegistry {
     /** Map of theme name → loaded theme module. */
     themes: Record<string, ThemeModule>;
@@ -336,6 +382,8 @@ interface Ampless {
     loadThemeConfig(): Promise<EffectiveThemeConfig>;
     postMetadata(post: Post): Promise<Metadata>;
     siteMetadata(): Promise<Metadata>;
+    publicHead(): Promise<ReactNode>;
+    publicBodyEnd(): Promise<ReactNode>;
     renderBody(post: Post): string;
     renderThemeCss(cssVars: Record<string, string>): string;
     publicAssetUrl(key: string): string;
@@ -350,6 +398,8 @@ interface Ampless {
     readonly themeActive: ThemeActiveApi;
     readonly themeConfig: ThemeConfigApi;
     readonly storageApi: StorageApi;
+    readonly pluginHead: PluginHeadApi;
+    readonly pluginSettings: PluginSettingsApi;
 }
 /**
  * Wire up the ampless runtime from user-supplied config blobs. The
@@ -360,4 +410,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 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, 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, htmlToMarkdown, markdownToHtml, renderBody, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };

package/dist/index.js CHANGED Viewed

@@ -225,6 +225,357 @@ function createSeo(cmsConfig, settingsApi) {
   };
 }
+// src/plugin-head.ts
+import {
+  Fragment,
+  createElement
+} from "react";
+import {
+  isValidPluginKey,
+  resolvePluginSettings
+} from "ampless";
+function isPlugin2(p) {
+  return typeof p === "object" && p !== null && "apiVersion" in p;
+}
+var ALLOWED_ATTRS = /* @__PURE__ */ new Set([
+  "crossorigin",
+  "referrerpolicy",
+  "integrity",
+  "fetchpriority",
+  // `nonce` is intentionally NOT in the allowlist for Phase 1. CSP
+  // nonce propagation is scoped out of Phase 1 (see spec §7); attrs
+  // shouldn't let plugins smuggle nonces past the design decision.
+  // The CSP nonce RFP will reintroduce it through `cspNonce` on
+  // PluginPublicRenderContext + `inlineScript.nonce: 'auto'`, not via
+  // the `attrs` bag.
+  "loading",
+  // iframe lazy-loading
+  "sandbox",
+  // iframe sandbox attribute
+  "allow",
+  // iframe permissions policy
+  "allowfullscreen"
+  // iframe fullscreen
+]);
+function isAllowedAttr(name) {
+  if (name.startsWith("data-")) return true;
+  return ALLOWED_ATTRS.has(name.toLowerCase());
+}
+function isSafeUrl(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+  const schemeMatch = trimmed.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
+  if (!schemeMatch) return true;
+  const scheme = schemeMatch[1].toLowerCase();
+  return scheme === "http" || scheme === "https";
+}
+function isDev() {
+  const env = typeof process !== "undefined" && process.env ? process.env.NODE_ENV : void 0;
+  return env !== "production";
+}
+function warn(message) {
+  if (!isDev()) return;
+  console.warn(`[ampless plugin-head] ${message}`);
+}
+function applyAttrs(target, attrs, ownerLabel) {
+  if (!attrs) return;
+  for (const [k, v] of Object.entries(attrs)) {
+    if (!isAllowedAttr(k)) {
+      warn(
+        `${ownerLabel}: attr "${k}" not in allowlist (data-* / crossorigin / referrerpolicy / integrity / fetchpriority / loading / sandbox / allow / allowfullscreen). skipping.`
+      );
+      continue;
+    }
+    target[k] = v;
+  }
+}
+function renderHeadDescriptor(descriptor, pluginLabel, index) {
+  switch (descriptor.type) {
+    case "script": {
+      if (!isSafeUrl(descriptor.src)) {
+        warn(
+          `${pluginLabel}: script descriptor #${index} dropped \u2014 unsafe src "${descriptor.src}".`
+        );
+        return null;
+      }
+      const props = {
+        src: descriptor.src
+      };
+      if (descriptor.id) props.id = descriptor.id;
+      const hasAsync = typeof descriptor.async === "boolean";
+      const hasDefer = typeof descriptor.defer === "boolean";
+      if (hasAsync) props.async = descriptor.async;
+      if (hasDefer) props.defer = descriptor.defer;
+      if (!hasAsync && !hasDefer) {
+        if (descriptor.strategy === "lazyOnload") {
+          props.defer = true;
+        } else {
+          props.async = true;
+        }
+      }
+      applyAttrs(props, descriptor.attrs, `${pluginLabel} script#${descriptor.id ?? index}`);
+      return {
+        id: descriptor.id ?? null,
+        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 "meta": {
+      const props = { content: descriptor.content };
+      if (descriptor.name) props.name = descriptor.name;
+      if (descriptor.property) props.property = descriptor.property;
+      return {
+        // meta has no id channel in the descriptor. Don't derive a
+        // dedup id from name/property — multiple `<meta name=...>`
+        // entries with the same name are legitimate (e.g. theme-color
+        // media variants, and two plugins emitting overlapping names
+        // is a real case the runtime shouldn't silently collapse).
+        // Position-based React keys handle the stable-key requirement.
+        id: null,
+        element: createElement("meta", props)
+      };
+    }
+    case "link": {
+      if (!isSafeUrl(descriptor.href)) {
+        warn(
+          `${pluginLabel}: link descriptor #${index} dropped \u2014 unsafe href "${descriptor.href}".`
+        );
+        return null;
+      }
+      const props = {
+        rel: descriptor.rel,
+        href: descriptor.href
+      };
+      if (descriptor.as) props.as = descriptor.as;
+      if (descriptor.typeAttr) props.type = descriptor.typeAttr;
+      return {
+        id: null,
+        element: createElement("link", props)
+      };
+    }
+    case "noscript": {
+      const props = {
+        dangerouslySetInnerHTML: { __html: descriptor.html }
+      };
+      if (descriptor.id) props.id = descriptor.id;
+      return {
+        id: descriptor.id ?? null,
+        element: createElement("noscript", props)
+      };
+    }
+  }
+}
+function renderBodyDescriptor(descriptor, pluginLabel, index) {
+  if (descriptor.type === "iframe") {
+    if (!isSafeUrl(descriptor.src)) {
+      warn(
+        `${pluginLabel}: iframe descriptor #${index} dropped \u2014 unsafe src "${descriptor.src}".`
+      );
+      return null;
+    }
+    const props = {
+      src: descriptor.src
+    };
+    if (descriptor.id) props.id = descriptor.id;
+    if (descriptor.title) props.title = descriptor.title;
+    if (typeof descriptor.width === "number") props.width = descriptor.width;
+    if (typeof descriptor.height === "number") props.height = descriptor.height;
+    applyAttrs(props, descriptor.attrs, `${pluginLabel} iframe#${descriptor.id ?? index}`);
+    return {
+      id: descriptor.id ?? null,
+      element: createElement("iframe", props)
+    };
+  }
+  return renderHeadDescriptor(descriptor, pluginLabel, index);
+}
+function dedupeAndKey(entries) {
+  const lastIndexById = /* @__PURE__ */ new Map();
+  for (let i = 0; i < entries.length; i++) {
+    const id = entries[i].id;
+    if (id === null) continue;
+    if (lastIndexById.has(id)) {
+      warn(`duplicate descriptor id "${id}" \u2014 keeping the last occurrence.`);
+    }
+    lastIndexById.set(id, i);
+  }
+  const kept = [];
+  for (let i = 0; i < entries.length; i++) {
+    const { id, element } = entries[i];
+    if (id !== null && lastIndexById.get(id) !== i) continue;
+    const key = id ?? `__pos-${i}`;
+    const existingProps = element.props;
+    kept.push(createElement(element.type, { ...existingProps, key }));
+  }
+  return kept;
+}
+function makeCtx(plugin, site, snapshot) {
+  const instanceId = plugin.instanceId ?? plugin.name;
+  const stored = snapshot.get(instanceId) ?? {};
+  const resolved = resolvePluginSettings(plugin.settings, stored);
+  return {
+    site,
+    setting(key) {
+      if (!isValidPluginKey(key)) return void 0;
+      const v = resolved[key];
+      return v === void 0 ? void 0 : v;
+    }
+  };
+}
+function collectFor(plugins, site, snapshot, surface, renderOne) {
+  const entries = [];
+  for (const plugin of plugins) {
+    const factory = surface(plugin);
+    if (!factory) continue;
+    const ctx = makeCtx(plugin, site, snapshot);
+    let descriptors;
+    try {
+      descriptors = factory.call(plugin, ctx) ?? [];
+    } catch (err) {
+      warn(
+        `plugin "${plugin.instanceId ?? plugin.name}" threw inside descriptor 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 = renderOne(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 = [];
+  const seenNamespaces = /* @__PURE__ */ new Set();
+  for (const plugin of plugins) {
+    const ns = plugin.instanceId ?? plugin.name;
+    const label = plugin.instanceId ? `${plugin.name}#${plugin.instanceId}` : plugin.name;
+    if (!isValidPluginKey(ns)) {
+      warn(
+        `${label}: plugin namespace "${ns}" violates ${`/^[a-zA-Z0-9_-]+$/`}. Use a simple identifier (letters / digits / "-" / "_"). Skipping plugin.`
+      );
+      continue;
+    }
+    if (seenNamespaces.has(ns)) {
+      warn(
+        `duplicate plugin namespace "${ns}" detected in cms.config.plugins. Set distinct \`instanceId\` on each instance to disambiguate.`
+      );
+    }
+    seenNamespaces.add(ns);
+    if (plugin.settings?.public) {
+      for (const field of plugin.settings.public) {
+        if (!isValidPluginKey(field.key)) {
+          warn(
+            `${label}: settings.public field key "${field.key}" violates ${`/^[a-zA-Z0-9_-]+$/`}. The field will not be readable through ctx.setting(). Rename the field key.`
+          );
+        }
+      }
+    }
+    validPlugins.push(plugin);
+    const caps = plugin.capabilities;
+    if (caps) {
+      if (caps.includes("publicHead") && !plugin.publicHead) {
+        warn(
+          `${label}: declares capability "publicHead" but no \`publicHead\` implementation. Drop the capability or add the function.`
+        );
+      }
+      if (caps.includes("publicBody") && !plugin.publicBodyEnd) {
+        warn(
+          `${label}: declares capability "publicBody" but no \`publicBodyEnd\` implementation. Drop the capability or add the function.`
+        );
+      }
+      if (plugin.publicHead && !caps.includes("publicHead")) {
+        warn(
+          `${label}: implements \`publicHead\` but "publicHead" is not in declared capabilities. Add it so admin UI / capability gates see the surface.`
+        );
+      }
+      if (plugin.publicBodyEnd && !caps.includes("publicBody")) {
+        warn(
+          `${label}: implements \`publicBodyEnd\` but "publicBody" is not in declared capabilities. Add it so admin UI / capability gates see the surface.`
+        );
+      }
+    }
+  }
+  return {
+    async renderHead() {
+      const snapshot = await pluginSettings.loadAll();
+      return collectFor(
+        validPlugins,
+        cmsConfig.site,
+        snapshot,
+        (p) => p.publicHead,
+        renderHeadDescriptor
+      );
+    },
+    async renderBodyEnd() {
+      const snapshot = await pluginSettings.loadAll();
+      return collectFor(
+        validPlugins,
+        cmsConfig.site,
+        snapshot,
+        (p) => p.publicBodyEnd,
+        renderBodyDescriptor
+      );
+    }
+  };
+}
+// src/plugin-settings.ts
+import { unflattenSettings as unflattenSettings2 } from "ampless";
+function createPluginSettings(storage) {
+  return {
+    async loadAll() {
+      const out = /* @__PURE__ */ new Map();
+      if (!storage.isStorageConfigured()) return out;
+      let url;
+      try {
+        url = storage.publicAssetUrl("public/site-settings.json");
+      } catch {
+        return out;
+      }
+      let flat;
+      try {
+        const res = await fetch(url, {
+          // Same revalidate + tag as site-settings.ts so a single
+          // request to the public route hits the JSON once and both
+          // helpers share the cached body.
+          next: { revalidate: 60, tags: ["site-settings"] }
+        });
+        if (!res.ok) return out;
+        flat = await res.json();
+      } catch {
+        return out;
+      }
+      const nested = unflattenSettings2(flat);
+      const pluginsBlock = nested.plugins;
+      if (!pluginsBlock || typeof pluginsBlock !== "object") return out;
+      for (const [instanceId, block] of Object.entries(pluginsBlock)) {
+        if (!block || typeof block !== "object" || Array.isArray(block)) continue;
+        out.set(instanceId, { ...block });
+      }
+      return out;
+    }
+  };
+}
 // src/theme-active.ts
 import { headers } from "next/headers";
 function createThemeActive(registry, storage) {
@@ -657,6 +1008,8 @@ function createAmpless(opts) {
   const media = createMediaApi(outputs);
   const settings = createSiteSettings(cmsConfig, storage);
   const seo = createSeo(cmsConfig, settings);
+  const pluginSettings = createPluginSettings(storage);
+  const pluginHead = createPluginHead(cmsConfig, pluginSettings);
   const themeActive = createThemeActive(themes, storage);
   const themeConfig = createThemeConfig(themeActive, storage);
   return {
@@ -670,6 +1023,8 @@ function createAmpless(opts) {
     loadThemeConfig: () => themeConfig.loadThemeConfig(),
     postMetadata: (post) => seo.postMetadata(post),
     siteMetadata: () => seo.siteMetadata(),
+    publicHead: () => pluginHead.renderHead(),
+    publicBodyEnd: () => pluginHead.renderBodyEnd(),
     renderBody: (post) => renderBody(post),
     renderThemeCss: (cssVars) => renderThemeCss(cssVars),
     publicAssetUrl: (key) => storage.publicAssetUrl(key),
@@ -683,7 +1038,9 @@ function createAmpless(opts) {
     seo,
     themeActive,
     themeConfig,
-    storageApi: storage
+    storageApi: storage,
+    pluginHead,
+    pluginSettings
   };
 }
 export {
@@ -691,6 +1048,8 @@ export {
   DEFAULT_COLOR_SCHEME,
   _resetStreamS3Cache,
   createAmpless,
+  createPluginHead,
+  createPluginSettings,
   htmlToMarkdown,
   markdownToHtml,
   renderBody,

package/dist/routes/index.d.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 import { Ampless } from '../index.js';
 import 'ampless';
 import 'next';
+import 'react';
 import 'aws-amplify/storage/server';
 import 'next/headers';

package/package.json CHANGED Viewed

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