@inneropen/marvin-astro 1.1.1 → 1.2.0

package/src/renderers/validation.ts

@@ -0,0 +1,55 @@
+import type { RendererRegistry } from './types.js';
+import type { MissingRenderer, ValidationResult } from './validation-types.js';
+
+interface EntryTypeWithRendering {
+  slug: string;
+  name: string;
+  isRendered?: boolean;
+  rendering?: Record<string, unknown> | null;
+}
+
+function isRendererRegistry(value: unknown): value is RendererRegistry {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as RendererRegistry).has === 'function'
+  );
+}
+
+export function validateRenderers(
+  entryTypes: EntryTypeWithRendering[],
+  registry: RendererRegistry | Record<string, unknown>,
+  options?: { ignore?: string[] }
+): ValidationResult {
+  const ignore = new Set(options?.ignore ?? []);
+
+  const withRenderer = entryTypes.filter(
+    (et) => et.isRendered && et.rendering?.renderer && !ignore.has(et.slug)
+  );
+
+  const hasRenderer = isRendererRegistry(registry)
+    ? (name: string) => registry.has(name)
+    : (name: string) => name in registry;
+
+  const missing: MissingRenderer[] = [];
+
+  for (const et of withRenderer) {
+    const rendering = et.rendering!;
+    const renderer = rendering.renderer as string;
+    if (!hasRenderer(renderer)) {
+      missing.push({
+        entryTypeSlug: et.slug,
+        entryTypeName: et.name,
+        renderer,
+        package: (rendering.package as string) ?? undefined,
+        version: (rendering.version as string) ?? undefined,
+      });
+    }
+  }
+
+  return {
+    total: withRenderer.length,
+    covered: withRenderer.length - missing.length,
+    missing,
+  };
+}

package/src/repository.ts

