@ampless/runtime 1.0.0-beta.67 → 1.0.0-beta.69

package/README.ja.md

@@ -92,6 +92,9 @@ middleware はリクエストごとに AppSync から `post.format` /
   `app/raw/[slug]/route.ts` で配信
 - `format: 'static'` → `/static/<slug>(/<path>)`、
   `app/static/[slug]/[[...path]]/route.ts` で配信
+- `/<slug>.md`（フォーマット不問） → `/md/<slug>`、
+  `app/md/[slug]/route.ts` で配信 — `ampless.postToMarkdown()` による
+  Markdown 投影。`cms.config.ai.markdownRoutes: false` で無効化できます。
 
 また、`post.metadata.cache`（auto / deep / hot）+ `post.updatedAt` +
 `cms.config.cache.{cooldownMs, freshTtlSeconds, deepTtlSeconds}` から
@@ -102,7 +105,7 @@ middleware はリクエストごとに AppSync から `post.format` /
 
 - `@ampless/runtime` — `createAmpless`、ランタイム型、`renderBody`・`renderThemeCss`・フォーマットコンバーターの再エクスポート
 - `@ampless/runtime/middleware` — `createAmplessMiddleware`、`defaultMatcherConfig`
-- `@ampless/runtime/routes` — `createOgRouteHandler`、`createSitemapRouteHandler`、`createFeedRouteHandler`、`createRawRouteHandler`、`createStaticRouteHandler`
+- `@ampless/runtime/routes` — `createOgRouteHandler`、`createSitemapRouteHandler`、`createFeedRouteHandler`、`createRawRouteHandler`、`createStaticRouteHandler`、`createMarkdownRouteHandler`
 - `@ampless/runtime/dispatchers` — `createThemeHomeDispatcher`、`createThemePostDispatcher`、`createThemeTagDispatcher`（それぞれ対応する `*Metadata` ファクトリーあり）
 
 ## テンプレートに残るもの

package/README.md

@@ -92,6 +92,9 @@ rewrites the request to the right internal handler:
   `app/raw/[slug]/route.ts`
 - `format: 'static'` → `/static/<slug>(/<path>)`, served by
   `app/static/[slug]/[[...path]]/route.ts`
