@inneropen/marvin-astro 1.1.1 → 1.2.1

package/README.md

@@ -3,13 +3,15 @@
 Site integration for [Marvin CMS](https://github.com/inneropen) on Astro: content repositories
 with static fallbacks, site chrome from collections, and payload normalization.
 
-Three packages, three concerns:
+Two packages, two concerns:
 
 | Package | Concern |
 |---|---|
 | `@inneropen/marvin-sdk` | transport — HTTP client, entries, collections, assets |
-| `@inneropen/marvin-renderers-core` | entry-type → Astro renderer component mapping |
-| **`@inneropen/marvin-astro`** | **site integration — repositories, chrome, normalization** |
+| **`@inneropen/marvin-astro`** | **site integration — repositories, chrome, normalization, and the Astro components (forms, media embeds, entry-type renderers)** |
+
+`@inneropen/marvin-renderers-core` has been folded in here — see
+[Migrating from @inneropen/marvin-renderers-core](#migrating-from-inneropenmarvin-renderers-core).
 
 A new site wires up to a Marvin workspace by installing one package, setting three env vars, and
 writing only its own transform functions.
@@ -78,12 +80,16 @@ page — and only fetches the entry directly when nothing is loaded yet or the s
 
 ## Why `hydrate`
 
-The collection endpoint returns `PublishedEntryListItem`, which carries core fields and
-`metadata_json` but **not** `data_json`. The single-entry endpoint returns `PublishedEntryRead`,
-which includes it.
+The collection endpoint returns `PublishedEntryListItem`: core fields, `metadata_json` and (on
+current servers) `data`, but only the *slugs* of its assets and resources — no `assets[]`
+placements (so no roles, no `hero-grade` image) and no `resources[]`. The single-entry endpoint
+returns `PublishedEntryRead`, which has all of it.
 
-So if a transform reads any schema-defined field — anything beyond title/slug/summary/metadata —
-`hydrate: true` is required or those fields come back `undefined`. It costs one request per entry.
+So if a transform reads asset roles, resources, or (on an older server, whose list items lack
+`data`) any schema field, `hydrate: true` is required. It costs one request per entry. Items are
+re-read unless they're already full entries (`isFullEntry`: `assets[]`/`resources[]` present, no
+`assetSlugs`) — carrying `data` isn't enough. `bySlug()` serves a detail page from the loaded list
+only when that item came from a full entry; otherwise it fetches the entry.
 
 Those requests run at most `hydrateConcurrency` at a time (default 6) rather than all at once, and
 a read that fails is retried with backoff (3 attempts) before the entry is dropped, so a single
@@ -104,7 +110,8 @@ fall-through a legacy value that *is* set would never surface.
 | `f.string(key)` `f.number(key)` `f.bool(key)` `f.list(key)` | scalars; `bool` reads `"true"`/`"1"`/`"yes"` |
 | `f.oneOf(key, allowed, fallback)` | enum guard — replaces per-field `normalizeStatus`-style helpers |
 | `f.raw(key)` `f.data()` `f.metadata()` | untyped escape hatches |
-| `f.markdown(key?, { softBreaks })` | renders to HTML; `undefined` when there is nothing to render |
+| `f.markdown(key?, { softBreaks, embeds })` | renders to HTML, with [media embeds](#media-embeds); `undefined` when there is nothing to render |
+| `f.embed(key)` | the resolved embed for an `embed` field — render with `<Embed>` |
 | `f.date(key)` `f.publishedAt()` | display date ("Mon DD, YYYY") / raw ISO stamp |
 | `f.image(options)` `f.images(options)` `f.icon(options)` | resolved `{src, alt, focalPoint}` |
 | `f.asset(options)` `f.assetByRole(...roles)` `f.assets()` | raw asset placements |
@@ -143,6 +150,153 @@ The default prefixes the entry's own non-navigation collection: an entry in `wor
 becomes `/workshop-reference/<slug>`, an entry in no other collection becomes `/<slug>`. Override
 when routes don't mirror collections.
 
+## Media embeds
+
+Paste a YouTube, Vimeo, Spotify, SoundCloud, Apple Music/Podcasts, Tidal or podcast link on its
+own line in a markdown field and Marvin resolves it on the server. The published entry then
+carries `embeds`, keyed by the URL exactly as written, each with Marvin-built `html` for the
+site's embed mode and the structured fields behind it. The stored markdown never changes, so a
+site that doesn't render embeds just shows the link.
+
+**Markdown.** `f.markdown()` passes the entry's embeds automatically. A paragraph that is exactly
+a URL with an `embeds` entry renders as that embed's `html`; `<url>`, `[text](url)`, a URL inside
+a sentence and anything in code stay as they are. Opt a field out with `f.markdown('body',
+{ embeds: false })`. Where you call the renderer yourself, pass the embeds:
+
+```ts
+import { entryEmbeds } from '@inneropen/marvin-astro';
+
+const bodyHtml = await marvin.renderMarkdown(body, { embeds: entryEmbeds(entry) });
+```
+
+**`embed` fields.** An `embed` field's value is the provider URL; `f.embed(key)` returns its
+resolved embed. Render it with `<Embed>`, which builds the player, facade or link card from the
+structured fields:
+
+```astro
+---
+import { Embed } from '@inneropen/marvin-astro/components';
+const site = await marvin.getSite();
+---
+<Embed
+  embed={post.video}
+  mode={site.embeds?.mode}
+  consentText={site.embeds?.consentText}
+  frameSources={site.embeds?.frameSources}
+/>
+```
+
+**The loader and CSS.** In `click_to_load` mode (Marvin's default) an embed is a facade — a
+button and a plain link — and nothing loads from the provider until the visitor clicks. Put
+`<EmbedLoader />` once in your layout:
+
+```astro
+---
+import { EmbedLoader } from '@inneropen/marvin-astro/components';
+---
+<body>
+  <slot />
+  <EmbedLoader />
+</body>
+```
+
+On click (or Enter/Space) it swaps the button for the iframe. It builds the iframe only from the
+facade's `data-marvin-embed-attrs`, keeps only `src`, `title`, `allow`, `sandbox`,
+`referrerpolicy`, `loading` and `style`, refuses any `src` that isn't https on a host in
+`data-marvin-embed-hosts`, and never parses HTML. It also brings the base `.marvin-embed` CSS:
+responsive aspect ratio for video, fixed height for audio, facade and link-card styles. The
+rules have zero specificity, so any site rule wins; theme through custom properties:
+
+```css
+.marvin-embed, .marvin-embed-link {
+  --marvin-embed-radius: 0;
+  --marvin-embed-bg: var(--ink);
+  --marvin-embed-fg: var(--paper);
+  --marvin-embed-max-width: 48rem;
+}
+```
+
+The full list (`--marvin-embed-aspect`, `-height`, `-margin`, `-muted`, `-border`, `-focus`, …)
+is at the top of `src/components/embeds.css`. For CSS without the loader (a `direct`-mode site),
+`import '@inneropen/marvin-astro/components/embeds.css'`.
+
+**CSP.** `site.embeds.frameSources` lists every origin the site's embeds may frame. Use it for a
+`frame-src` directive:
+
+```astro
+---
+const site = await marvin.getSite();
+const frameSrc = ["'self'", ...(site.embeds?.frameSources ?? [])].join(' ');
+---
+<meta http-equiv="Content-Security-Policy" content={`frame-src ${frameSrc}`} />
+```
+
+The loader script is small enough that Astro inlines it; if your CSP forbids inline scripts, hash
+it or set `vite.build.assetsInlineLimit: 0` so Astro emits it as a file.
+
+The embed types (`MarvinEmbed`, `MarvinSiteEmbeds`, …) are declared in this package, so none of
+this needs a newer SDK.
+
+## Components
+
+`@inneropen/marvin-astro/components` ships Astro source, compiled by your site's build.
+
+| Component | Use |
+|---|---|
+| `FormRenderer` | a public form from a submittable entry type's `formSchema`; unstyled, progressive-enhancement submit |
+| `Embed`, `LinkCard`, `EmbedLoader` | media embeds (above) |
+| `EntryRenderer` | picks the renderer for an entry from its entry type's `rendering` |
+| `PageRenderer`, `ArticleRenderer`, `FaqRenderer`, `NavigationRenderer` | unstyled, semantic core renderers with `data-renderer`/`data-role` hooks |
+
+Page and Article render the markdown body (with embeds); pass `renderMarkdown={marvin.renderMarkdown}`
+to use your site's markdown options.
+
+The registry and logic: `getRenderer`, `astroRegistry`, `coreRendererPackage` from
+`@inneropen/marvin-astro/components` (or `/components/registry`), and the framework-agnostic
+helpers — `resolveRendererName`, `resolveRendererConfig`, `extractBody`, `extractField`,
+`getFeaturedAsset`, `createRegistry`, `createPackageRegistry`, `createRendererPackage`,
+`validateRenderers`, … — from `@inneropen/marvin-astro/renderers`.
+
+Build-time check that every rendered entry type has a renderer:
+
+```js
+// astro.config.mjs
+import { marvinIntegration } from '@inneropen/marvin-astro/components/integration';
+import { astroRegistry } from '@inneropen/marvin-astro/components/registry';
+
+export default defineConfig({
+  integrations: [marvinIntegration({ registry: astroRegistry })],
+});
+```
+
+Options: `registry` (required), `apiUrl`, `siteToken` (default to the `MARVIN_*` env vars),
+`strict` (throw instead of warn), `ignore` (entry-type slugs to skip).
+
+Marvin's system entry types name their renderer package `@inneropen/marvin-renderers-core`; the
+core renderers still answer to that name (and to `@inneropen/marvin-astro`).
+
+## Migrating from @inneropen/marvin-renderers-core
+
+The components and logic moved here with their names unchanged. Swap the import paths, then
+remove `@inneropen/marvin-renderers-core` from `package.json`:
+
+| Before (`@inneropen/marvin-renderers-core…`) | After (`@inneropen/marvin-astro…`) |
+|---|---|
+| `/astro` | `/components` |
+| `/astro/registry` | `/components/registry` |
+| `/astro/integration` | `/components/integration` |
+| `/astro/renderers/PageRenderer.astro` (etc.) | `/components/renderers/PageRenderer.astro` |
+| `/logic` | `/renderers` |
+
+```diff
+-import { FormRenderer } from '@inneropen/marvin-renderers-core/astro';
++import { FormRenderer } from '@inneropen/marvin-astro/components';
+```
+
+Behaviour changes: Page/Article now render the body as markdown instead of injecting it raw, and
+`EntryRenderer` renders core entry types without a custom registry (it silently rendered only
+its slot before).
+
 ## The failure latch
 
 A static build asks for content once per path. When the backend is down that means N failed
@@ -162,8 +316,8 @@ marvin.backend.clearLatch();
 
 ## SEO head (optional)
 
-One component ships, behind its own export path, so the core package stays pure TypeScript and
-Astro stays an optional peer dependency.
+`SeoHead` ships behind its own export path (as do the [components](#components)), so the core
+package stays pure TypeScript and Astro stays an optional peer dependency.
 
 ```astro
 ---
@@ -187,18 +341,23 @@ verification tags. No styling, no site coupling.
 | `@inneropen/marvin-astro` | `createMarvinContent` and every helper below it |
 | `@inneropen/marvin-astro/types` | resolved types only (`ApiSite`, `ApiSeo`, `ApiSiteChrome`, …) |
 | `@inneropen/marvin-astro/astro` | `SeoHead` |
+| `@inneropen/marvin-astro/components` | `FormRenderer`, `Embed`, `LinkCard`, `EmbedLoader`, `EntryRenderer`, the core renderers, registry, `marvinIntegration` |
+| `@inneropen/marvin-astro/components/registry` | `getRenderer`, `astroRegistry`, `coreRendererPackage` |
+| `@inneropen/marvin-astro/components/integration` | `marvinIntegration` (for `astro.config.mjs`) |
+| `@inneropen/marvin-astro/components/*` | individual components, `renderers/*.astro`, `embeds.css` |
+| `@inneropen/marvin-astro/renderers` | renderer logic (compiled): resolve, registry, validation |
 
 Beyond `createMarvinContent`, the pieces are usable on their own: `createBackend`,
 `createFetcher`, `createRepository`, `createSiteLoader`, `createChromeLoader`,
-`createFieldAccessor`, `createMarkdownRenderer`, `formatDisplayDate`, `selectValuesForPage`, and
-the whole `normalize` surface.
+`createFieldAccessor`, `createMarkdownRenderer`, `entryEmbeds`, `findEmbed`, `siteEmbeds`,
+`formatDisplayDate`, `selectValuesForPage`, and the whole `normalize` surface.
 
 ## Development
 
 ```bash
 npm install
 npm run typecheck
-npm test          # vitest, fixture-driven, no network
+npm test          # vitest, fixture-driven, no network; .astro components via Astro's Container API
 npm run build     # tsup → dist/ with .d.ts
 ```
 

package/dist/embeds-BTNryQA6.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Media embeds: the published shapes Marvin hands a site, read tolerantly.
+ *
+ * Marvin resolves a pasted provider link (YouTube, Vimeo, Spotify, …) on the server and publishes
+ * the result next to the entry as `entry.embeds`, keyed by the URL exactly as the author wrote it.
+ * Stored markdown is never rewritten: a site that knows about embeds swaps the link for the
+ * player; an older site just shows the link.
+ *
+ * These types are declared here rather than imported from `@inneropen/marvin-sdk` so the package
+ * works with SDKs that predate embeds. Kind and status are open-ended so a newer server value
+ * doesn't break an older site's types.
+ */
+type MarvinEmbedKind = 'video' | 'audio' | 'podcast' | 'playlist';
+type MarvinEmbedStatus = 'ok' | 'link' | 'unavailable';
+type MarvinEmbedMode = 'direct' | 'click_to_load';
+/**
+ * A Marvin-built iframe. Every value comes from Marvin's provider registry. Exactly one of
+ * `aspectRatio` / `height` is set; the other is `null`.
+ */
+type MarvinEmbedIframe = {
+    src: string;
+    title: string;
+    allow?: string | null;
+    sandbox?: string | null;
+    referrerpolicy?: string | null;
+    /** CSS aspect ratio for video players, e.g. `"16/9"` (`"9/16"` for Shorts); `null` otherwise. */
+    aspectRatio?: string | null;
+    /** Fixed pixel height for audio / podcast / playlist players; `null` for video. */
+    height?: number | null;
+};
+/** The plain link every embed falls back to. */
+type MarvinEmbedLink = {
+    href: string;
+    title: string;
+    providerName: string;
+};
+/** Optional fields arrive as `null` rather than omitted; every reader here treats both alike. */
+type MarvinEmbed = {
+    /** The URL exactly as written in the content. */
+    url: string;
+    canonicalUrl?: string | null;
+    /** Provider key, e.g. `youtube`. */
+    provider: string;
+    /** Display name, e.g. `YouTube`. */
+    providerName: string;
+    kind: MarvinEmbedKind | (string & {});
+    /** `ok` has an iframe; `link` and `unavailable` render as a link card. */
+    status: MarvinEmbedStatus | (string & {});
+    title?: string | null;
+    authorName?: string | null;
+    thumbnailUrl?: string | null;
+    iframe?: MarvinEmbedIframe | null;
+    link: MarvinEmbedLink;
+    /** Marvin-built HTML for the site's embed mode (an iframe, a click-to-load facade, or a link). */
+    html: string;
+};
+/** `entry.embeds`: every resolved embed on the entry, keyed by the URL as written. */
+type MarvinEmbeds = Record<string, MarvinEmbed>;
+/**
+ * `site.embeds` (next to `site.seo`): the site's embed privacy mode, consent text (`{provider}`
+ * already substituted per embed in the published `html`) and the frame sources a CSP must allow.
+ */
+type MarvinSiteEmbeds = {
+    mode: MarvinEmbedMode;
+    consentText: string;
+    /** Origins/hosts the site's embeds may frame — feed these into a `frame-src` directive. */
+    frameSources: string[];
+};
+/**
+ * The entry's `embeds` map, or `undefined` when it has none (an older server, or no embeds).
+ * Values that aren't objects carrying a URL are dropped.
+ */
+declare function entryEmbeds(entry: unknown): MarvinEmbeds | undefined;
+/** The embed for `url` as written, tolerating surrounding whitespace. */
+declare function findEmbed(embeds: MarvinEmbeds | null | undefined, url: string | null | undefined): MarvinEmbed | undefined;
+/** Normalize `site.embeds`; `undefined` when the server doesn't send it. */
+declare function siteEmbeds(raw: unknown): MarvinSiteEmbeds | undefined;
+
+export { type MarvinEmbeds as M, type MarvinEmbed as a, type MarvinEmbedIframe as b, type MarvinEmbedKind as c, type MarvinEmbedLink as d, type MarvinEmbedMode as e, type MarvinEmbedStatus as f, type MarvinSiteEmbeds as g, entryEmbeds as h, findEmbed as i, siteEmbeds as s };

package/dist/index.d.ts

@@ -1,11 +1,21 @@
 import { MarkedOptions } from 'marked';
+import { M as MarvinEmbeds, a as MarvinEmbed } from './embeds-BTNryQA6.js';
+export { b as MarvinEmbedIframe, c as MarvinEmbedKind, d as MarvinEmbedLink, e as MarvinEmbedMode, f as MarvinEmbedStatus, g as MarvinSiteEmbeds, h as entryEmbeds, i as findEmbed, s as siteEmbeds } from './embeds-BTNryQA6.js';
 import { MarvinContentEntry, ApiSite, ApiSeo, ApiSiteChrome, ApiNavigationLink, ApiSocialLink, AssetSelectOptions, ApiImage, ApiResourceLink, SectionLanding } from './types.js';
 export { ApiActionVariant, ApiHero, ApiHeroAction, ApiPageAction } from './types.js';
 import * as _inneropen_marvin_sdk from '@inneropen/marvin-sdk';
 import { MarvinClient, MarvinEntry, Entry, PublishedCollectionSummary, Collection, CollectionEntry, MarvinSite, Workspace, MarvinAsset, MarvinResource } from '@inneropen/marvin-sdk';
 
 type MarkdownOptions = MarkedOptions;
-type MarkdownRenderer = (markdown: string | string[] | null | undefined) => Promise<string>;
+/** Per-call options for a {@link MarkdownRenderer}. */
+type RenderMarkdownOptions = {
+    /**
+     * The entry's `embeds` map. A paragraph that is exactly a URL with an entry here renders as
+     * that embed's Marvin-built HTML instead of a link.
+     */
+    embeds?: MarvinEmbeds | null;
+};
+type MarkdownRenderer = (markdown: string | string[] | null | undefined, options?: RenderMarkdownOptions) => Promise<string>;
 /**
  * A markdown renderer with its own `marked` instance — options are per-site, not global, so two
  * `createMarvinContent()` instances in one process can't clobber each other's settings.
@@ -13,6 +23,12 @@ type MarkdownRenderer = (markdown: string | string[] | null | undefined) => Prom
  * `breaks: false` is the default because CMS body copy is authored as prose: a soft-wrapped
  * paragraph should render as one paragraph. Where authored line breaks must survive (a landing
  * intro, an address block), pass `breaks: true` or pre-convert with a trailing double space.
+ *
+ * Pass the entry's `embeds` to turn a bare provider URL on its own line into its player:
+ *
+ * ```ts
+ * await renderMarkdown(body, { embeds: entryEmbeds(entry) });
+ * ```
  */
 declare function createMarkdownRenderer(options?: MarkdownOptions): MarkdownRenderer;
 /** Turn single newlines into hard breaks, leaving paragraph breaks alone. */
@@ -139,6 +155,15 @@ declare function createBackend(options?: MarvinAstroConfig): MarvinBackend;
 /** An entry that carries `data_json` — i.e. schema fields are readable. */
 type HydratedEntry = MarvinEntry | Entry;
 type MarvinFetcher = ReturnType<typeof createFetcher>;
+/**
+ * True for a full entry (`PublishedEntryRead`), false for a list item (`PublishedEntryListItem`).
+ *
+ * `data` doesn't tell them apart: list items carry it too now. What differs is attachments. A full
+ * read has `assets[]` and `resources[]` (placement objects, always present, possibly empty); a list
+ * item has only `assetSlugs` / `resourceSlugs` and a `featuredAsset`. The SDK's `Entry` wrapper
+ * only ever comes from the single-entry read.
+ */
+declare function isFullEntry(item: unknown): boolean;
 declare function createFetcher(backend: MarvinBackend): {
     backend: MarvinBackend;
     collections(): Promise<PublishedCollectionSummary[]>;
@@ -291,6 +316,11 @@ type IconFieldOptions = {
 type MarkdownFieldOptions = {
     /** Keep authored single newlines as hard breaks. Default `false`. */
     softBreaks?: boolean;
+    /**
+     * Render a bare provider URL on its own line as its player, using the entry's `embeds`.
+     * Default `true`; `false` keeps every URL a plain link.
+     */
+    embeds?: boolean;
 };
 type ResourceFieldOptions = {
     /** Keep only these resource types, e.g. `['material', 'construction']`. */
@@ -338,6 +368,12 @@ declare function createFieldAccessor(entry: MarvinContentEntry, context: FieldAc
      * caller can omit the property rather than emit an empty string.
      */
     markdown(key?: string, options?: MarkdownFieldOptions): Promise<string | undefined>;
+    /**
+     * The resolved embed for an `embed` field (its value is the provider URL), or `undefined`
+     * when the field is empty or the server hasn't resolved it. Render it with `<Embed>` from
+     * `@inneropen/marvin-astro/components`, or output `embed.html`.
+     */
+    embed(key: string): MarvinEmbed | undefined;
     /**
      * The entry's primary image. Checks, in order: a hand-authored `metadata_json.featuredImage`,
      * the exact `preferRoles`, a role/usage match over the entry's image assets, and finally the
@@ -389,10 +425,11 @@ type RepositoryOptions<T> = {
     /**
      * Fetch each list item as a full entry before transforming.
      *
-     * The collection endpoint returns `PublishedEntryListItem`, which omits `data_json`; the
-     * single-entry endpoint returns `PublishedEntryRead`, which includes it. So if the transform
-     * reads ANY schema-defined field — anything not title/slug/summary/metadata — this must be
-     * `true` or those fields come back `undefined`. It costs one request per entry.
+     * The collection endpoint returns `PublishedEntryListItem`, which has no `assets[]` or
+     * `resources[]` (only their slugs) and, on older servers, no `data_json`; the single-entry
+     * endpoint returns `PublishedEntryRead`, which has all of it. So if the transform reads asset
+     * roles, resources, or (on an older server) any schema field, this must be `true`. It costs one
+     * request per entry. `bySlug` always works from full entries either way.
      */
     hydrate?: boolean;
     /** Build the resolved item from an entry. May be async (e.g. to render markdown). */
@@ -585,4 +622,4 @@ declare function createMarvinContent(options?: MarvinContentOptions): {
     reset(): void;
 };
 
-export { ApiImage, ApiNavigationLink, ApiResourceLink, ApiSeo, ApiSite, ApiSiteChrome, ApiSocialLink, AssetSelectOptions, type ChromeLoader, type ChromeOptions, DEFAULT_DEV_RETRY_MS, DEFAULT_HYDRATE_CONCURRENCY, ENV_KEYS, type FieldAccessor, type HrefContext, type HydratedEntry, type IconFieldOptions, type ImageFieldOptions, type MarkdownFieldOptions, type MarkdownOptions, type MarkdownRenderer, type MarvinAstroConfig, type MarvinBackend, type MarvinContent, MarvinContentEntry, type MarvinContentOptions, type MarvinFetcher, type MarvinLogger, type NavigationContext, type NavigationLinkInput, type Repository, type RepositoryContext, type RepositoryOptions, type ResolveHref, type ResolvedConfig, type ResourceFieldOptions, SectionLanding, type SectionLandingOptions, type SiteLoader, type SiteOptions, type SocialLinkInput, asNumber, asRecord, asString, asStringArray, assetAlt, assetField, assetUrl, buildFallbackSite, buildSeo, collectionRole, collectionSlugs, createBackend, createChromeLoader, createFetcher, createFieldAccessor, createMarkdownRenderer, createMarvinContent, createRepository, createSiteLoader, defaultResolveHref, describeConfig, entryAssets, entryData, entryField, entryMetadata, entryResources, errorMessage, field, focalPoint, formatDisplayDate, isExternalHref, isNetworkFailure, loadSectionLanding, metadataLink, preserveSoftBreaks, readEnv, resolveConfig, resourceField, resourceRole, selectAssetByRole, selectEntryAsset, selectFeaturedAsset, selectIconAsset, selectImageAsset, selectValuesForPage, socialLinkFromKey, toNavigationLink };
+export { ApiImage, ApiNavigationLink, ApiResourceLink, ApiSeo, ApiSite, ApiSiteChrome, ApiSocialLink, AssetSelectOptions, type ChromeLoader, type ChromeOptions, DEFAULT_DEV_RETRY_MS, DEFAULT_HYDRATE_CONCURRENCY, ENV_KEYS, type FieldAccessor, type HrefContext, type HydratedEntry, type IconFieldOptions, type ImageFieldOptions, type MarkdownFieldOptions, type MarkdownOptions, type MarkdownRenderer, type MarvinAstroConfig, type MarvinBackend, type MarvinContent, MarvinContentEntry, type MarvinContentOptions, MarvinEmbed, MarvinEmbeds, type MarvinFetcher, type MarvinLogger, type NavigationContext, type NavigationLinkInput, type RenderMarkdownOptions, type Repository, type RepositoryContext, type RepositoryOptions, type ResolveHref, type ResolvedConfig, type ResourceFieldOptions, SectionLanding, type SectionLandingOptions, type SiteLoader, type SiteOptions, type SocialLinkInput, asNumber, asRecord, asString, asStringArray, assetAlt, assetField, assetUrl, buildFallbackSite, buildSeo, collectionRole, collectionSlugs, createBackend, createChromeLoader, createFetcher, createFieldAccessor, createMarkdownRenderer, createMarvinContent, createRepository, createSiteLoader, defaultResolveHref, describeConfig, entryAssets, entryData, entryField, entryMetadata, entryResources, errorMessage, field, focalPoint, formatDisplayDate, isExternalHref, isFullEntry, isNetworkFailure, loadSectionLanding, metadataLink, preserveSoftBreaks, readEnv, resolveConfig, resourceField, resourceRole, selectAssetByRole, selectEntryAsset, selectFeaturedAsset, selectIconAsset, selectImageAsset, selectValuesForPage, socialLinkFromKey, toNavigationLink };

package/dist/index.js

@@ -404,6 +404,13 @@ function createChromeLoader(fetcher, siteLoader, options = {}) {
 }
 
 // src/fetch.ts
+function isFullEntry(item) {
+  if (!item || typeof item !== "object") return false;
+  if (typeof item.field === "function") return true;
+  const raw = item;
+  if ("assetSlugs" in raw || "resourceSlugs" in raw) return false;
+  return Array.isArray(raw.assets) || Array.isArray(raw.resources);
+}
 var HYDRATE_ATTEMPTS = 3;
 var HYDRATE_BACKOFF_MS = 500;
 function sleep(ms) {
@@ -461,9 +468,7 @@ function createFetcher(backend) {
       entries,
       backend.config.hydrateConcurrency,
       async (item) => {
-        if (typeof item.field === "function" || "data" in item || "dataJson" in item) {
-          return item;
-        }
+        if (isFullEntry(item)) return item;
         return entryForHydration(item.slug ?? "");
       }
     );
@@ -527,13 +532,79 @@ function createFetcher(backend) {
 
 // src/markdown.ts
 import { Marked } from "marked";
+
+// src/embeds.ts
+var EMBED_MODES = /* @__PURE__ */ new Set(["direct", "click_to_load"]);
+function readEmbedsField(entry) {
+  if (!entry || typeof entry !== "object") return void 0;
+  const direct = entry.embeds;
+  if (direct !== void 0) return direct;
+  const toJSON = entry.toJSON;
+  if (typeof toJSON === "function") {
+    return asRecord(toJSON.call(entry)).embeds;
+  }
+  return void 0;
+}
+function entryEmbeds(entry) {
+  const raw = readEmbedsField(entry);
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const embeds = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      embeds[key] = value;
+    }
+  }
+  return Object.keys(embeds).length > 0 ? embeds : void 0;
+}
+function findEmbed(embeds, url) {
+  if (!embeds || !url) return void 0;
+  const key = url.trim();
+  if (!key) return void 0;
+  return Object.prototype.hasOwnProperty.call(embeds, key) ? embeds[key] : void 0;
+}
+function siteEmbeds(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const value = asRecord(raw);
+  const mode = asString(value.mode);
+  const frameSources = Array.isArray(value.frameSources) ? value.frameSources.filter(
+    (source) => typeof source === "string" && source.trim().length > 0
+  ) : [];
+  return {
+    // Unknown or missing mode → the privacy-preserving default.
+    mode: mode && EMBED_MODES.has(mode) ? mode : "click_to_load",
+    consentText: asString(value.consentText) ?? "",
+    frameSources
+  };
+}
+
+// src/markdown.ts
+var EMBEDS = /* @__PURE__ */ Symbol("marvin.embeds");
+var BARE_URL = /^https?:\/\/\S+$/i;
+function paragraphEmbedHtml(token, embeds) {
+  if (!embeds) return void 0;
+  const text = token.text.trim();
+  if (!BARE_URL.test(text)) return void 0;
+  const html = findEmbed(embeds, text)?.html;
+  return typeof html === "string" && html.trim() ? html : void 0;
+}
 function createMarkdownRenderer(options = {}) {
   const marked = new Marked();
   marked.setOptions({ gfm: true, breaks: false, ...options });
-  return async (markdown) => {
+  marked.use({
+    renderer: {
+      paragraph(token) {
+        const embeds = this.options[EMBEDS];
+        const html = paragraphEmbedHtml(token, embeds);
+        return html === void 0 ? false : `${html}
+`;
+      }
+    }
+  });
+  return async (markdown, renderOptions = {}) => {
     const source = Array.isArray(markdown) ? markdown.join("\n\n") : markdown ?? "";
     if (!source) return "";
-    return await marked.parse(source);
+    const parseOptions = { [EMBEDS]: renderOptions.embeds ?? null };
+    return await marked.parse(source, parseOptions);
   };
 }
 function preserveSoftBreaks(source) {
@@ -585,6 +656,7 @@ function selectValuesForPage(items, pageSlug, count = 4) {
 var DEFAULT_IMAGE_ROLES = ["hero", "featured", "card"];
 function createFieldAccessor(entry, context) {
   const title = asString(entry.title);
+  const embeds = entryEmbeds(entry);
   const accessor = {
     /** The entry itself, for anything the accessor doesn't cover. */
     entry,
@@ -647,7 +719,17 @@ function createFieldAccessor(entry, context) {
       const raw = field(entry, key) ?? entry.contentMarkdown;
       const source = Array.isArray(raw) ? raw.join("\n\n") : asString(raw);
       if (!source) return void 0;
-      return context.renderMarkdown(options.softBreaks ? preserveSoftBreaks(source) : source);
+      return context.renderMarkdown(options.softBreaks ? preserveSoftBreaks(source) : source, {
+        embeds: options.embeds === false ? void 0 : embeds
+      });
+    },
+    /**
+     * The resolved embed for an `embed` field (its value is the provider URL), or `undefined`
+     * when the field is empty or the server hasn't resolved it. Render it with `<Embed>` from
+     * `@inneropen/marvin-astro/components`, or output `embed.html`.
+     */
+    embed(key) {
+      return findEmbed(embeds, asString(field(entry, key)));
     },
     /**
      * The entry's primary image. Checks, in order: a hand-authored `metadata_json.featuredImage`,
@@ -776,6 +858,7 @@ function createRepository(context, options) {
   const collections = options.collections ?? (options.collection ? [options.collection] : []);
   const slugOf = options.slugOf ?? defaultSlugOf;
   const isFeatured = options.isFeatured ?? defaultIsFeatured;
+  let loadedPromise = null;
   let allPromise = null;
   const bySlugCache = /* @__PURE__ */ new Map();
   function arrange(items) {
@@ -792,7 +875,7 @@ function createRepository(context, options) {
     return Promise.resolve(options.transform(entry, fields));
   }
   async function useFallback() {
-    return arrange(await options.fallback?.() ?? []);
+    return { items: arrange(await options.fallback?.() ?? []), fromFullEntry: /* @__PURE__ */ new Set() };
   }
   async function load() {
     if (collections.length > 0 && fetcher.backend.hasBackend()) {
@@ -800,7 +883,12 @@ function createRepository(context, options) {
         const entries = options.hydrate ? await fetcher.hydratedCollectionEntriesFallback(collections) : await fetcher.collectionEntriesFallback(collections);
         if (entries.length > 0) {
           const items = await Promise.all(entries.map((entry) => transform(entry)));
-          return arrange(items);
+          const fromFullEntry = /* @__PURE__ */ new Set();
+          items.forEach((item, index) => {
+            const slug = slugOf(item);
+            if (slug !== void 0 && isFullEntry(entries[index])) fromFullEntry.add(slug);
+          });
+          return { items: arrange(items), fromFullEntry };
         }
       } catch (error) {
         fetcher.backend.remember(error);
@@ -815,9 +903,11 @@ function createRepository(context, options) {
     return items.find((item) => slugOf(item) === slug);
   }
   async function loadBySlug(slug) {
-    if (allPromise) {
-      const listed = findInList(await allPromise, slug);
-      if (listed) return listed;
+    let listed;
+    if (loadedPromise) {
+      const loaded = await loadedPromise;
+      listed = findInList(loaded.items, slug);
+      if (listed && loaded.fromFullEntry.has(slug)) return listed;
     }
     if (fetcher.backend.hasBackend()) {
       try {
@@ -828,10 +918,13 @@ function createRepository(context, options) {
         fetcher.backend.warn(`Entry "${slug}" failed, using fallback: ${errorMessage(error)}`);
       }
     }
-    return findInList(await all(), slug);
+    return listed ?? findInList(await all(), slug);
   }
   function all() {
-    allPromise ??= load();
+    if (!allPromise) {
+      loadedPromise = load();
+      allPromise = loadedPromise.then((loaded) => loaded.items);
+    }
     return allPromise;
   }
   return {
@@ -853,6 +946,7 @@ function createRepository(context, options) {
     },
     reset() {
       allPromise = null;
+      loadedPromise = null;
       bySlugCache.clear();
     }
   };
@@ -865,7 +959,7 @@ async function loadSectionLanding(fetcher, slug, renderMarkdown = createMarkdown
   const source = asString(entryField(entry, options.bodyField ?? "body")) ?? asString(entry.summary);
   return {
     title: asString(entry.title),
-    introHtml: source ? await renderMarkdown(preserveSoftBreaks(source)) : void 0,
+    introHtml: source ? await renderMarkdown(preserveSoftBreaks(source), { embeds: entryEmbeds(entry) }) : void 0,
     hero: assetUrl(selectAssetByRole(entry, options.heroRole ?? "hero"))
   };
 }
@@ -952,6 +1046,10 @@ function transformMarvinSite(marvinSite, fallback) {
       canonicalUrl: asString(config.canonicalUrl),
       siteName: title
     }),
+    // Older servers and SDKs don't send it; `siteEmbeds` returns undefined then.
+    embeds: siteEmbeds(
+      config.embeds ?? marvinSite.embeds
+    ),
     metadata
   };
 }
@@ -1083,14 +1181,17 @@ export {
   describeConfig,
   entryAssets,
   entryData,
+  entryEmbeds,
   entryField,
   entryMetadata,
   entryResources,
   errorMessage,
   field,
+  findEmbed,
   focalPoint,
   formatDisplayDate,
   isExternalHref,
+  isFullEntry,
   isNetworkFailure,
   loadSectionLanding,
   metadataLink,
@@ -1105,6 +1206,7 @@ export {
   selectIconAsset,
   selectImageAsset,
   selectValuesForPage,
+  siteEmbeds,
   socialLinkFromKey,
   toNavigationLink
 };