@ampless/runtime 1.0.0-alpha.50 → 1.0.0-alpha.52

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Post, MediaMetadata, Config, ThemeModule, ThemeManifest, PluginPackageManifest } from 'ampless';
+import { Post, MediaMetadata, AmplessPlugin, ContentFieldRenderer, PluginPublicRenderContext, Config, ThemeModule, ThemeManifest, PluginPackageManifest } from 'ampless';
 export { Config, Post, ThemeManifest } from 'ampless';
 import { Metadata } from 'next';
 import { ReactNode } from 'react';
@@ -142,6 +142,112 @@ interface PluginSettingsApi {
 }
 declare function createPluginSettings(storage: StorageApi): PluginSettingsApi;
 
+/**
+ * Registry of `contentFields` renderers, plus a per-plugin context
+ * resolver. Built once per request from `cms.config.plugins` by
+ * `createPluginHead.contentFieldsRegistry` and threaded through every
+ * `renderBody(post, { contentFields, ctxForPlugin })` call.
+ *
+ * The map values capture the original plugin so the runtime can rebind
+ * `this` and resolve the right `PluginPublicRenderContext` for each
+ * renderer at call time.
+ */
+interface ContentFieldRegistry {
+    tiptap: ReadonlyMap<string, {
+        plugin: AmplessPlugin;
+        renderer: Extract<ContentFieldRenderer, {
+            kind: 'tiptap';
+        }>;
+    }>;
+    markdownUrl: ReadonlyArray<{
+        plugin: AmplessPlugin;
+        renderer: Extract<ContentFieldRenderer, {
+            kind: 'markdown-url';
+        }>;
+    }>;
+}
+/**
+ * Build a `ContentFieldRegistry` from a list of plugins. Eagerly errors
+ * on duplicate `nodeType` / `pattern.source` registration across
+ * plugins so the misuse surfaces at config time, not at the first
+ * render that happens to walk the conflicting node.
+ */
+declare function buildContentFieldRegistry(plugins: readonly AmplessPlugin[]): ContentFieldRegistry;
+interface RenderBodyOptions {
+    contentFields?: ContentFieldRegistry;
+    /**
+     * Resolver invoked with the matched plugin to obtain the
+     * `PluginPublicRenderContext` for the renderer call. Wired by
+     * `createAmpless` so plugin renderers see the same `setting()`-bound
+     * ctx as `publicHead` / `publicBodyEnd`.
+     */
+    ctxForPlugin?: (plugin: AmplessPlugin) => PluginPublicRenderContext;
+}
+/**
+ * Async + ReactNode-shaped post body renderer. The runtime threads its
+ * `contentFields` registry + per-plugin ctx resolver in via `opts`; a
+ * raw direct caller (tests etc.) can omit `opts` to fall back to the
+ * default embed-free behaviour.
+ *
+ * Themes should call this through `ampless.renderBody(post)` (which
+ * supplies both opts) rather than calling this low-level function
+ * directly.
+ */
+declare function renderBody(post: Post, opts?: RenderBodyOptions): ReactNode;
+/**
+ * Sync string-shaped renderer used by `routes/raw.ts` and by format
+ * converters that need a `string` output. Skips the `contentFields`
+ * registry entirely — the raw route serves `format: 'html'` posts
+ * directly, and the format converters operate on tiptap / markdown
+ * source that doesn't expand embed shortcuts.
+ */
+declare function renderBodyHtmlString(post: Post): string;
+/**
+ * Convert a tiptap doc to its HTML form. Same renderer the public
+ * site uses. Defensive: tiptap accepts an HTML string as initial
+ * content and parses it on mount, but won't fire onUpdate until the
+ * user edits, so a format-switch chain (e.g. markdown -> tiptap ->
+ * markdown without editing) can still hand us a raw HTML string
+ * here. In that case, return it as-is rather than walking it as a
+ * malformed tiptap node and producing empty output.
+ */
+declare function tiptapToHtml(doc: unknown): string;
+/** Convert markdown to HTML using marked + GFM. */
+declare function markdownToHtml(md: string): string;
+/**
+ * Walk a tiptap doc and emit Markdown. Mirrors `renderTiptapString` in
+ * shape but produces markdown syntax. Loses anything markdown can't
+ * express (data attributes, image display modes, custom marks).
+ *
+ * Notes on info loss:
+ * - underline / highlight are not in GFM, so they fall back to the
+ *   literal `<u>` / `<mark>` HTML tags (preserved as-is across round trips).
+ * - paragraph / heading textAlign cannot be expressed in markdown and
+ *   is therefore lost on conversion.
+ *
+ * Same defensive path as tiptapToHtml: a string input means tiptap
+ * hasn't emitted JSON yet (the body is still the HTML we handed it).
+ * Route through htmlToMarkdown so the content survives.
+ */
+declare function tiptapToMarkdown(doc: unknown): string;
+/**
+ * Regex-based HTML -> Markdown converter. Handles the tag set the
+ * editor produces (`<p>` `<h1>`-`<h6>` `<strong>` `<em>` `<a>`
+ * `<img>` `<ul>` `<ol>` `<li>` `<code>` `<pre>` `<blockquote>` `<hr>`
+ * `<br>` `<u>` `<mark>` `<table>` task-list `<ul data-type="taskList">`).
+ * Decorative containers like `<div style="text-align:...">` are dropped.
+ *
+ * Tables are reduced to GFM pipe syntax via convertHtmlTable. Complex
+ * nested content inside cells (lists, other tables) is flattened to
+ * plain text.
+ *
+ * Not a full library, there are known limits like nested formatting
+ * inside list items potentially merging. Acceptable for a v0.x
+ * format-switch convenience; complex HTML round-trips shouldn't be
+ * relied on.
+ */
+declare function htmlToMarkdown(html: string): string;
+
 interface PluginHeadApi {
     /**
      * React children safe to drop into `<head>`. Async because admin-
@@ -170,6 +276,33 @@ interface PluginHeadApi {
      * templates. Themes never call `dangerouslySetInnerHTML` themselves.
      */
     renderHtmlForPost(post: Post): Promise<PublicHtmlForPostResult>;
+    /**
+     * Page-level scripts aggregated across all installed plugins'
+     * `publicPostScript(post, ctx)` (Phase 7 `publicPostScript`
+     * capability). Themes invoke this via
+     * `ampless.publicPostScriptsForPage(posts)` after rendering post
+     * body / featured body. Descriptors are deduped by stable `id` so a
+     * widget script (e.g. x.com `widgets.js`) emits at most once per
+     * page regardless of how many embeds appear.
+     */
+    renderPostScriptsForPage(posts: readonly Post[]): Promise<ReactNode>;
+    /**
+     * In-body content renderer registry (Phase 7 `contentFields`
+     * capability). Built once at `createPluginHead` construction time so
+     * duplicate `nodeType` / `pattern.source` registrations throw eagerly
+     * (config error). Threaded into `rendering.ts:renderBody()` via
+     * `Ampless.renderBody`. Returns `null` when no plugin registered any
+     * `contentFields`.
+     */
+    readonly contentFieldsRegistry: ContentFieldRegistry;
+    /**
+     * Resolve the per-plugin `PluginPublicRenderContext` snapshot used by
+     * `contentFields` renderers. Same `settings()` binding the public
+     * surfaces (`publicHead` / `publicBodyEnd`) use. Async because it
+     * reads the S3 site-settings cache once per request via
+     * `pluginSettings.loadAll()`.
+     */
+    contextForPlugins(): Promise<(plugin: AmplessPlugin) => PluginPublicRenderContext>;
 }
 /**
  * Position-bucketed result of `renderHtmlForPost`. Themes embed these
@@ -325,53 +458,6 @@ declare function loadPackageManifest(packageName: string): PluginPackageManifest
  */
 declare const SUPPORTED_API_VERSION: 1;
 