+- `/<slug>.md` (any format) → `/md/<slug>`, served by
+  `app/md/[slug]/route.ts` — Markdown projection via
+  `ampless.postToMarkdown()`. Disable with `cms.config.ai.markdownRoutes: false`.
 
 It also computes `Cache-Control` from `post.metadata.cache` (auto /
 deep / hot) + `post.updatedAt` + `cms.config.cache.{cooldownMs,
@@ -102,7 +105,7 @@ See `docs/CONTENT.md` for the cache strategy contract.
 
 - `@ampless/runtime` — `createAmpless`, runtime types, and re-exports of `renderBody`, `renderThemeCss`, format converters
 - `@ampless/runtime/middleware` — `createAmplessMiddleware`, `defaultMatcherConfig`
-- `@ampless/runtime/routes` — `createOgRouteHandler`, `createSitemapRouteHandler`, `createFeedRouteHandler`, `createRawRouteHandler`, `createStaticRouteHandler`
+- `@ampless/runtime/routes` — `createOgRouteHandler`, `createSitemapRouteHandler`, `createFeedRouteHandler`, `createRawRouteHandler`, `createStaticRouteHandler`, `createMarkdownRouteHandler`
 - `@ampless/runtime/dispatchers` — `createThemeHomeDispatcher`, `createThemePostDispatcher`, `createThemeTagDispatcher` (each with a matching `*Metadata` factory)
 
 ## What's still in the template

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Post, MediaMetadata, AmplessPlugin, ContentFieldRenderer, PluginPublicRenderContext, TiptapNodeHtmlAdapters, TiptapNodeMarkdownAdapters, Config, ThemeModule, ThemeManifest, PluginPackageManifest } from 'ampless';
+import { Post, MediaMetadata, AmplessPlugin, ContentFieldRenderer, TiptapNodeMarkdownAdapters, PluginPublicRenderContext, TiptapNodeHtmlAdapters, Config, ThemeModule, ThemeManifest, PluginPackageManifest } from 'ampless';
 export { Config, Post, ThemeManifest } from 'ampless';
 import { Metadata } from 'next';
 import { ReactNode } from 'react';
@@ -188,6 +188,21 @@ interface ContentFieldRegistry {
  * render that happens to walk the conflicting node.
  */
 declare function buildContentFieldRegistry(plugins: readonly AmplessPlugin[]): ContentFieldRegistry;
+/**
+ * Merge every plugin's server-safe `tiptapNodeToMarkdown` map into a
+ * single `TiptapNodeMarkdownAdapters` registry. Eagerly errors on
+ * duplicate `nodeType` registration across plugins (two different
+ * functions) so the misuse surfaces at config time, not at the first
+ * markdown conversion that happens to walk the conflicting node. The
+ * exact same function registered twice (e.g. one shared adapter map
+ * reused by two plugin instances) is tolerated.
+ *
+ * Non-function entries are skipped with a warning rather than thrown:
+ * `definePlugin` already warns about them at definition time, and one
+ * broken plugin shouldn't take the whole site's markdown output down
+ * (a nodeType conflict, by contrast, is a config error — that throws).
+ */
+declare function buildMarkdownAdapterRegistry(plugins: readonly AmplessPlugin[]): TiptapNodeMarkdownAdapters;
 interface RenderBodyOptions {
     contentFields?: ContentFieldRegistry;
     /**
@@ -280,6 +295,54 @@ declare function tiptapToMarkdown(doc: unknown, opts?: {
  * relied on.
  */
 declare function htmlToMarkdown(html: string): string;
+interface PostToMarkdownOptions {
+    /**
+     * Per-nodeType tiptap→markdown serialisers (plugin embed nodes →
+     * bare URL lines). `createAmpless` injects
+     * `pluginHead.markdownAdapters`; a raw direct caller can omit this
+     * to fall back to the built-in switch (unknown atom nodes then emit
+     * unsupported-node placeholder comments).
+     */
+    nodeAdapters?: TiptapNodeMarkdownAdapters;
+    /** Prepend YAML frontmatter (default: true). */
+    frontmatter?: boolean;
+    /**
+     * Absolute site origin used to build the frontmatter's `canonical`
+     * line (`<siteUrl>/<slug>`). Omitted → no canonical line.
+     */
+    siteUrl?: string;
+}
+/**
+ * Convert a public post into its canonical Markdown representation:
+ * YAML frontmatter + format-dependent body. This is the single
+ * conversion point for every AI-readable surface (the `/<slug>.md`
+ * route, llms-full, public MCP `get_post`) — new surfaces should call
+ * this rather than reimplementing the format branches.
+ *
+ * Frontmatter carries **public fields only** (title / slug /
+ * publishedAt / updatedAt / tags / excerpt / canonical) — never
+ * postId, status, or metadata. Values are encoded with
+ * `JSON.stringify`: a JSON string is a valid YAML double-quoted
+ * scalar and a JSON array is a valid YAML flow sequence, so quoting /
+ * escaping is correct without a YAML library.
+ *
+ * Body quality varies by format:
+ *   - `markdown`: the stored source, verbatim.
+ *   - `tiptap`: `tiptapToMarkdown` with `opts.nodeAdapters` (plugin
+ *     embeds become bare URL lines; unknown atom nodes emit an
+ *     `ampless:unsupported-node` placeholder comment).
+ *   - `html`: `htmlToMarkdown` — regex-based and approximate; complex
+ *     markup may not fully survive (see htmlToMarkdown's limits).
+ *   - `static`: no body conversion (the bundle bytes live in S3) — a
+ *     markdown link to the served entrypoint, plus the excerpt when
+ *     present.
+ *
+ * Pure, synchronous, and node-safe — same tier as `tiptapToMarkdown` /
+ * `htmlToMarkdown`. Themes / routes should usually call it through
+ * `ampless.postToMarkdown(post)`, which injects the plugin adapter
+ * registry and the effective site URL.
+ */
+declare function postToMarkdown(post: Post, opts?: PostToMarkdownOptions): string;
 
 interface PluginHeadApi {
     /**
@@ -328,6 +391,15 @@ interface PluginHeadApi {
      * `contentFields`.
      */
     readonly contentFieldsRegistry: ContentFieldRegistry;
+    /**
+     * Merged tiptap→markdown adapter registry across all valid plugins
+     * (server-safe `tiptapNodeToMarkdown` manifests). Built once at
+     * `createPluginHead` construction time so duplicate `nodeType`
+     * registrations across plugins throw eagerly (config error).
+     * Threaded into `rendering.ts:postToMarkdown()` via
+     * `Ampless.postToMarkdown`.
+     */
+    readonly markdownAdapters: TiptapNodeMarkdownAdapters;
     /**
      * Resolve the per-plugin `PluginPublicRenderContext` snapshot used by
      * `contentFields` renderers. Same `settings()` binding the public
@@ -652,6 +724,22 @@ interface Ampless {
      * complete HTML documents that don't expand embed shortcuts.
      */
     renderBodyHtmlString(post: Post): string;
+    /**
+     * Convert a post into its canonical Markdown representation (YAML
+     * frontmatter + body). This is the **single conversion point** for
+     * every AI-readable surface — the `/<slug>.md` route, llms-full, and
+     * the public MCP `get_post` all go through here rather than
+     * reimplementing the format branches. Plugin embed nodes are
+     * serialised via `pluginHead.markdownAdapters` (bare URL lines);
+     * `format: 'html'` bodies go through the regex-based `htmlToMarkdown`
+     * and are approximate. Async because the frontmatter's `canonical`
+     * line needs the effective `site.url` from the S3 site-settings
+     * cache; with `frontmatter: false` that read is skipped entirely and
+     * only the body is returned.
+     */
+    postToMarkdown(post: Post, opts?: {
+        frontmatter?: boolean;
+    }): Promise<string>;
     renderThemeCss(cssVars: Record<string, string>): string;
     publicAssetUrl(key: string): string;
     isStorageConfigured(): boolean;
@@ -677,4 +765,4 @@ interface Ampless {
  */
 declare function createAmpless(opts: CreateAmplessOpts): Ampless;
 
-export { type Ampless, type AmplessOutputs, COLOR_SCHEME_SETTING_KEY, type ColorScheme, type ContentFieldRegistry, 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 RenderBodyOptions, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, SUPPORTED_API_VERSION, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, buildContentFieldRegistry, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, loadPackageManifest, markdownToHtml, renderBody, renderBodyHtmlString, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };
+export { type Ampless, type AmplessOutputs, COLOR_SCHEME_SETTING_KEY, type ColorScheme, type ContentFieldRegistry, 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 PostToMarkdownOptions, type PostsApi, type PublicHtmlForPostResult, type PublicMediaShape, type PublicPostConnectionShape, type PublicPostShape, type RenderBodyOptions, type ResolvedAssetMeta, type ResolvedMedia, type ResolvedTheme, SUPPORTED_API_VERSION, type SeoApi, type SiteSettingsApi, type StorageOutput, type StreamS3Options, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, _resetStreamS3Cache, buildContentFieldRegistry, buildMarkdownAdapterRegistry, createAmpless, createPluginHead, createPluginSettings, escapeJsonLdInlineBody, htmlToMarkdown, loadPackageManifest, markdownToHtml, postToMarkdown, renderBody, renderBodyHtmlString, renderThemeCss, streamS3Object, streamS3ObjectWithRunner, tiptapToHtml, tiptapToMarkdown, validateColorScheme };

package/dist/index.js

@@ -399,6 +399,29 @@ function buildContentFieldRegistry(plugins) {
   }
   return { tiptap, markdownUrl, htmlPlaceholder };
 }
+function buildMarkdownAdapterRegistry(plugins) {
+  const merged = {};
+  for (const plugin of plugins) {
+    const adapters = plugin.tiptapNodeToMarkdown;
+    if (!adapters) continue;
+    for (const [nodeType, adapter] of Object.entries(adapters)) {
+      if (typeof adapter !== "function") {
+        console.warn(
+          `[ampless markdownAdapters] plugin "${plugin.instanceId ?? plugin.name}" declares a non-function tiptapNodeToMarkdown entry for nodeType "${nodeType}". Skipping the entry.`
+        );
+        continue;
+      }
+      const existing = merged[nodeType];
+      if (existing && existing !== adapter) {
+        throw new Error(
+          `[ampless markdownAdapters] duplicate tiptap nodeType "${nodeType}" \u2014 already registered by another plugin. Each nodeType may be claimed by at most one plugin.`
+        );
+      }
+      merged[nodeType] = adapter;
+    }
+  }
+  return merged;
+}
 function htmlPassthrough(html) {
   return createElement("span", { dangerouslySetInnerHTML: { __html: html } });
 }
@@ -776,9 +799,19 @@ function tiptapNodeToMarkdown(node, opts) {
 `;
     }
     default:
-      return children;
+      if (children) return children;
+      console.warn(
+        `[ampless] tiptapToMarkdown: no adapter for node type "${String(node.type)}" \u2014 emitting placeholder`
+      );
+      return `
+<!-- ampless:unsupported-node type="${sanitizeNodeTypeForComment(node.type)}" -->
+
+`;
   }
 }
+function sanitizeNodeTypeForComment(type) {
+  return String(type).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+}
 function tiptapTableToMarkdown(node, opts) {
   const rows = node.content ?? [];
   if (rows.length === 0) return "";
@@ -902,6 +935,62 @@ function convertHtmlTaskList(items) {
   }
   return out.join("\n");
 }
+function postToMarkdown(post, opts = {}) {
+  const frontmatter = opts.frontmatter !== false ? postFrontmatter(post, opts.siteUrl) : "";
+  return frontmatter + postBodyToMarkdown(post, opts);
+}
+function postFrontmatter(post, siteUrl) {
+  const lines = [];
+  lines.push(`title: ${JSON.stringify(post.title)}`);
+  lines.push(`slug: ${JSON.stringify(post.slug)}`);
+  if (post.publishedAt) lines.push(`publishedAt: ${JSON.stringify(post.publishedAt)}`);
+  if (post.updatedAt) lines.push(`updatedAt: ${JSON.stringify(post.updatedAt)}`);
+  if (post.tags && post.tags.length > 0) lines.push(`tags: ${JSON.stringify(post.tags)}`);
+  if (post.excerpt) lines.push(`excerpt: ${JSON.stringify(post.excerpt)}`);
+  if (siteUrl) {
+    const origin = siteUrl.replace(/\/+$/, "");
+    lines.push(`canonical: ${JSON.stringify(`${origin}/${post.slug}`)}`);
+  }
+  return `---
+${lines.join("\n")}
+---
+
+`;
+}
+function postBodyToMarkdown(post, opts) {
+  switch (post.format) {
+    case "markdown":
+      return typeof post.body === "string" ? post.body : String(post.body ?? "");
+    case "tiptap":
+      return tiptapToMarkdown(post.body, { nodeAdapters: opts.nodeAdapters });
+    case "html":
+      return htmlToMarkdown(String(post.body));
+    case "static": {
+      const link = `[${staticEntrypoint(post.body)}](/${post.slug}/)`;
+      return post.excerpt ? `${link}
+
+${post.excerpt}
+` : `${link}
+`;
+    }
+    default:
+      return "";
+  }
+}
+function staticEntrypoint(body) {
+  let manifest = body;
+  if (typeof manifest === "string") {
+    try {
+      manifest = JSON.parse(manifest);
+    } catch {
+      return "index.html";
+    }
+  }
+  if (typeof manifest === "object" && manifest !== null && typeof manifest.entrypoint === "string" && manifest.entrypoint.length > 0) {
+    return manifest.entrypoint;
+  }
+  return "index.html";
+}
 
 // src/plugin-package-manifest.ts
 var TRUST_LEVELS = ["untrusted", "trusted", "privileged"];