@@ -0,0 +1,190 @@
+/**
+ * The repository factory.
+ *
+ * `getAll` / `getBySlug` / `getFeatured` is the same forty lines of try / fallback / memoize
+ * around every content type on every site. Only the transform differs. This holds the forty
+ * lines; the site writes the transform.
+ */
+
+import { errorMessage } from './client.js';
+import { createFieldAccessor, type FieldAccessor } from './fields.js';
+import type { MarvinFetcher } from './fetch.js';
+import type { MarkdownRenderer } from './markdown.js';
+import type { MarvinContentEntry } from './types.js';
+
+export type RepositoryOptions<T> = {
+  /** Collection slug to load from. */
+  collection?: string;
+  /**
+   * Collection slugs tried in order; the first one that yields entries wins. Lets a site work
+   * against workspaces that named the same thing `bench-notes`, `journal`, or `blog`.
+   */
+  collections?: string[];
+  /**
+   * 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.
+   */
+  hydrate?: boolean;
+  /** Build the resolved item from an entry. May be async (e.g. to render markdown). */
+  transform: (entry: MarvinContentEntry, fields: FieldAccessor) => T | Promise<T>;
+  /** Static data to serve when Marvin is unreachable or the collection is empty. */
+  fallback?: () => T[] | Promise<T[]>;
+  /** Applied to Marvin and fallback results alike, so ordering doesn't depend on the source. */
+  sort?: (a: T, b: T) => number;
+  /** Applied to Marvin and fallback results alike. */
+  filter?: (item: T) => boolean;
+  /** The route an entry resolves to; exposed to the transform as `fields.href`. */
+  href?: (slug: string, entry: MarvinContentEntry) => string;
+  /** How to read an item's slug for `bySlug`. Defaults to `item.slug`. */
+  slugOf?: (item: T) => string | undefined;
+  /** How to tell whether an item is featured. Defaults to `item.featured`. */
+  isFeatured?: (item: T) => boolean;
+};
+
+export type Repository<T> = {
+  /** Every item, resolved once per process. */
+  all(): Promise<T[]>;
+  /**
+   * One item by slug. Served from `all()` once that has loaded; otherwise a direct entry
+   * fetch, falling back to a scan of `all()`.
+   */
+  bySlug(slug: string): Promise<T | undefined>;
+  /** The first featured item, or the first item when none is marked. */
+  featured(): Promise<T | undefined>;
+  /** Every featured item, in `all()` order. */
+  allFeatured(): Promise<T[]>;
+  /** Drop the memoized results. Next call re-fetches. */
+  reset(): void;
+};
+
+export type RepositoryContext = {
+  fetcher: MarvinFetcher;
+  renderMarkdown: MarkdownRenderer;
+};
+
+function defaultSlugOf<T>(item: T): string | undefined {
+  const slug = (item as { slug?: unknown }).slug;
+  return typeof slug === 'string' ? slug : undefined;
+}
+
+function defaultIsFeatured<T>(item: T): boolean {
+  return Boolean((item as { featured?: unknown }).featured);
+}
+
+export function createRepository<T>(
+  context: RepositoryContext,
+  options: RepositoryOptions<T>
+): Repository<T> {
+  const { fetcher, renderMarkdown } = context;
+  const collections = options.collections ?? (options.collection ? [options.collection] : []);
+  const slugOf = options.slugOf ?? defaultSlugOf;
+  const isFeatured = options.isFeatured ?? defaultIsFeatured;
+
+  let allPromise: Promise<T[]> | null = null;
+  const bySlugCache = new Map<string, Promise<T | undefined>>();
+
+  function arrange(items: T[]): T[] {
+    const filtered = options.filter ? items.filter(options.filter) : items;
+    return options.sort ? [...filtered].sort(options.sort) : filtered;
+  }
+
+  function transform(entry: MarvinContentEntry, collection?: string): Promise<T> {
+    const slug = (entry as { slug?: string }).slug ?? '';
+    const fields = createFieldAccessor(entry, {
+      renderMarkdown,
+      href: options.href?.(slug, entry),
+      collection,
+    });
+    return Promise.resolve(options.transform(entry, fields));
+  }
+
+  async function useFallback(): Promise<T[]> {
+    return arrange((await options.fallback?.()) ?? []);
+  }
+
+  async function load(): Promise<T[]> {
+    if (collections.length > 0 && fetcher.backend.hasBackend()) {
+      try {
+        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);
+        }
+      } catch (error) {
+        fetcher.backend.remember(error);
+        fetcher.backend.warn(
+          `Collection "${collections[0]}" failed, using fallback: ${errorMessage(error)}`
+        );
+      }
+    }
+
+    return useFallback();
+  }
+
+  function findInList(items: T[], slug: string): T | undefined {
+    return items.find((item) => slugOf(item) === slug);
+  }
+
+  async function loadBySlug(slug: string): Promise<T | undefined> {
+    // Once the list has loaded, every slug in it is already transformed — a per-entry fetch
+    // would be a second request (and a second hydration) for the same content. On a 280-entry
+    // site that was ~1.4s per detail page.
+    if (allPromise) {
+      const listed = findInList(await allPromise, slug);
+      if (listed) return listed;
+    }
+
+    if (fetcher.backend.hasBackend()) {
+      try {
+        const entry = await fetcher.entry(slug);
+        if (entry) return await transform(entry);
+      } catch (error) {
+        fetcher.backend.remember(error);
+        fetcher.backend.warn(`Entry "${slug}" failed, using fallback: ${errorMessage(error)}`);
+      }
+    }
+
+    // No backend, no such entry, or a transform that blew up: fall back to the resolved list,
+    // which is either Marvin's or the static data — the caller doesn't need to care which.
+    return findInList(await all(), slug);
+  }
+
+  function all(): Promise<T[]> {
+    allPromise ??= load();
+    return allPromise;
+  }
+
+  return {
+    all,
+
+    bySlug(slug: string): Promise<T | undefined> {
+      let cached = bySlugCache.get(slug);
+      if (!cached) {
+        cached = loadBySlug(slug);
+        bySlugCache.set(slug, cached);
+      }
+      return cached;
+    },
+
+    async allFeatured(): Promise<T[]> {
+      return (await all()).filter(isFeatured);
+    },
+
+    async featured(): Promise<T | undefined> {
+      const items = await all();
+      return items.find(isFeatured) ?? items[0];
+    },
+
+    reset() {
+      allPromise = null;
+      bySlugCache.clear();
+    },
+  };
+}

package/src/sections.ts