-declare function renderBody(post: Post): string;
-/**
- * Convert a tiptap doc to its HTML form. Same renderer the public
- * site uses. Defensive: tiptap accepts an HTML string as initial
- * content and parses it on mount, but won't fire onUpdate until the
- * user edits, so a format-switch chain (e.g. markdown -> tiptap ->
- * markdown without editing) can still hand us a raw HTML string
- * here. In that case, return it as-is rather than walking it as a
- * malformed tiptap node and producing empty output.
- */
-declare function tiptapToHtml(doc: unknown): string;
-/** Convert markdown to HTML using marked + GFM. */
-declare function markdownToHtml(md: string): string;
-/**
- * Walk a tiptap doc and emit Markdown. Mirrors `renderTiptap` in
- * shape but produces markdown syntax. Loses anything markdown can't
- * express (data attributes, image display modes, custom marks).
- *
- * Notes on info loss:
- * - underline / highlight are not in GFM, so they fall back to the
- *   literal `<u>` / `<mark>` HTML tags (preserved as-is across round trips).
- * - paragraph / heading textAlign cannot be expressed in markdown and
- *   is therefore lost on conversion.
- *
- * Same defensive path as tiptapToHtml: a string input means tiptap
- * hasn't emitted JSON yet (the body is still the HTML we handed it).
- * Route through htmlToMarkdown so the content survives.
- */
-declare function tiptapToMarkdown(doc: unknown): string;
-/**
- * Regex-based HTML -> Markdown converter. Handles the tag set the
- * editor produces (`<p>` `<h1>`-`<h6>` `<strong>` `<em>` `<a>`
- * `<img>` `<ul>` `<ol>` `<li>` `<code>` `<pre>` `<blockquote>` `<hr>`
- * `<br>` `<u>` `<mark>` `<table>` task-list `<ul data-type="taskList">`).
- * Decorative containers like `<div style="text-align:...">` are dropped.
- *
- * Tables are reduced to GFM pipe syntax via convertHtmlTable. Complex
- * nested content inside cells (lists, other tables) is flattened to
- * plain text.
- *
- * Not a full library, there are known limits like nested formatting
- * inside list items potentially merging. Acceptable for a v0.x
- * format-switch convenience; complex HTML round-trips shouldn't be
- * relied on.
- */
-declare function htmlToMarkdown(html: string): string;
-
 type AmplifyServerContext = Parameters<typeof getProperties>[0];
 /** Metadata sufficient to choose between stream-back and 302 fallback. */
 interface ResolvedAssetMeta {
@@ -490,7 +576,40 @@ interface Ampless {
      * `dangerouslySetInnerHTML` themselves.
      */
     publicHtmlForPost(post: Post): Promise<PublicHtmlForPostResult>;
-    renderBody(post: Post): string;
+    /**
+     * Page-level scripts aggregated across all installed plugins'
+     * `publicPostScript(post, ctx)` (Phase 7 `publicPostScript`
+     * capability). Themes render this in the post / home layout
+     * (typically just after the post body) so widgets like x.com's
+     * `widgets.js` load once per page even when several embedded posts
+     * appear. Descriptors are deduped by stable `id` so multiple posts
+     * needing the same script collapse into a single tag.
+     */
+    publicPostScriptsForPage(posts: readonly Post[]): Promise<ReactNode>;
+    /**
+     * Render a post body into a `ReactNode`. Async because admin-managed
+     * `settings.public` values feed into `contentFields` renderers via
+     * the same S3 site-settings cache the public head/body surfaces use;
+     * fetched once per request (Next.js fetch dedup on the
+     * `site-settings` cache tag). Themes call this directly in their
+     * post / home layouts:
+     *
+     *     <div>{await ampless.renderBody(post)}</div>
+     *
+     * Phase 7 alpha breaking: this signature replaced the prior sync
+     * `string` return shape. The sync string flavour is still available
+     * via `renderBodyHtmlString` for routes (raw HTML response) that
+     * cannot await — but those callsites bypass the `contentFields`
+     * registry on purpose.
+     */
+    renderBody(post: Post): Promise<ReactNode>;
+    /**
+     * Sync string-shaped renderer used by the raw route handler. Skips
+     * the `contentFields` registry — the raw route serves
+     * `format: 'html', metadata.no_layout: true` posts whose bodies are
+     * complete HTML documents that don't expand embed shortcuts.
+     */
+    renderBodyHtmlString(post: Post): string;
     renderThemeCss(cssVars: Record<string, string>): string;
     publicAssetUrl(key: string): string;
     isStorageConfigured(): boolean;
@@ -516,4 +635,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 PublicHtmlForPostResult, 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 };
+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 };