@@ -1520,6 +1609,7 @@ function createPluginHead(cmsConfig, pluginSettings) {
     }
   }
   const contentFieldsRegistry = buildContentFieldRegistry(validPlugins);
+  const markdownAdapters = buildMarkdownAdapterRegistry(validPlugins);
   for (const plugin of validPlugins) {
     const caps = plugin.capabilities;
     if (!caps) continue;
@@ -1581,6 +1671,7 @@ function createPluginHead(cmsConfig, pluginSettings) {
       return collectPostScriptsForPage(validPlugins, cmsConfig.site, snapshot, posts);
     },
     contentFieldsRegistry,
+    markdownAdapters,
     async contextForPlugins() {
       const snapshot = await pluginSettings.loadAll();
       return (plugin) => makeCtx(plugin, cmsConfig.site, snapshot);
@@ -1847,6 +1938,19 @@ function createAmpless(opts) {
       });
     },
     renderBodyHtmlString: (post) => renderBodyHtmlString(post),
+    postToMarkdown: async (post, o) => {
+      if (o?.frontmatter === false) {
+        return postToMarkdown(post, {
+          nodeAdapters: pluginHead.markdownAdapters,
+          frontmatter: false
+        });
+      }
+      const { site } = await settings.loadSiteSettings();
+      return postToMarkdown(post, {
+        nodeAdapters: pluginHead.markdownAdapters,
+        siteUrl: site.url || void 0
+      });
+    },
     renderThemeCss: (cssVars) => renderThemeCss(cssVars),
     publicAssetUrl: (key) => storage.publicAssetUrl(key),
     isStorageConfigured: () => storage.isStorageConfigured(),