@@ -0,0 +1,39 @@
+import { entryEmbeds } from './embeds.js';
+import type { MarvinFetcher } from './fetch.js';
+import { createMarkdownRenderer, preserveSoftBreaks, type MarkdownRenderer } from './markdown.js';
+import { asString, assetUrl, entryField, selectAssetByRole } from './normalize.js';
+import type { SectionLanding } from './types.js';
+
+export type SectionLandingOptions = {
+  /** Asset role to use as the hero image. Default `'hero'`. */
+  heroRole?: string;
+  /** Field holding the intro copy. Default `'body'`, falling back to the entry summary. */
+  bodyField?: string;
+};
+
+/**
+ * Resolve a section-landing header from a Marvin `page` entry with the given slug.
+ *
+ * The intro is rendered with authored line breaks preserved — landing copy is written as a few
+ * deliberate lines, not a soft-wrapped paragraph, and losing those breaks changes the layout.
+ */
+export async function loadSectionLanding(
+  fetcher: MarvinFetcher,
+  slug: string,
+  renderMarkdown: MarkdownRenderer = createMarkdownRenderer(),
+  options: SectionLandingOptions = {}
+): Promise<SectionLanding> {
+  const entry = await fetcher.entry(slug);
+  if (!entry) return {};
+
+  const source =
+    asString(entryField(entry, options.bodyField ?? 'body')) ?? asString(entry.summary);
+
+  return {
+    title: asString(entry.title),
+    introHtml: source
+      ? await renderMarkdown(preserveSoftBreaks(source), { embeds: entryEmbeds(entry) })
+      : undefined,
+    hero: assetUrl(selectAssetByRole(entry, options.heroRole ?? 'hero')),
+  };
+}

package/src/site.ts

