@ampless/runtime 1.0.0-alpha.21 → 1.0.0-alpha.23

package/dist/chunk-5BLMLMZU.js

@@ -0,0 +1,123 @@
+// src/stream-s3.ts
+import { getProperties } from "aws-amplify/storage/server";
+import { cookies } from "next/headers";
+var DEFAULT_THRESHOLD_BYTES = 6 * 1024 * 1024;
+var META_CACHE_MAX = 1e3;
+var META_CACHE_TTL_MS = 5 * 6e4;
+var META_CACHE = /* @__PURE__ */ new Map();
+function metaCacheGet(key) {
+  const hit = META_CACHE.get(key);
+  if (!hit) return void 0;
+  if (hit.expires < Date.now()) {
+    META_CACHE.delete(key);
+    return void 0;
+  }
+  META_CACHE.delete(key);
+  META_CACHE.set(key, hit);
+  return hit.meta;
+}
+function metaCacheSet(key, meta) {
+  if (META_CACHE.size >= META_CACHE_MAX) {
+    const oldest = META_CACHE.keys().next().value;
+    if (oldest !== void 0) META_CACHE.delete(oldest);
+  }
+  META_CACHE.set(key, { meta, expires: Date.now() + META_CACHE_TTL_MS });
+}
+function _resetStreamS3Cache() {
+  META_CACHE.clear();
+}
+async function headViaAmplify(ctx, key) {
+  try {
+    const props = await getProperties(ctx, { path: key });
+    const size = typeof props.size === "number" ? props.size : 0;
+    const mimeType = props.contentType ?? "application/octet-stream";
+    const etag = props.eTag;
+    return { size, mimeType, etag };
+  } catch (err) {
+    console.error(`[stream-s3] getProperties failed for ${key}:`, err);
+    return null;
+  }
+}
+async function streamS3Object(amplifyServerContext, key, options) {
+  const threshold = options.thresholdBytes ?? DEFAULT_THRESHOLD_BYTES;
+  let meta = options.meta ?? null;
+  if (!meta) {
+    const cached = metaCacheGet(key);
+    if (cached) {
+      meta = cached;
+    } else if (options.headFallback) {
+      try {
+        meta = await options.headFallback();
+      } catch (err) {
+        console.error(`[stream-s3] headFallback threw for ${key}:`, err);
+        meta = null;
+      }
+      if (meta) metaCacheSet(key, meta);
+    }
+  }
+  if (!meta) {
+    const probed = await headViaAmplify(amplifyServerContext, key);
+    if (probed) {
+      metaCacheSet(key, probed);
+      meta = probed;
+    }
+  }
+  if (!meta) {
+    return new Response("Not Found", { status: 404 });
+  }
+  if (meta.size > threshold) {
+    const url = await options.presignedUrlFor(key).catch((err) => {
+      console.error(`[stream-s3] presign failed for ${key}:`, err);
+      return null;
+    });
+    if (!url) return new Response("Not Found", { status: 404 });
+    const headers2 = new Headers({ Location: url });
+    if (options.cacheControl) headers2.set("Cache-Control", options.cacheControl);
+    return new Response(null, { status: 302, headers: headers2 });
+  }
+  const presigned = await options.presignedUrlFor(key).catch((err) => {
+    console.error(`[stream-s3] presign failed for ${key}:`, err);
+    return null;
+  });
+  if (!presigned) return new Response("Not Found", { status: 404 });
+  let upstream;
+  try {
+    upstream = await fetch(presigned);
+  } catch (err) {
+    console.error(`[stream-s3] upstream fetch failed for ${key}:`, err);
+    return new Response("Bad Gateway", { status: 502 });
+  }
+  if (upstream.status === 404 || upstream.status === 403) {
+    return new Response("Not Found", { status: 404 });
+  }
+  if (!upstream.ok || !upstream.body) {
+    console.error(
+      `[stream-s3] upstream returned ${upstream.status} for ${key}`
+    );
+    return new Response("Bad Gateway", { status: 502 });
+  }
+  const headers = new Headers();
+  headers.set("Content-Type", meta.mimeType);
+  const contentLength = upstream.headers.get("Content-Length");
+  if (contentLength) {
+    headers.set("Content-Length", contentLength);
+  } else {
+    headers.set("Content-Length", String(meta.size));
+  }
+  const upstreamEtag = upstream.headers.get("ETag") ?? meta.etag;
+  if (upstreamEtag) headers.set("ETag", upstreamEtag);
+  if (options.cacheControl) headers.set("Cache-Control", options.cacheControl);
+  return new Response(upstream.body, { status: 200, headers });
+}
+async function streamS3ObjectWithRunner(runWithAmplifyServerContext, key, options) {
+  return runWithAmplifyServerContext({
+    nextServerContext: { cookies },
+    operation: (ctx) => streamS3Object(ctx, key, options)
+  });
+}
+
+export {
+  _resetStreamS3Cache,
+  streamS3Object,
+  streamS3ObjectWithRunner
+};

