@inneropen/marvin-astro 1.1.0 → 1.2.0

package/src/chrome.ts

@@ -0,0 +1,242 @@
+/**
+ * Site chrome: main nav, footer columns, legal strip, social links, inquiry link.
+ *
+ * All of it comes from ordinary Marvin collections, so a workspace can reorder its own
+ * navigation without a deploy. Every piece has a static fallback for when the backend is down.
+ */
+
+import type { MarvinFetcher, HydratedEntry } from './fetch.js';
+import {
+  asRecord,
+  asString,
+  collectionRole,
+  collectionSlugs,
+  entryField,
+  isExternalHref,
+} from './normalize.js';
+import type { SiteLoader } from './site.js';
+import type { ApiNavigationLink, ApiSiteChrome, ApiSocialLink, MarvinContentEntry } from './types.js';
+
+export type NavigationContext = 'main' | 'footer';
+
+export type HrefContext = {
+  /** Where this link is being rendered. */
+  context: NavigationContext;
+  /** The nav collection the entry was read from. */
+  collectionSlug: string;
+  slug: string;
+  /** Every collection the entry belongs to, nav collections included. */
+  collections: string[];
+  /** The collection slugs treated as navigation, i.e. not route prefixes. */
+  navCollections: Set<string>;
+};
+
+export type ResolveHref = (entry: MarvinContentEntry, context: HrefContext) => string;
+
+/** A link authored in site code rather than in the CMS. */
+export type NavigationLinkInput = {
+  label: string;
+  href: string;
+  description?: string;
+  role?: string;
+};
+
+export type SocialLinkInput = NavigationLinkInput & { icon: string };
+
+export type ChromeOptions = {
+  /** Collection holding the main nav. Default `'main-navigation'`. */
+  mainCollection?: string;
+  /** Collection holding the footer nav. Default `'footer-navigation'`. */
+  footerCollection?: string;
+  /**
+   * Route for a nav entry that carries no explicit `href`/`url`/`path` field.
+   *
+   * The default prefixes the entry's own (non-navigation) collection: an entry in
+   * `workshop-reference` becomes `/workshop-reference/<slug>`, and an entry in no other
+   * collection becomes `/<slug>`. Override when routes don't mirror collections.
+   */
+  resolveHref?: ResolveHref;
+  /** Membership role that marks a footer link as legal (Terms, Privacy…). Default `'legal'`. */
+  legalRole?: string;
+  /** Footer links per column once split. Columns are only created above this count. */
+  footerColumnThreshold?: number;
+  fallback?: {
+    mainNavigation?: NavigationLinkInput[];
+    footerNavigation?: NavigationLinkInput[][];
+    legalLinks?: NavigationLinkInput[];
+    socialLinks?: SocialLinkInput[];
+    inquiry?: NavigationLinkInput;
+  };
+};
+
+export function toNavigationLink(link: NavigationLinkInput): ApiNavigationLink {
+  return {
+    label: link.label,
+    href: link.href,
+    description: link.description,
+    external: isExternalHref(link.href),
+    role: link.role,
+  };
+}
+
+/** Collection-prefixed routing: `/<owning-collection>/<slug>`, else `/<slug>`. */
+export const defaultResolveHref: ResolveHref = (_entry, context) => {
+  const owning = context.collections.find((slug) => !context.navCollections.has(slug));
+  return owning ? `/${owning}/${context.slug}` : `/${context.slug}`;
+};
+
+/** A `{label, href}` object stored loose in site metadata (e.g. `metadata.inquiry`). */
+export function metadataLink(value: unknown): ApiNavigationLink | undefined {
+  const link = asRecord(value);
+  const label = asString(link.label);
+  const href = asString(link.href);
+  if (!label || !href) return undefined;
+
+  return {
+    label,
+    href,
+    description: asString(link.description) ?? asString(link.subject),
+    external: isExternalHref(href),
+  };
+}
+
+/** Title-case a social key: `x_handle` → `X Handle`, `email` → `Email`. */
+function socialLabel(key: string): string {
+  return key.replace(/[-_]/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+
+export function socialLinkFromKey(key: string, href: string): ApiSocialLink {
+  return {
+    label: socialLabel(key),
+    href,
+    icon: key,
+    external: isExternalHref(href),
+  };
+}
+
+export type ChromeLoader = {
+  get(): Promise<ApiSiteChrome>;
+  reset(): void;
+};
+
+export function createChromeLoader(
+  fetcher: MarvinFetcher,
+  siteLoader: SiteLoader,
+  options: ChromeOptions = {}
+): ChromeLoader {
+  const mainCollection = options.mainCollection ?? 'main-navigation';
+  const footerCollection = options.footerCollection ?? 'footer-navigation';
+  const legalRole = options.legalRole ?? 'legal';
+  const footerColumnThreshold = options.footerColumnThreshold ?? 4;
+  const resolveHref = options.resolveHref ?? defaultResolveHref;
+  const navCollections = new Set([mainCollection, footerCollection]);
+  const fallback = options.fallback ?? {};
+
+  let promise: Promise<ApiSiteChrome> | null = null;
+
+  function entryToLink(
+    entry: HydratedEntry,
+    collectionSlug: string,
+    context: NavigationContext
+  ): ApiNavigationLink {
+    const slug = entry.slug ?? '';
+    const href =
+      asString(entryField(entry, 'href')) ??
+      asString(entryField(entry, 'url')) ??
+      asString(entryField(entry, 'path')) ??
+      resolveHref(entry, {
+        context,
+        collectionSlug,
+        slug,
+        collections: collectionSlugs(entry),
+        navCollections,
+      });
+    const label =
+      asString(entryField(entry, 'label')) ??
+      asString(asRecord((entry as { metadataJson?: unknown }).metadataJson).label) ??
+      asString(entry.title) ??
+      href;
+
+    return {
+      label,
+      href,
+      description:
+        asString(entry.summary) ?? asString((entry as { description?: unknown }).description),
+      external: isExternalHref(href),
+      role: collectionRole(entry, collectionSlug),
+    };
+  }
+
+  async function navigationCollection(
+    slug: string,
+    context: NavigationContext,
+    staticLinks: ApiNavigationLink[]
+  ): Promise<{ links: ApiNavigationLink[]; fromBackend: boolean }> {
+    if (!fetcher.backend.hasBackend()) return { links: staticLinks, fromBackend: false };
+
+    // Hydrated: a nav entry's `href`/`label` overrides are schema fields, absent from list items.
+    const entries = await fetcher.hydratedCollectionEntries(slug);
+    if (entries.length === 0) return { links: staticLinks, fromBackend: false };
+
+    return { links: entries.map((entry) => entryToLink(entry, slug, context)), fromBackend: true };
+  }
+
+  function groupFooterLinks(links: ApiNavigationLink[]): ApiNavigationLink[][] {
+    if (links.length <= footerColumnThreshold) return [links];
+
+    const midpoint = Math.ceil(links.length / 2);
+    return [links.slice(0, midpoint), links.slice(midpoint)];
+  }
+
+  async function load(): Promise<ApiSiteChrome> {
+    const site = await siteLoader.get();
+    const staticMain = (fallback.mainNavigation ?? []).map(toNavigationLink);
+    const staticFooter = (fallback.footerNavigation ?? []).map((group) =>
+      group.map(toNavigationLink)
+    );
+
+    const main = await navigationCollection(mainCollection, 'main', staticMain);
+    const footer = await navigationCollection(footerCollection, 'footer', staticFooter.flat());
+
+    const socialLinks = Object.entries(site.social).map(([key, href]) =>
+      socialLinkFromKey(key, href)
+    );
+    if (site.email && !socialLinks.some((link) => link.icon === 'email')) {
+      socialLinks.push(socialLinkFromKey('email', `mailto:${site.email}`));
+    }
+
+    // Split footer links by membership role: legal → the legal strip; everything else → columns.
+    const legalLinks = footer.fromBackend
+      ? footer.links.filter((link) => link.role === legalRole)
+      : [];
+    const columnLinks = footer.links.filter((link) => link.role !== legalRole);
+    const staticLegal = (fallback.legalLinks ?? []).map(toNavigationLink);
+
+    return {
+      site,
+      mainNavigation: main.links,
+      footerNavigation: footer.fromBackend ? groupFooterLinks(columnLinks) : staticFooter,
+      legalLinks: legalLinks.length > 0 ? legalLinks : staticLegal,
+      socialLinks:
+        socialLinks.length > 0
+          ? socialLinks
+          : (fallback.socialLinks ?? []).map((link) => ({
+              ...toNavigationLink(link),
+              icon: link.icon,
+            })),
+      inquiry:
+        metadataLink(site.metadata.inquiry) ??
+        (fallback.inquiry ? toNavigationLink(fallback.inquiry) : undefined),
+    };
+  }
+
+  return {
+    get() {
+      promise ??= load();
+      return promise;
+    },
+    reset() {
+      promise = null;
+    },
+  };
+}

package/src/client.ts

@@ -0,0 +1,119 @@
+/**
+ * SDK client construction and the network-failure latch.
+ *
+ * The latch exists because a static build asks for content once per path. When the backend is
+ * down, that is N failed requests with N timeouts before the build gives up. The latch trips on
+ * the first network failure and short-circuits the rest.
+ *
+ * Unlike the hand-rolled original it is *retryable*: it expires after `retryAfterMs` so a dev
+ * server recovers on its own when the backend comes back, instead of serving stale static data
+ * until someone restarts it. Production keeps the permanent latch — a build should fail fast and
+ * consistently rather than half-succeed.
+ */
+
+import { createMarvinClient } from '@inneropen/marvin-sdk';
+import type { MarvinClient } from '@inneropen/marvin-sdk';
+import {
+  describeConfig,
+  resolveConfig,
+  type MarvinAstroConfig,
+  type ResolvedConfig,
+} from './config.js';
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+/**
+ * A network failure means "the backend is unreachable", not "this request was bad". Only the
+ * former should trip the latch — a 404 on one entry says nothing about the next one.
+ */
+export function isNetworkFailure(error: unknown): boolean {
+  const message = errorMessage(error).toLowerCase();
+  return (
+    message.includes('network error') ||
+    message.includes('fetch failed') ||
+    message.includes('econnrefused') ||
+    message.includes('enotfound') ||
+    message.includes('etimedout')
+  );
+}
+
+export type MarvinBackend = {
+  readonly config: ResolvedConfig;
+  /** True when Marvin is configured AND not currently latched out. */
+  hasBackend(): boolean;
+  /** The SDK client. Throws when Marvin is not configured. */
+  client(): MarvinClient;
+  /** Trip the latch if this error indicates the backend is unreachable. */
+  remember(error: unknown): void;
+  /** True while the latch is closed (backend considered unreachable). */
+  isLatched(): boolean;
+  /** Manually re-open the latch, e.g. after a deploy. */
+  clearLatch(): void;
+  warn(message: string): void;
+};
+
+export function createBackend(options: MarvinAstroConfig = {}): MarvinBackend {
+  const config = resolveConfig(options);
+  let client: MarvinClient | null = null;
+  let latchedAt: number | null = null;
+  let envLogged = false;
+
+  function isLatched(): boolean {
+    if (latchedAt === null) return false;
+    if (config.retryAfterMs === Number.POSITIVE_INFINITY) return true;
+    if (config.now() - latchedAt < config.retryAfterMs) return true;
+
+    // Expired — re-open and let the next call find out whether the backend is back.
+    latchedAt = null;
+    return false;
+  }
+
+  function hasBackend(): boolean {
+    if (config.debug && !envLogged) {
+      envLogged = true;
+      config.logger.log('[marvin-astro] env check:', describeConfig(config));
+    }
+    if (!config.configured) return false;
+    return !isLatched();
+  }
+
+  return {
+    config,
+    hasBackend,
+    isLatched,
+    clearLatch() {
+      latchedAt = null;
+    },
+    remember(error: unknown) {
+      if (isNetworkFailure(error)) latchedAt = config.now();
+    },
+    warn(message: string) {
+      config.logger.warn(`[marvin-astro] ${message}`);
+    },
+    client(): MarvinClient {
+      if (!config.configured) {
+        throw new Error(
+          '[marvin-astro] Marvin is not configured. Set MARVIN_API_URL, ' +
+            'MARVIN_SITE_CLIENT_TOKEN and MARVIN_WORKSPACE_SLUG, or pass them to createMarvinContent().'
+        );
+      }
+      client ??= (config.createClient
+        ? config.createClient({
+            apiUrl: config.apiUrl,
+            siteClientToken: config.siteClientToken,
+            workspaceSlug: config.workspaceSlug,
+            debug: config.debug,
+          })
+        : createMarvinClient({
+            apiUrl: config.apiUrl,
+            siteClientToken: config.siteClientToken,
+            workspaceSlug: config.workspaceSlug,
+            debug: config.debug,
+          })) as MarvinClient;
+      return client;
+    },
+  };
+}

package/src/components/Embed.astro

@@ -0,0 +1,119 @@
+---
+/**
+ * Embed — render a Marvin `PublishedEmbed` from its structured fields.
+ *
+ * - `status: 'ok'` with an allowed iframe → the player (`mode="direct"`) or a click-to-load facade
+ *   (`mode="click_to_load"`, the default: nothing loads from the provider until the visitor clicks).
+ * - anything else → a plain link card.
+ *
+ * The markup matches the `html` Marvin publishes for the same embed and mode, so either renders
+ * the same with the same CSS. Use it for `embed` fields (`f.embed('video')`); markdown bodies
+ * already carry Marvin's `html`. Facades need `<EmbedLoader />` once in the layout.
+ */
+import type { MarvinEmbed, MarvinEmbedMode } from '../embeds.js';
+import { frameHostPattern, iframeAttributes, isAllowedFrameSrc, safeLinkHref } from './embed-frame.js';
+import LinkCard from './LinkCard.astro';
+
+interface Props {
+  embed: MarvinEmbed | null | undefined;
+  /** `site.embeds.mode`. Default `click_to_load`. */
+  mode?: MarvinEmbedMode;
+  /** `site.embeds.consentText`, shown on the facade. `{provider}` becomes the provider name. */
+  consentText?: string | null;
+  /** `site.embeds.frameSources`. When given, an iframe outside them renders as a link card. */
+  frameSources?: string[] | null;
+  class?: string;
+}
+
+/** Marvin's default, for a server that doesn't send `site.embeds`. */
+const DEFAULT_CONSENT_TEXT = 'Loading this player connects to {provider}, which may set cookies.';
+
+const { embed, mode = 'click_to_load', consentText, frameSources, class: className } = Astro.props;
+
+const iframe = embed?.status === 'ok' ? (embed.iframe ?? undefined) : undefined;
+const providerName = embed?.providerName || embed?.link?.providerName || 'the provider';
+
+// A facade may load only the iframe's own host — the narrowest list, like Marvin's own facades.
+const ownHost = iframe ? hostOf(iframe.src) : undefined;
+const hosts = ownHost ? [ownHost] : [];
+const withinFrameSources = !frameSources?.length || isAllowedFrameSrc(iframe?.src, frameSources);
+const attributes =
+  iframe && withinFrameSources
+    ? iframeAttributes(
+        {
+          src: iframe.src,
+          title: iframe.title || embed?.title || `${providerName} player`,
+          allow: iframe.allow,
+          sandbox: iframe.sandbox,
+          referrerpolicy: iframe.referrerpolicy || 'strict-origin-when-cross-origin',
+          loading: 'lazy',
+        },
+        hosts
+      )
+    : undefined;
+
+function hostOf(src: unknown): string | undefined {
+  if (typeof src !== 'string') return undefined;
+  try {
+    return frameHostPattern(new URL(src).hostname);
+  } catch {
+    return undefined;
+  }
+}
+
+// Size travels as a CSS custom property on the figure: a fixed height (audio, podcast, playlist)
+// or an aspect ratio (video; 9/16 for Shorts). Validated, never passed through raw.
+function sizeStyle(): string | undefined {
+  const height = iframe?.height;
+  if (typeof height === 'number' && Number.isInteger(height) && height > 0 && height < 5000) {
+    return `--marvin-embed-height:${height}px`;
+  }
+  const aspect = iframe?.aspectRatio;
+  if (typeof aspect === 'string' && /^\d{1,3}\/\d{1,3}$/.test(aspect)) {
+    return `--marvin-embed-aspect:${aspect}`;
+  }
+  return undefined;
+}
+
+const kind = embed ? String(embed.kind).replace(/[^a-z0-9-]/gi, '') || 'video' : 'video';
+const linkTitle = embed?.link?.title || embed?.title || providerName;
+const label = embed?.title || linkTitle;
+const consent = (consentText || DEFAULT_CONSENT_TEXT).replaceAll('{provider}', providerName);
+const linkHref = safeLinkHref(embed?.link?.href ?? embed?.canonicalUrl ?? embed?.url);
+const classes = (...names: (string | false | undefined)[]) => names.filter(Boolean).join(' ');
+---
+
+{embed && attributes && mode === 'direct' && (
+  <figure
+    class={classes('marvin-embed', `marvin-embed--${kind}`, className)}
+    data-provider={embed.provider}
+    style={sizeStyle()}
+  >
+    <iframe {...attributes} />
+  </figure>
+)}
+
+{embed && attributes && mode !== 'direct' && (
+  <figure
+    class={classes('marvin-embed', `marvin-embed--${kind}`, 'marvin-embed--facade', className)}
+    data-provider={embed.provider}
+    style={sizeStyle()}
+  >
+    <button
+      type="button"
+      class="marvin-embed__load"
+      data-marvin-embed-src={attributes.src}
+      data-marvin-embed-attrs={JSON.stringify(attributes)}
+      data-marvin-embed-hosts={JSON.stringify(hosts)}
+    >
+      <span class="marvin-embed__provider">{providerName}</span>
+      <span class="marvin-embed__title">{label}</span>
+      <span class="marvin-embed__consent">{consent}</span>
+    </button>
+    {linkHref && (
+      <a class="marvin-embed__link" href={linkHref} rel="noopener noreferrer">{linkTitle}</a>
+    )}
+  </figure>
+)}
+
+{embed && !attributes && <LinkCard embed={embed} class={className} />}

package/src/components/EmbedLoader.astro

@@ -0,0 +1,24 @@
+---
+/**
+ * EmbedLoader — put this once in your layout.
+ *
+ * In `click_to_load` mode an embed renders as a facade: a button plus a plain link, and no request
+ * to the provider. On click (or Enter/Space — it's a real button) this swaps the button for the
+ * iframe, built only from the facade's `data-marvin-embed-attrs` and refused unless its src is
+ * https on a host in `data-marvin-embed-hosts`.
+ *
+ * Also brings in the base `.marvin-embed` CSS (low-specificity, themeable through
+ * `--marvin-embed-*` custom properties).
+ *
+ * The script is processed by Astro (deduplicated to one per page, however many embeds), so it can
+ * share its tested logic with `<Embed>`. Astro inlines a script this small; if your CSP forbids
+ * inline scripts, hash it or set `vite.build.assetsInlineLimit: 0` to get a file instead.
+ */
+import './embeds.css';
+---
+
+<script>
+  import { installEmbedLoader } from './embed-frame';
+
+  installEmbedLoader(document);
+</script>

package/src/components/EntryRenderer.astro

@@ -0,0 +1,40 @@
+---
+import type { Entry } from '@inneropen/marvin-sdk';
+import type { RendererEntry, RendererRegistry } from '../renderers/types.js';
+import { resolveRendererConfig, resolveRendererName, resolveRendererRequirement, shouldRenderEntry } from '../renderers/resolve.js';
+import { astroRegistry } from './registry.js';
+import { isCoreRendererPackage, resolveRenderer } from '../renderers/registry.js';
+import { debug } from '../renderers/debug.js';
+
+interface Props {
+  entry?: RendererEntry | Entry;
+  config?: Record<string, unknown>;
+  class?: string;
+  registry?: RendererRegistry | Record<string, unknown>;
+}
+
+const { entry, config: configOverrides, class: className, registry: customRegistry } = Astro.props;
+const rendererEntry = typeof (entry as any)?.toJSON === 'function'
+  ? (entry as Entry).toJSON() as RendererEntry
+  : entry as RendererEntry | undefined;
+
+const rendererRequirement = rendererEntry ? resolveRendererRequirement(rendererEntry) : undefined;
+const rendererPackage = rendererRequirement?.packageName;
+const rendererName = rendererEntry ? resolveRendererName(rendererEntry) : undefined;
+const Renderer = isCoreRendererPackage(rendererPackage) && rendererName
+  // The fallback is the core registry itself; passing a component here (as before) looked up
+  // `component[name]` and never rendered anything.
+  ? resolveRenderer(rendererName, customRegistry, astroRegistry)
+  : undefined;
+const canRender = rendererEntry ? shouldRenderEntry(rendererEntry, rendererName) : true;
+const config = rendererEntry ? resolveRendererConfig(rendererEntry, configOverrides) : {};
+debug('EntryRenderer', { slug: rendererEntry?.slug, renderer: rendererName, package: rendererPackage, hasComponent: !!Renderer, canRender });
+---
+
+{rendererEntry && Renderer && canRender ? (
+  <Renderer entry={rendererEntry} config={config} class={className}>
+    <slot />
+  </Renderer>
+) : (
+  <slot />
+)}