@@ -0,0 +1,222 @@
+/**
+ * Site identity + SEO.
+ *
+ * Marvin's site configuration is optional almost everywhere; a template that had to guard every
+ * field would be unreadable. This resolves it once into an `ApiSite` where title, description,
+ * siteName, locale and timezone are always present, and where brand asset slugs have already
+ * become URLs.
+ */
+
+import type { MarvinSite, SiteConfiguration } from '@inneropen/marvin-sdk';
+import { siteEmbeds } from './embeds.js';
+import type { MarvinFetcher } from './fetch.js';
+import { asRecord, asString, assetUrl } from './normalize.js';
+import type { ApiSeo, ApiSite } from './types.js';
+
+export type SiteOptions = {
+  /**
+   * Static identity to fall back to, field by field, when Marvin is unreachable or leaves a
+   * value unset. Anything omitted here falls through to a neutral default.
+   */
+  fallback?: Partial<ApiSite> | (() => Partial<ApiSite>);
+  /** Default locale when neither Marvin nor the fallback sets one. Default `'en-US'`. */
+  defaultLocale?: string;
+  /** Default timezone when neither Marvin nor the fallback sets one. Default `'UTC'`. */
+  defaultTimezone?: string;
+};
+
+/**
+ * Build resolved SEO from Marvin's raw SiteSeo block, applying identity fallbacks so title,
+ * description and siteName are never empty. Absent → sensible defaults (robots `index,follow`;
+ * og type `website`; large-image Twitter card).
+ */
+export function buildSeo(
+  raw: Record<string, unknown> | undefined,
+  identity: { title: string; description: string; canonicalUrl?: string; siteName: string }
+): ApiSeo {
+  const seo = raw ?? {};
+  const verification = asRecord(seo.verification);
+
+  return {
+    title: asString(seo.title) ?? identity.title,
+    titleTemplate: asString(seo.titleTemplate),
+    description: asString(seo.description) ?? identity.description,
+    keywords: Array.isArray(seo.keywords)
+      ? seo.keywords.filter((keyword): keyword is string => typeof keyword === 'string')
+      : [],
+    robots: asString(seo.robots) ?? 'index,follow',
+    image: asString(seo.image),
+    imageAlt: asString(seo.imageAlt),
+    ogType: asString(seo.ogType) ?? 'website',
+    siteName: asString(seo.siteName) ?? identity.siteName,
+    twitterCard: asString(seo.twitterCard) ?? 'summary_large_image',
+    twitterHandle: asString(seo.twitterHandle),
+    twitterCreator: asString(seo.twitterCreator),
+    fbAppId: asString(seo.fbAppId),
+    themeColor: asString(seo.themeColor),
+    publisher: asString(seo.publisher),
+    canonicalUrl: identity.canonicalUrl,
+    verification: {
+      google: asString(verification.google),
+      bing: asString(verification.bing),
+      pinterest: asString(verification.pinterest),
+      yandex: asString(verification.yandex),
+    },
+  };
+}
+
+function normalizeSocial(social: unknown): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(asRecord(social)).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1].length > 0
+    )
+  );
+}
+
+/** The offline site: the caller's fallback, with neutral defaults under it. */
+export function buildFallbackSite(options: SiteOptions = {}): ApiSite {
+  const provided = typeof options.fallback === 'function' ? options.fallback() : options.fallback;
+  const fallback = provided ?? {};
+  const title = fallback.title ?? fallback.name ?? 'Untitled site';
+  const description = fallback.description ?? '';
+
+  return {
+    ...fallback,
+    name: fallback.name ?? title,
+    title,
+    description,
+    locale: fallback.locale ?? options.defaultLocale ?? 'en-US',
+    timezone: fallback.timezone ?? options.defaultTimezone ?? 'UTC',
+    social: fallback.social ?? {},
+    metadata: fallback.metadata ?? {},
+    seo:
+      fallback.seo ??
+      buildSeo(undefined, { title, description, siteName: fallback.name ?? title }),
+  };
+}
+
+function transformMarvinSite(marvinSite: MarvinSite, fallback: ApiSite): ApiSite {
+  const config: SiteConfiguration = marvinSite.site;
+  const metadata = asRecord(config.metadataJson);
+  const title =
+    asString(config.title) ?? asString(marvinSite.workspace?.name) ?? fallback.title;
+  const description = asString(config.description) ?? fallback.description;
+
+  return {
+    workspaceSlug: asString(marvinSite.workspace?.slug),
+    workspaceName: asString(marvinSite.workspace?.name),
+    name: title,
+    title,
+    tagline: asString(config.tagline) ?? fallback.tagline,
+    description,
+    canonicalUrl: asString(config.canonicalUrl) ?? fallback.canonicalUrl,
+    logo: asString(config.logo) ?? fallback.logo,
+    favicon: asString(config.favicon) ?? fallback.favicon,
+    locale: asString(config.locale) ?? fallback.locale,
+    timezone: asString(config.timezone) ?? fallback.timezone,
+    email: asString(config.contactEmail) ?? fallback.email,
+    imprint: asString(metadata.imprint) ?? fallback.imprint,
+    social: { ...fallback.social, ...normalizeSocial(config.social) },
+    // Typed `config.seo` when the SDK declares it, else the raw `metadata.seo` blob — older
+    // SDKs drop the typed field but pass the blob through untouched, and workspaces configured
+    // before the typed field existed still only have the blob.
+    seo: buildSeo(asRecord((config as { seo?: unknown }).seo ?? metadata.seo), {
+      title,
+      description,
+      canonicalUrl: asString(config.canonicalUrl),
+      siteName: title,
+    }),
+    // Older servers and SDKs don't send it; `siteEmbeds` returns undefined then.
+    embeds: siteEmbeds(
+      (config as { embeds?: unknown }).embeds ?? (marvinSite as { embeds?: unknown }).embeds
+    ),
+    metadata,
+  };
+}
+
+function looksLikeAssetSlug(value: string): boolean {
+  return !/^https?:\/\//.test(value) && !value.startsWith('/') && !value.startsWith('data:');
+}
+
+export type SiteLoader = {
+  get(): Promise<ApiSite>;
+  reset(): void;
+};
+
+export function createSiteLoader(fetcher: MarvinFetcher, options: SiteOptions = {}): SiteLoader {
+  const fallback = buildFallbackSite(options);
+  let promise: Promise<ApiSite> | null = null;
+
+  async function resolveAssetSlug(slug: string | undefined): Promise<string | undefined> {
+    if (!slug) return undefined;
+    return assetUrl(await fetcher.asset(slug));
+  }
+
+  // Resolve a value only when it looks like a bare asset slug; a URL/path/data URI (or a slug with
+  // no matching asset) is returned unchanged.
+  async function resolveMaybeSlug(value: string | undefined): Promise<string | undefined> {
+    if (!value || !looksLikeAssetSlug(value)) return value;
+    return (await resolveAssetSlug(value)) ?? value;
+  }
+
+  async function load(): Promise<ApiSite> {
+    const marvinSite = await fetcher.site();
+    if (!marvinSite) return fallback;
+
+    const site = transformMarvinSite(marvinSite, fallback);
+
+    // Brand-asset registry: resolve EVERY `brand.<name>` slug → URL in one pass. A site adds a
+    // shared asset with one config line (`brand.paperFold = "paper-fold"`) plus an upload;
+    // components then read `site.brand.paperFold`. No code change per asset.
+    const brandPairs = Object.entries(asRecord(site.metadata.brand)).filter(
+      (entry): entry is [string, string] =>
+        typeof entry[1] === 'string' && entry[1].trim().length > 0
+    );
+    const resolved = await Promise.all(
+      brandPairs.map(async ([name, slug]) => [name, await resolveAssetSlug(slug)] as const)
+    );
+    const brand: Record<string, string> = {};
+    const brandBySlug = new Map<string, string>();
+    for (const [index, [name, url]] of resolved.entries()) {
+      if (!url) continue;
+      brand[name] = url;
+      brandBySlug.set(brandPairs[index][1], url);
+    }
+
+    // The og:image may be given as a bare asset slug too. It is usually one of the brand slugs
+    // (a monogram, a logo), so check what was just resolved before fetching it again.
+    const rawImage = site.seo.image;
+    const ogImage =
+      rawImage && looksLikeAssetSlug(rawImage)
+        ? (brandBySlug.get(rawImage) ?? (await resolveAssetSlug(rawImage)))
+        : undefined;
+
+    // The top-level `site_logo` / `site_favicon` fields may be bare asset slugs too (like brand.*
+    // and og:image) — resolve them so they can reference an uploaded asset by slug. The brand-map
+    // aliases still win when present.
+    const logo = brand.logo ?? (await resolveMaybeSlug(site.logo));
+    const favicon = brand.favicon ?? (await resolveMaybeSlug(site.favicon));
+
+    return {
+      ...site,
+      brand,
+      // Convenience aliases for common callers; all of these also live in `site.brand`.
+      logo,
+      favicon,
+      seal: brand.seal ?? site.seal,
+      seo: { ...site.seo, image: ogImage ?? site.seo.image },
+    };
+  }
+
+  return {
+    get() {
+      // Memoized: components like a per-card brand stamp render many instances per page, so
+      // this keeps brand-slug resolution to once per process rather than once per render.
+      promise ??= load();
+      return promise;
+    },
+    reset() {
+      promise = null;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,188 @@
+/**
+ * Site-integration types.
+ *
+ * These are the *resolved* shapes a site renders from — Marvin's raw payloads normalized,
+ * defaulted, and made non-optional where a template would otherwise need a guard on every
+ * use. Nothing here is specific to a particular site's design system.
+ */
+
+import type { MarvinSiteEmbeds } from './embeds.js';
+import type {
+  CollectionEntry,
+  Entry,
+  MarvinEntry,
+  MarvinEntryListItem,
+} from '@inneropen/marvin-sdk';
+
+/**
+ * Any entry shape the published API can hand back. `MarvinEntry`/`Entry` carry `data_json`;
+ * `CollectionEntry`/`MarvinEntryListItem` (list items) do not — see the `hydrate` repository
+ * option.
+ */
+export type MarvinContentEntry = MarvinEntry | Entry | CollectionEntry | MarvinEntryListItem;
+
+/** Criteria for picking one asset off an entry's `assets[]`. */
+export type AssetSelectOptions = {
+  role?: string;
+  roles?: string[];
+  usage?: string;
+  usages?: string[];
+  type?: string;
+  types?: string[];
+  mimeType?: string;
+  /** Also accept assets carrying neither a role nor a usage. */
+  allowUnroled?: boolean;
+};
+
+/** A resolved image: a URL plus the presentation hints stored alongside the asset. */
+export type ApiImage = {
+  src: string;
+  alt: string;
+  /** CSS `object-position` value, e.g. `"40% 65%"`. */
+  focalPoint?: string;
+};
+
+/** A resolved link to an attached resource (material, construction detail, document…). */
+export type ApiResourceLink = {
+  name: string;
+  /** The resource type, e.g. `'material'`, `'construction'`. */
+  type: string;
+  /** The relationship role, e.g. `'primary-material'`. */
+  role?: string;
+  slug?: string;
+  href?: string;
+};
+
+/**
+ * Resolved SEO / social-sharing metadata for the site. Mirrors Marvin's SiteSeo, with identity
+ * fallbacks already applied (title/description/siteName never empty). The rendering layer
+ * (SeoHead) turns this into the actual `<meta>`/Open Graph/Twitter tags.
+ */
+export type ApiSeo = {
+  title: string;
+  titleTemplate?: string;
+  description: string;
+  keywords: string[];
+  robots: string;
+  image?: string;
+  imageAlt?: string;
+  ogType: string;
+  siteName: string;
+  twitterCard: string;
+  twitterHandle?: string;
+  twitterCreator?: string;
+  fbAppId?: string;
+  themeColor?: string;
+  publisher?: string;
+  canonicalUrl?: string;
+  verification: {
+    google?: string;
+    bing?: string;
+    pinterest?: string;
+    yandex?: string;
+  };
+};
+
+export type ApiSite = {
+  workspaceSlug?: string;
+  workspaceName?: string;
+  name: string;
+  title: string;
+  tagline?: string;
+  description: string;
+  canonicalUrl?: string;
+  logo?: string;
+  favicon?: string;
+  /** Round maker's stamp / seal — resolved from `site_metadata_json.brand.seal` (asset slug). */
+  seal?: string;
+  /**
+   * Brand-asset registry: every `site_metadata_json.brand.<name>` slug resolved to its URL.
+   * Add a shared asset with one config line; components read `site.brand.<name>`.
+   */
+  brand?: Record<string, string>;
+  locale: string;
+  timezone: string;
+  email?: string;
+  imprint?: string;
+  social: Record<string, string>;
+  seo: ApiSeo;
+  /**
+   * Embed privacy mode, consent text and the frame sources a `frame-src` CSP must allow.
+   * Absent when the server predates media embeds.
+   */
+  embeds?: MarvinSiteEmbeds;
+  metadata: Record<string, unknown>;
+};
+
+export type ApiNavigationLink = {
+  label: string;
+  href: string;
+  description?: string;
+  external: boolean;
+  /** Membership role from the nav collection (e.g. `'primary'`, `'legal'`). Drives grouping. */
+  role?: string;
+};
+
+export type ApiSocialLink = ApiNavigationLink & {
+  icon: string;
+};
+
+export type ApiSiteChrome = {
+  site: ApiSite;
+  mainNavigation: ApiNavigationLink[];
+  footerNavigation: ApiNavigationLink[][];
+  /** Legal links (`role: 'legal'` in the footer nav collection), e.g. Terms/Privacy. */
+  legalLinks: ApiNavigationLink[];
+  socialLinks: ApiSocialLink[];
+  inquiry?: ApiNavigationLink;
+};
+
+export type ApiActionVariant = 'primary' | 'secondary';
+
+export type ApiPageAction = ApiNavigationLink & {
+  variant: ApiActionVariant;
+};
+
+export type ApiHeroAction = ApiPageAction;
+
+export type ApiHero = {
+  kicker: string;
+  headline: string;
+  body: string;
+  actions: ApiHeroAction[];
+  layout: 'split' | 'centered';
+  image?: {
+    src?: string;
+    alt: string;
+    focalPoint?: string;
+    dominantColor?: string;
+    fit?: 'cover' | 'contain';
+    caption?: string;
+    credit?: string;
+    orientation?: string;
+  };
+};
+
+/**
+ * A section-landing header driven by a Marvin `page` entry (e.g. `bench-notes`, `projects`).
+ * The entry is linkable in nav (collection membership) AND supplies the landing's title, intro,
+ * and hero — so the top of an index page stops being static. Absent fields resolve to
+ * `undefined` so callers fall back to their existing copy/illustration.
+ */
+export type SectionLanding = {
+  title?: string;
+  /** The `body` field (or summary) rendered from markdown to HTML — render with `set:html`. */
+  introHtml?: string;
+  hero?: string;
+};
+
+export type {
+  MarvinEmbed,
+  MarvinEmbedIframe,
+  MarvinEmbedKind,
+  MarvinEmbedLink,
+  MarvinEmbedMode,
+  MarvinEmbeds,
+  MarvinEmbedStatus,
+  MarvinSiteEmbeds,
+} from './embeds.js';