package/dist/dispatchers/index.d.ts

@@ -2,6 +2,8 @@ import { ReactNode } from 'react';
 import { Metadata } from 'next';
 import { Ampless } from '../index.js';
 import 'ampless';
+import 'aws-amplify/storage/server';
+import 'next/headers';
 
 interface Props$2 {
     params: Promise<Record<string, never>>;

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-import { Post, 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';
 
 interface StorageOutput {
     bucket_name: string;
@@ -68,6 +71,30 @@ interface PostsApi {
     listPostsByTag(tag: string, opts?: ListPostsByTagOptions): Promise<ListPostsResult>;
 }
 
+/** Public projection returned by the `getMediaBySrc` custom query. */
+interface PublicMediaShape {
+    src: string;
+    size?: number | null;
+    mimeType?: string | null;
+    metadata?: unknown;
+}
+/** Decoded form handed to callers. */
+interface ResolvedMedia {
+    src: string;
+    size: number | null;
+    mimeType: string | null;
+    metadata: MediaMetadata | null;
+}
+interface MediaApi {
+    /**
+     * Resolve the Media DynamoDB row for the given S3 key. Returns
+     * `null` when no row matches (orphan / legacy asset) or when the
+     * AppSync call fails — the caller should treat both the same and
+     * fall back to a HEAD lookup. Failures are logged.
+     */
+    getMediaBySrc(src: string): Promise<ResolvedMedia | null>;
+}
+
 interface EffectiveSiteSettings {
     site: {
         name: string;
@@ -96,6 +123,20 @@ interface SeoApi {
     siteMetadata(): Promise<Metadata>;
 }
 
+interface PluginHeadApi {
+    /** React children safe to drop into `<head>`. */
+    renderHead(): ReactNode;
+    /** React children safe to drop just before `</body>`. */
+    renderBodyEnd(): 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.
+ */
+declare function createPluginHead(cmsConfig: Config): PluginHeadApi;
+
 interface ThemesRegistry {
     /** Map of theme name → loaded theme module. */
     themes: Record<string, ThemeModule>;
@@ -214,6 +255,75 @@ declare function tiptapToMarkdown(doc: unknown): string;
  */
 declare function htmlToMarkdown(html: string): string;
 
+type AmplifyServerContext = Parameters<typeof getProperties>[0];
+/** Metadata sufficient to choose between stream-back and 302 fallback. */
+interface ResolvedAssetMeta {
+    size: number;
+    mimeType: string;
+    /** S3 ETag (when known). Passed through to the response so clients can revalidate. */
+    etag?: string;
+}
+interface StreamS3Options {
+    /**
+     * Override the Cache-Control header on the streamed response.
+     * Leave undefined to let the route's middleware overlay
+     * (`computeCacheControl`) decide — that's the right answer for
+     * static-post asset bytes, since the strategy lives on
+     * `post.metadata.cache`. Media uploads pass an immutable header
+     * because their S3 keys carry a timestamp prefix.
+     */
+    cacheControl?: string;
+    /** Default 6 MiB — matches Amplify SSR Lambda's buffered response cap. */
+    thresholdBytes?: number;
+    /**
+     * Caller-supplied metadata (from DynamoDB). Preferred path: when
+     * present, no HEAD round-trip is issued.
+     */
+    meta?: ResolvedAssetMeta;
+    /**
+     * Caller-provided HEAD substitute. Invoked only when `meta` is
+     * omitted; result is memoised in the in-process LRU so repeat
+     * misses don't all hit S3.
+     */
+    headFallback?: () => Promise<ResolvedAssetMeta | null>;
+    /**
+     * Required for the 302 fallback path (files larger than the
+     * threshold, or stream-fetch errors). Returns a presigned URL or
+     * null when the object cannot be signed.
+     */
+    presignedUrlFor: (key: string) => Promise<string | null>;
+}
+/**
+ * Exported for tests. Production callers should never need to
+ * touch the module-scope cache directly.
+ */
+declare function _resetStreamS3Cache(): void;
+/**
+ * Stream the S3 object at `key` back through the Lambda response.
+ * Returns a `Response` whose body is the object bytes (for small
+ * files) or a 302 redirect to a presigned URL (for files larger
+ * than `thresholdBytes`). Missing objects → 404.
+ *
+ * The Amplify server context is required so the helper can mint a
+ * presigned URL through the same auth context the caller already
+ * uses (Cognito identity / public role). No extra IAM grant is
+ * needed on the Lambda execution role.
+ */
+declare function streamS3Object(amplifyServerContext: AmplifyServerContext, key: string, options: StreamS3Options): Promise<Response>;
+/**
+ * Convenience wrapper that pulls in the standard Amplify SSR cookie
+ * adapter so route handlers don't have to duplicate the
+ * `runWithAmplifyServerContext` plumbing. Pass the runner from
+ * `createServerRunner({ config: outputs })` and the rest is the same
+ * shape as `streamS3Object`.
+ */
+declare function streamS3ObjectWithRunner(runWithAmplifyServerContext: <T>(args: {
+    nextServerContext: {
+        cookies: typeof cookies;
+    };
+    operation: (ctx: AmplifyServerContext) => Promise<T>;
+}) => Promise<T>, key: string, options: StreamS3Options): Promise<Response>;
+
 interface CreateAmplessOpts {
     outputs: AmplessOutputs;
     cmsConfig: Config;
@@ -223,6 +333,12 @@ interface Ampless {
     listPublishedPosts(opts?: ListPostsOptions): Promise<ListPostsResult>;
     getPublishedPost(slug: string): Promise<Post | null>;
     listPostsByTag(tag: string, opts?: ListPostsByTagOptions): Promise<ListPostsResult>;
+    /**
+     * Look up the Media DynamoDB row by S3 key. Returns `null` for
+     * orphan / legacy assets (which the media-proxy route falls back
+     * to a HEAD lookup for). Failures are logged and surface as null.
+     */
+    getMediaBySrc(src: string): Promise<ResolvedMedia | null>;
     loadSiteSettings(): Promise<EffectiveSiteSettings>;
     resolveActiveTheme(): Promise<ResolvedTheme>;
     /**
@@ -235,6 +351,8 @@ interface Ampless {
     loadThemeConfig(): Promise<EffectiveThemeConfig>;
     postMetadata(post: Post): Promise<Metadata>;
     siteMetadata(): Promise<Metadata>;
+    publicHead(): ReactNode;
+    publicBodyEnd(): ReactNode;
     renderBody(post: Post): string;
     renderThemeCss(cssVars: Record<string, string>): string;
     publicAssetUrl(key: string): string;
@@ -243,11 +361,13 @@ interface Ampless {
     readonly cmsConfig: Config;
     readonly themes: ThemesRegistry;
     readonly posts: PostsApi;
+    readonly media: MediaApi;
     readonly settings: SiteSettingsApi;
     readonly seo: SeoApi;
     readonly themeActive: ThemeActiveApi;
     readonly themeConfig: ThemeConfigApi;
     readonly storageApi: StorageApi;
+    readonly pluginHead: PluginHeadApi;
 }
 /**
  * Wire up the ampless runtime from user-supplied config blobs. The
@@ -258,4 +378,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 PostsApi, type PublicPostConnectionShape, type PublicPostShape, type ResolvedTheme, type SeoApi, type SiteSettingsApi, type StorageOutput, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, createAmpless, htmlToMarkdown, markdownToHtml, renderBody, renderThemeCss, 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 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, htmlToMarkdown, markdownToHtml, renderBody, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };

package/dist/index.js

@@ -1,3 +1,9 @@
+import {
+  _resetStreamS3Cache,
+  streamS3Object,
+  streamS3ObjectWithRunner
+} from "./chunk-5BLMLMZU.js";
+
 // src/storage.ts
 import { formatPublicAssetUrl } from "ampless";
 function createStorage(outputs) {
@@ -81,6 +87,50 @@ function createPostsApi(outputs) {
   };
 }
 
+// src/media.ts
+import { cookies as cookies2 } from "next/headers";
+import { generateServerClientUsingCookies as generateServerClientUsingCookies2 } from "@aws-amplify/adapter-nextjs/api";
+import { decodeAwsJson as decodeAwsJson2 } from "ampless";
+function decodeMediaMetadata(value) {
+  if (value === null || value === void 0) return null;
+  const parsed = decodeAwsJson2(value);
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    return parsed;
+  }
+  return null;
+}
+function createMediaApi(outputs) {
+  const client = generateServerClientUsingCookies2({
+    config: outputs,
+    cookies: cookies2,
+    authMode: "apiKey"
+  });
+  return {
+    async getMediaBySrc(src) {
+      try {
+        const { data, errors } = await client.queries.getMediaBySrc({ src });
+        if (errors && errors.length > 0) {
+          console.error(
+            `[media-api] getMediaBySrc errors for ${src}`,
+            errors.map((e) => e.message)
+          );
+          return null;
+        }
+        if (!data) return null;
+        return {
+          src: data.src,
+          size: data.size ?? null,
+          mimeType: data.mimeType ?? null,
+          metadata: decodeMediaMetadata(data.metadata)
+        };
+      } catch (err) {
+        console.error(`[media-api] getMediaBySrc threw for ${src}`, err);
+        return null;
+      }
+    }
+  };
+}
+
 // src/site-settings.ts
 import { unflattenSettings } from "ampless";
 function createSiteSettings(cmsConfig, storage) {
@@ -175,6 +225,280 @@ function createSeo(cmsConfig, settingsApi) {
   };
 }
 
+// src/plugin-head.ts
+import {
+  Fragment,
+  createElement
+} from "react";
+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 collectFor(plugins, ctx, surface, renderOne) {
+  const entries = [];
+  for (const plugin of plugins) {
+    const factory = surface(plugin);
+    if (!factory) continue;
+    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) {
+  const plugins = (cmsConfig.plugins ?? []).filter(isPlugin2);
+  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 (seenNamespaces.has(ns)) {
+      warn(
+        `duplicate plugin namespace "${ns}" detected in cms.config.plugins. Set distinct \`instanceId\` on each instance to disambiguate.`
+      );
+    }
+    seenNamespaces.add(ns);
+    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 {
+    renderHead() {
+      return collectFor(
+        plugins,
+        { site: cmsConfig.site },
+        (p) => p.publicHead,
+        renderHeadDescriptor
+      );
+    },
+    renderBodyEnd() {
+      return collectFor(
+        plugins,
+        { site: cmsConfig.site },
+        (p) => p.publicBodyEnd,
+        renderBodyDescriptor
+      );
+    }
+  };
+}
+
 // src/theme-active.ts
 import { headers } from "next/headers";
 function createThemeActive(registry, storage) {
@@ -604,20 +928,25 @@ function createAmpless(opts) {
   const { outputs, cmsConfig, themes } = opts;
   const storage = createStorage(outputs);
   const posts = createPostsApi(outputs);
+  const media = createMediaApi(outputs);
   const settings = createSiteSettings(cmsConfig, storage);
   const seo = createSeo(cmsConfig, settings);
+  const pluginHead = createPluginHead(cmsConfig);
   const themeActive = createThemeActive(themes, storage);
   const themeConfig = createThemeConfig(themeActive, storage);
   return {
     listPublishedPosts: (o) => posts.listPublishedPosts(o),
     getPublishedPost: (slug) => posts.getPublishedPost(slug),
     listPostsByTag: (tag, o) => posts.listPostsByTag(tag, o),
+    getMediaBySrc: (src) => media.getMediaBySrc(src),
     loadSiteSettings: () => settings.loadSiteSettings(),
     resolveActiveTheme: () => themeActive.resolveActiveTheme(),
     readStoredActiveThemeFresh: () => themeActive.readStoredActiveThemeFresh(),
     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),
@@ -626,21 +955,27 @@ function createAmpless(opts) {
     cmsConfig,
     themes,
     posts,
+    media,
     settings,
     seo,
     themeActive,
     themeConfig,
-    storageApi: storage
+    storageApi: storage,
+    pluginHead
   };
 }
 export {
   COLOR_SCHEME_SETTING_KEY,
   DEFAULT_COLOR_SCHEME,
+  _resetStreamS3Cache,
   createAmpless,
+  createPluginHead,
   htmlToMarkdown,
   markdownToHtml,
   renderBody,
   renderThemeCss,
+  streamS3Object,
+  streamS3ObjectWithRunner,
   tiptapToHtml,
   tiptapToMarkdown,
   validateColorScheme

package/dist/routes/index.d.ts

@@ -1,6 +1,9 @@
 import { Ampless } from '../index.js';
 import 'ampless';
 import 'next';
+import 'react';
+import 'aws-amplify/storage/server';
+import 'next/headers';
 
 interface Ctx$4 {
     params: Promise<{
@@ -84,15 +87,13 @@ type StaticRouteHandler = (req: Request, ctx: Ctx) => Promise<Response>;
  * the bundle resolve correctly — `<img src="img.png">` must resolve
  * to `/<slug>/img.png`, not the site root.
  *
- * Trust model: assets are served via short-lived S3 presigned URLs;
- * the bucket stays private.
+ * Trust model: the bucket stays private. Small files (<=6 MB) are
+ * streamed back through the Lambda response so CloudFront caches
+ * them; larger files fall back to a short-lived S3 presigned redirect.
  *
  * Cache-Control: deliberately omitted from the responses here.
  * Middleware computes the strategy from `metadata.cache` +
- * `post.updatedAt` and sets it on the rewritten response. The 302
- * presigned redirects also rely on S3's own headers for the actual
- * asset bytes — adding a stale-while-revalidate window on the 302
- * would risk serving an expired presign to repeat visitors.
+ * `post.updatedAt` and overlays it on the rewritten response.
  */
 declare function createStaticRouteHandler(ampless: Ampless): StaticRouteHandler;
 

package/dist/routes/index.js

@@ -1,3 +1,7 @@
+import {
+  streamS3Object
+} from "../chunk-5BLMLMZU.js";
+
 // src/routes/og.ts
 import { ImageResponse } from "next/og";
 import { loadImageForOg } from "@ampless/plugin-og-image/load-image";
@@ -104,6 +108,8 @@ function createStaticRouteHandler(ampless) {
     if (post.format !== "static") {
       return new Response("Not Found", { status: 404 });
     }
+    const metadata = post.metadata;
+    const filesMeta = metadata && typeof metadata.files === "object" && metadata.files !== null ? metadata.files : void 0;
     if (restSegments.length === 0) {
       const url = new URL(request.url);
       if (!url.pathname.endsWith("/")) {
@@ -113,15 +119,12 @@ function createStaticRouteHandler(ampless) {
       }
       const body2 = post.body ?? null;
       const entrypoint = typeof body2?.entrypoint === "string" && body2.entrypoint ? body2.entrypoint : "index.html";
-      const presignedUrl2 = await signStaticAsset({
+      return serveStaticAsset({
         runWithAmplifyServerContext,
         slug,
-        rest: entrypoint
+        rest: entrypoint,
+        filesMeta
       });
-      if (!presignedUrl2) {
-        return new Response("Not Found", { status: 404 });
-      }
-      return Response.redirect(presignedUrl2, 302);
     }
     if (restSegments.some(
       (s) => !s || s === "." || s === ".." || s.includes("/") || s.includes("\\") || s.includes("\0")
@@ -134,39 +137,49 @@ function createStaticRouteHandler(ampless) {
     if (fileList.length > 0 && !fileList.includes(rest)) {
       return new Response("Not Found", { status: 404 });
     }
-    const presignedUrl = await signStaticAsset({
+    return serveStaticAsset({
       runWithAmplifyServerContext,
       slug,
-      rest
+      rest,
+      filesMeta
     });
-    if (!presignedUrl) {
-      return new Response("Not Found", { status: 404 });
-    }
-    return Response.redirect(presignedUrl, 302);
   };
 }
-async function signStaticAsset({
+async function serveStaticAsset({
   runWithAmplifyServerContext,
   slug,
-  rest
+  rest,
+  filesMeta
+}) {
+  const key = `public/static/${slug}/${rest}`;
+  const persisted = filesMeta?.[rest];
+  const meta = persisted ? { size: persisted.size, mimeType: persisted.mimeType } : void 0;
+  const opts = {
+    meta,
+    presignedUrlFor: (k) => signStaticAsset({ runWithAmplifyServerContext, key: k })
+  };
+  return runWithAmplifyServerContext({
+    nextServerContext: { cookies },
+    operation: (ctx) => streamS3Object(ctx, key, opts)
+  });
+}
+async function signStaticAsset({
+  runWithAmplifyServerContext,
+  key
 }) {
-  const objectPath = `public/static/${slug}/${rest}`;
   try {
     return await runWithAmplifyServerContext({
       nextServerContext: { cookies },
       operation: async (amplifyContext) => {
         const result = await getUrl(amplifyContext, {
-          path: objectPath,
+          path: key,
           options: { expiresIn: 60 * 60 }
         });
         return result.url.toString();
       }
     });
   } catch (err) {
-    console.error(
-      `[static-route] presign failed for ${objectPath}:`,
-      err
-    );
+    console.error(`[static-route] presign failed for ${key}:`, err);
     return null;
   }
 }

package/package.json

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