@@ -1870,6 +1974,7 @@ export {
   SUPPORTED_API_VERSION,
   _resetStreamS3Cache,
   buildContentFieldRegistry,
+  buildMarkdownAdapterRegistry,
   createAmpless,
   createPluginHead,
   createPluginSettings,
@@ -1877,6 +1982,7 @@ export {
   htmlToMarkdown,
   loadPackageManifest,
   markdownToHtml,
+  postToMarkdown,
   renderBody,
   renderBodyHtmlString,
   renderThemeCss,

package/dist/middleware.d.ts

@@ -32,6 +32,8 @@ declare function computeCacheControl(flags: {
  *  - Rewrite to `/static/<slug>(/<path>)` when the post is a static
  *    bundle (`format='static'`). Themed posts (default) get no
  *    rewrite — `app/[slug]/page.tsx` serves them directly.
+ *  - Rewrite `/<slug>.md` → `/md/<slug>` (any format) unless
+ *    `cms.config.ai.markdownRoutes` is explicitly `false`.
  *  - `Cache-Control` header computed from `post.metadata.cache` +
  *    `post.updatedAt` + `cms.config.cache.*` and set on the response.
  *  - `?previewTheme` / `?previewColorScheme` → `x-preview-theme` /

package/dist/middleware.js

@@ -135,7 +135,8 @@ var RESERVED_PREFIXES = /* @__PURE__ */ new Set([
   "tag",
   // internal rewrite targets — direct hits should not be middleware-driven
   "raw",
-  "static"
+  "static",
+  "md"
 ]);
 function createAmplessMiddleware(opts) {
   return async function middleware(request) {
@@ -160,9 +161,11 @@ function createAmplessMiddleware(opts) {
       return passthrough();
     }
     const restPath = segments.slice(1);
-    const flags = await getCachedFlags(opts, slug);
+    const isMdRequest = restPath.length === 0 && slug.endsWith(".md") && slug.length > 3 && opts.cmsConfig.ai?.markdownRoutes !== false;
+    const lookupSlug = isMdRequest ? slug.slice(0, -3) : slug;
+    const flags = await getCachedFlags(opts, lookupSlug);
     if (!flags) {
-      if (restPath.length > 0) {
+      if (restPath.length > 0 || isMdRequest) {
         return new NextResponse("Not Found", { status: 404 });
       }
       return passthrough();
@@ -170,7 +173,12 @@ function createAmplessMiddleware(opts) {
     const cacheControl = computeCacheControl(flags, opts.cmsConfig);
     let response;
     if (restPath.length === 0) {
-      if (flags.format === "html" && flags.metadata?.no_layout === true) {
+      if (isMdRequest) {
+        url.pathname = `/md/${lookupSlug}`;
+        response = NextResponse.rewrite(url, {
+          request: { headers: requestHeaders }
+        });
+      } else if (flags.format === "html" && flags.metadata?.no_layout === true) {
         url.pathname = `/raw/${slug}`;
         response = NextResponse.rewrite(url, {
           request: { headers: requestHeaders }

package/dist/routes/index.d.ts

@@ -5,18 +5,18 @@ import 'react';
 import 'aws-amplify/storage/server';
 import 'next/headers';
 
-interface Ctx$4 {
+interface Ctx$5 {
     params: Promise<{
         slug: string;
     }>;
 }
-type OgRouteHandler = (req: Request, ctx: Ctx$4) => Promise<Response>;
+type OgRouteHandler = (req: Request, ctx: Ctx$5) => Promise<Response>;
 declare function createOgRouteHandler(ampless: Ampless): OgRouteHandler;
 
-interface Ctx$3 {
+interface Ctx$4 {
     params: Promise<Record<string, never>>;
 }
-type SitemapRouteHandler = (req: Request, ctx: Ctx$3) => Promise<Response>;
+type SitemapRouteHandler = (req: Request, ctx: Ctx$4) => Promise<Response>;
 /**
  * Sitemap route delegate. Looks up the active theme and forwards to
  * whichever `routes.sitemap` handler the theme provides. Themes
@@ -24,10 +24,10 @@ type SitemapRouteHandler = (req: Request, ctx: Ctx$3) => Promise<Response>;
  */
 declare function createSitemapRouteHandler(ampless: Ampless): SitemapRouteHandler;
 
-interface Ctx$2 {
+interface Ctx$3 {
     params: Promise<Record<string, never>>;
 }
-type FeedRouteHandler = (req: Request, ctx: Ctx$2) => Promise<Response>;
+type FeedRouteHandler = (req: Request, ctx: Ctx$3) => Promise<Response>;
 /**
  * Feed route delegate. Looks up the active theme and forwards to
  * whichever `routes.feed` handler the theme provides. Themes without
@@ -35,12 +35,12 @@ type FeedRouteHandler = (req: Request, ctx: Ctx$2) => Promise<Response>;
  */
 declare function createFeedRouteHandler(ampless: Ampless): FeedRouteHandler;
 
-interface Ctx$1 {
+interface Ctx$2 {
     params: Promise<{
         slug: string;
     }>;
 }
-type RawRouteHandler = (req: Request, ctx: Ctx$1) => Promise<Response>;
+type RawRouteHandler = (req: Request, ctx: Ctx$2) => Promise<Response>;
 /**
  * Internal route handler for `format: 'html'` posts whose
  * `metadata.no_layout === true` — the body is its own complete HTML
@@ -63,13 +63,13 @@ type RawRouteHandler = (req: Request, ctx: Ctx$1) => Promise<Response>;
  */
 declare function createRawRouteHandler(ampless: Ampless): RawRouteHandler;
 
-interface Ctx {
+interface Ctx$1 {
     params: Promise<{
         slug: string;
         path?: string[];
     }>;
 }
-type StaticRouteHandler = (req: Request, ctx: Ctx) => Promise<Response>;
+type StaticRouteHandler = (req: Request, ctx: Ctx$1) => Promise<Response>;
 /**
  * Internal route handler for `format: 'static'` posts — the body is a
  * manifest describing a bundle of files in S3 at
@@ -97,4 +97,26 @@ type StaticRouteHandler = (req: Request, ctx: Ctx) => Promise<Response>;
  */
 declare function createStaticRouteHandler(ampless: Ampless): StaticRouteHandler;
 
-export { type FeedRouteHandler, type OgRouteHandler, type RawRouteHandler, type SitemapRouteHandler, type StaticRouteHandler, createFeedRouteHandler, createOgRouteHandler, createRawRouteHandler, createSitemapRouteHandler, createStaticRouteHandler };
+interface Ctx {
+    params: Promise<{
+        slug: string;
+    }>;
+}
+type MarkdownRouteHandler = (req: Request, ctx: Ctx) => Promise<Response>;
+/**
+ * Route handler serving the per-post Markdown projection
+ * (`ampless.postToMarkdown()`) for published posts of any format.
+ *
+ * Mounted at `app/md/[slug]/route.ts`; reached via middleware rewrite
+ * of `/<slug>.md` → `/md/<slug>` internally — the public/canonical URL
+ * is `/<slug>.md`. Middleware adds `md` to its reserved-prefix list so
+ * a user post with slug `md` passes through to a 404 rather than
+ * reaching this handler with the wrong content.
+ *
+ * Cache-Control: deliberately omitted from the response. Middleware
+ * computes the strategy from `post.metadata.cache` + `post.updatedAt`
+ * and sets the header on the rewritten response.
+ */
+declare function createMarkdownRouteHandler(ampless: Ampless): MarkdownRouteHandler;
+
+export { type FeedRouteHandler, type MarkdownRouteHandler, type OgRouteHandler, type RawRouteHandler, type SitemapRouteHandler, type StaticRouteHandler, createFeedRouteHandler, createMarkdownRouteHandler, createOgRouteHandler, createRawRouteHandler, createSitemapRouteHandler, createStaticRouteHandler };

package/dist/routes/index.js

@@ -184,8 +184,31 @@ async function signStaticAsset({
     return null;
   }
 }
+
+// src/routes/md.ts
+function createMarkdownRouteHandler(ampless) {
+  return async function GET(_request, { params }) {
+    const { slug } = await params;
+    const cleanSlug = slug.replace(/\.md$/, "");
+    if (ampless.cmsConfig.ai?.markdownRoutes === false) {
+      return new Response("Not Found", { status: 404 });
+    }
+    const post = await ampless.getPublishedPost(cleanSlug);
+    if (!post) {
+      return new Response("Not Found", { status: 404 });
+    }
+    return new Response(await ampless.postToMarkdown(post), {
+      status: 200,
+      headers: {
+        "Content-Type": "text/markdown; charset=utf-8"
+        // Cache-Control set by middleware.
+      }
+    });
+  };
+}
 export {
   createFeedRouteHandler,
+  createMarkdownRouteHandler,
   createOgRouteHandler,
   createRawRouteHandler,
   createSitemapRouteHandler,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/runtime",
-  "version": "1.0.0-beta.67",
+  "version": "1.0.0-beta.69",
   "description": "Public-side runtime for ampless: post fetching, theme dispatch, middleware, public route handlers",
   "license": "MIT",
   "type": "module",
@@ -51,8 +51,8 @@
     "marked": "^18.0.4",
     "sanitize-html": "^2.17.4",
     "tailwind-merge": "^3.6.0",
-    "@ampless/plugin-og-image": "0.2.0-beta.55",
-    "ampless": "1.0.0-beta.55"
+    "@ampless/plugin-og-image": "0.2.0-beta.56",
+    "ampless": "1.0.0-beta.56"
   },
   "peerDependencies": {
     "@aws-amplify/adapter-nextjs": "^1",