@uxfront/layer-docs 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @uxfront/layer-docs
 
+## 0.4.0
+
+### Minor Changes
+
+- a4caf06: Ship OG image support and the two satori card templates.
+
+  Every consumer was registering `nuxt-og-image` itself and carrying its own copy of the templates, which meant carrying a page override too — `defineOgImage` cannot be called from the layer if the module is not registered by it. The layer now registers the module beside `@nuxtjs/sitemap` and `@nuxtjs/robots` (same class of SEO plumbing it already turns on unasked) and calls `defineOgImage` from its own docs and landing pages, so a consumer that extends the layer gets branded cards without writing anything. Opt out with the module's own switch, `ogImage: { enabled: false }`.
+
+  **The accent is a brand token, not a hardcoded colour.** The existing copies hardcoded a Tailwind class, which was wrong in a way that only showed up on the rendered card: every consumer shadows stock Tailwind scale names with its own values in `@theme`, so `text-teal-500` renders Tailwind's teal, not the brand's. Custom properties are not an option either — satori has no CSS cascade, and `var(--ui-primary)` resolves to nothing. The accent is therefore resolved to a literal at build time by following `--ui-primary` to the `--color-<scale>` declaration it aliases in the consumer's registered CSS, the same two hops the browser does and the same pair `describeBrandPaletteCss` already asserts. Override it with a literal via `ogImage.accent` in `app.config.ts`.
+
+  Two parts of the card are components rather than props, because `defineOgImage` serialises its arguments and a Vue slot cannot cross that boundary. Shadow `app/AppOgDecoration.vue` (a neutral radial wash) or `app/AppOgLogo.vue` (a wordmark from `header.title`) at the same path to replace either.
+
+  Cards render at 1200×630 rather than the module's 1200×600 default — 1.91:1 is the ratio crawlers crop to.
+
+  New peer dependencies: `nuxt-og-image`, `satori`, and `@resvg/resvg-js`. Satori renders the template to SVG and needs a separate rasteriser for the PNG; without one, prerendering logs `renderer.createImage error` per card and emits nothing.
+
+- 5cc11f2: Add `StorybookEmbed` and the `@uxfront/layer-docs/storybook` bridge.
+
+  `StorybookEmbed` embeds a deployed Storybook story in a docs page, in one of
+  three modes — `preview` (canvas only), `full` (manager without the sidebar), and
+  `panel` (manager with the controls panel). It mounts lazily, keeps the
+  Storybook's colour mode in sync with the page's, and grows to fit its story
+  without shifting layout. The Storybook host comes from
+  `NUXT_PUBLIC_STORYBOOK_BASE_URL`, with an optional `{framework}` placeholder for
+  per-framework deployments.
+
+  The `/storybook` subpath export ships the other half of that contract:
+  `installDocsEmbedPreviewBridge` and `installDocsEmbedManagerBridge`, which are
+  framework-free and import nothing from Nuxt. A Storybook that already speaks a
+  branded message namespace can name it via
+  `NUXT_PUBLIC_STORYBOOK_LEGACY_MESSAGE_NAMESPACE`, and both sides accept and emit
+  both spellings so the two can deploy in either order.
+
+## 0.3.0
+
+### Minor Changes
+
+- 751810d: Stop registering the layer's own `main.css`, and ship the brand-palette guards consumers were each expected to write themselves.
+
+  **Breaking for any consumer that does not already register its own CSS entry.** The layer registered `app/assets/css/main.css` in `css` while every consumer also imported that same base from its brand CSS — because a brand `@theme` only compiles into real `:root` custom properties when it lives inside a Tailwind pass, which means importing the base rather than sitting beside it. Two entries, two Tailwind passes, and a byte-for-byte duplicate of every base utility in the shipped stylesheet: **+212 KB raw / +26.7 KB gzip (+94%)** on inkline's render-blocking `entry.css`, on every page, for every visitor (UXF-118).
+
+  The layer no longer registers it. Consumers register exactly one CSS entry of their own, whose first line imports the layer base — which is what all three consumers were already doing, one of them via a `modules:done` hook that un-registered what the layer had just registered. That hook can now be deleted.
+
+  **Migration.** If your app already has `css: ["./app/assets/css/main.css"]` pointing at a file that starts with `@import "@uxfront/layer-docs/app/assets/css/main.css"`, nothing changes except that your stylesheet halves; drop any hook that stripped the layer's entry. If it does not, add both — see README § Styling. There is no silent middle state: without a CSS entry the app ships no Tailwind utilities at all.
+
+  **What the duplication actually cost.** Payload, not layout. The duplicate pass measured on inkline was a complete superset of the first and was emitted wholly after it, so the last `sm:`/`lg:` variant still landed after the last conflicting base and won by source order — computed-style A/B across 4 pages × 4 viewports found zero rendering difference. That rescue was incidental rather than designed, which is why the cause is fixed rather than the symptom.
+
+  **New: `@uxfront/layer-docs/test`.** The two guards that would have caught this before ship, now parameterised by brand scale instead of copy-pasted per repo. `describeBrandPaletteCss` asserts, without a build, that your CSS entry imports the layer base before its `@theme` and defines the scale it maps onto `--ui-primary`. `describeSingleTailwindPass` reads the built stylesheet and asserts every base utility is emitted **exactly once** — catching a duplicate pass and a CSS entry that never reached the bundle with the same assertion. `vitest` is an optional peer dependency, needed only for these.
+
+  Also fixed: three code comments claimed the second pass "kills every `sm:`/`lg:` responsive variant". It does not, in the equal-superset case measured; the guards now describe the duplicate payload they actually guard.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -20,8 +20,9 @@ npm install -D @uxfront/layer-docs
 Then install the peer dependencies the layer expects (the Nuxt documentation
 stack — see [`package.json`](./package.json) `peerDependencies` for pinned
 ranges): `nuxt`, `vue`, `@nuxt/ui`, `@nuxt/image`, `@nuxt/scripts`,
-`@nuxtjs/robots`, `nuxt-og-image`, `nuxt-llms`, `tailwindcss`, and — for content
-and translation — `@nuxt/content`, `@nuxtjs/i18n`, `@nuxtjs/mdc`.
+`@nuxtjs/robots`, `nuxt-og-image`, `satori`, `@resvg/resvg-js`, `nuxt-llms`,
+`tailwindcss`, and — for content and translation — `@nuxt/content`,
+`@nuxtjs/i18n`, `@nuxtjs/mdc`.
 
 ## Usage
 
@@ -60,6 +61,186 @@ That renders `uxd by UXFront` — the wordmark still links home, `by` is plain
 text, and `UXFront` links out. Omit `attribution` (or leave `label` empty) to
 render the wordmark alone.
 
+## Styling
+
+**The consumer owns the single Tailwind entry.** The layer ships a palette-free
+Tailwind base at `@uxfront/layer-docs/app/assets/css/main.css` and deliberately
+does not register it itself. A brand `@theme` only compiles into real `:root`
+custom properties when it lives inside a Tailwind pass, so your CSS file has to
+_import_ the layer base rather than sit beside it as a second entry — two
+entries each re-emit every base utility into the shipped stylesheet.
+
+Register one CSS entry:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ["@uxfront/layer-docs"],
+  css: ["./app/assets/css/main.css"],
+});
+```
+
+whose first line imports the layer base, followed by your palette:
+
+```css
+/* app/assets/css/main.css */
+@import "@uxfront/layer-docs/app/assets/css/main.css";
+
+/* The layer's own `@source` paths are package-relative (they resolve inside
+   node_modules), so re-scan your content and config for utility classes. */
+@source "../../../content/**/*";
+@source "../../app.config.ts";
+
+@theme static {
+  --color-teal: hsl(189, 53%, 41%);
+  /* … the rest of the scale … */
+}
+
+:root {
+  --ui-primary: var(--color-teal);
+}
+```
+
+The scale name must match `ui.colors.primary` in your `app.config.ts` for Nuxt
+UI to resolve component variants onto it.
+
+### Guardrail tests
+
+Both halves of that contract fail silently, so the layer ships the guards.
+`vitest` is an optional peer dependency, needed only for these.
+
+```ts
+// test/brand-palette-css.test.ts — source-level, no build required
+import { describeBrandPaletteCss } from "@uxfront/layer-docs/test";
+
+describeBrandPaletteCss({
+  entry: new URL("../app/assets/css/main.css", import.meta.url),
+  scale: "teal",
+});
+```
+
+```ts
+// test/brand-palette-compiled.build.test.ts — requires a prior `nuxt build`
+import { describeSingleTailwindPass } from "@uxfront/layer-docs/test";
+
+describeSingleTailwindPass({
+  output: new URL("../.output/public/_nuxt", import.meta.url),
+  scale: "teal",
+});
+```
+
+The first asserts your CSS entry is a Tailwind entry and defines the palette.
+The second reads the built stylesheet and asserts every base utility is emitted
+**exactly once** — catching both a duplicate Tailwind pass (double payload) and
+a CSS entry that never reached the bundle (no base utilities at all). Run it in
+whichever CI job already builds the app; it needs `.output/` on disk.
+
+## Storybook embeds
+
+`StorybookEmbed` renders a deployed Storybook story inside a docs page. Point it
+at your Storybook once, from env — the host is a deployment fact, not a code
+fact, so it lives in runtime config rather than `app.config`:
+
+```bash
+# a single Storybook
+NUXT_PUBLIC_STORYBOOK_BASE_URL="https://storybook.example.com"
+
+# or one per framework — `{framework}` is substituted per embed
+NUXT_PUBLIC_STORYBOOK_BASE_URL="https://{framework}.storybook.example.com"
+```
+
+Then use it from markdown:
+
+```mdc
+:storybook-embed{story="components-actions-button--default"}
+
+:storybook-embed{story="components-actions-button--default" mode="panel"}
+
+:storybook-embed{story="components-actions-button--default" title="Button"}
+```
+
+| Prop        | Default          | Notes                                                                                               |
+| ----------- | ---------------- | --------------------------------------------------------------------------------------------------- |
+| `story`     | —                | Storybook story id, e.g. `components-actions-button--default`.                                      |
+| `framework` | `useFramework()` | Fills `{framework}` in the base URL. Follows the tab by default.                                    |
+| `mode`      | `"preview"`      | `preview` (canvas only) · `full` (manager, no sidebar) · `panel` (manager with the controls panel). |
+| `height`    | mode default     | Number (px) or any CSS length. Set it and auto-height is off.                                       |
+| `title`     | —                | Wraps the embed in `BrowserFrame` with this title.                                                  |
+
+The embed mounts its iframe only once it is 200px from the viewport, keeps the
+Storybook's colour mode in sync with the page's, and grows to fit its story.
+Height is always reserved, so none of that shifts layout.
+
+### The Storybook side
+
+Auto-height and theme sync are a two-way `postMessage` contract, so the
+Storybook has to answer. Install the bridge — it is framework-free and imports
+nothing from Nuxt:
+
+```ts
+// .storybook/preview.ts
+import { installDocsEmbedPreviewBridge } from "@uxfront/layer-docs/storybook";
+
+installDocsEmbedPreviewBridge({ onTheme: (theme) => applyTheme(theme) });
+```
+
+```ts
+// .storybook/manager.ts — only needed for `full` / `panel`
+import { installDocsEmbedManagerBridge } from "@uxfront/layer-docs/storybook";
+
+installDocsEmbedManagerBridge({ onTheme: (theme) => applyTheme(theme) });
+```
+
+Without the bridge the embed still renders; it just holds its default height and
+does not follow the page's colour mode.
+
+### Migrating an existing Storybook
+
+If your Storybook already speaks a branded namespace (`<brand>:theme`,
+`<brand>:height`), name it and both sides accept **and** emit both spellings, so
+the docs site and the Storybook can deploy in either order:
+
+```bash
+NUXT_PUBLIC_STORYBOOK_LEGACY_MESSAGE_NAMESPACE="acme"
+```
+
+Unset it once both sides are on `@uxfront/layer-docs/storybook`.
+
+## OG images
+
+Social share cards are on by default — the layer registers `nuxt-og-image` and
+calls `defineOgImage` from the docs and landing pages, so a consumer that sets up
+the CSS entry above gets branded 1200×630 cards without writing anything. Opt out
+with the module's own switch: `ogImage: { enabled: false }`.
+
+The accent is resolved to a **literal colour at build time** by following
+`--ui-primary` to the `--color-<scale>` value it aliases in your CSS entry.
+Satori — the renderer behind `.satori.vue` templates — has no CSS cascade and no
+custom properties, so `var(--ui-primary)` would render as nothing, and a utility
+class like `text-teal-500` would render Tailwind's teal rather than yours (your
+`@theme` shadows the stock scale name). Override it with a literal if you need
+something other than the brand colour:
+
+```ts
+export default defineAppConfig({
+  ogImage: { accent: "#a78bfa" },
+});
+```
+
+Two pieces of the card are components rather than props, because `defineOgImage`
+serialises its arguments and a Vue slot cannot cross that boundary. Shadow either
+by creating a file at the same path in your own `app/components/`:
+
+| Component                 | Default                             |
+| ------------------------- | ----------------------------------- |
+| `app/AppOgDecoration.vue` | A neutral radial-gradient flourish  |
+| `app/AppOgLogo.vue`       | A text wordmark from `header.title` |
+
+The wordmark is text, not `AppHeaderLogo`: that component renders
+`UColorModeImage`, and satori has neither a colour mode nor a browser to resolve
+relative image paths against. A brand that wants its mark on the card overrides
+`AppOgLogo.vue` with an `<img>` pointing at an **absolute** URL.
+
 ## Compatibility
 
 Pinned to the Nuxt 4 documentation stack (Nuxt 4.4, Nuxt UI 4.8, Content 3.14,

package/app/components/OgImage/OgImageDocs.satori.vue

@@ -0,0 +1,40 @@
+<script lang="ts" setup>
+/**
+ * Default OG card for docs, changelog and landing pages — `defineOgImage("DocsSatori", ...)`.
+ *
+ * Brandable without touching this package: the accent comes from the consumer's
+ * own `--ui-primary` token (resolved in `modules/config.ts`), and both the
+ * decoration and the wordmark are components a consumer can shadow. See
+ * README § OG images.
+ */
+withDefaults(defineProps<{ title?: string; description?: string; headline?: string }>(), {
+  title: "",
+  description: "",
+  headline: "",
+});
+
+const appConfig = useAppConfig();
+const accent = computed(() => appConfig.ogImage?.accent);
+</script>
+
+<template>
+  <div class="w-full h-full flex flex-col justify-center bg-neutral-900">
+    <AppOgDecoration />
+
+    <div class="pl-[100px]">
+      <p
+        v-if="headline"
+        class="uppercase text-[24px] mb-4 font-semibold"
+        :style="{ color: accent }"
+      >
+        {{ headline }}
+      </p>
+      <h1 v-if="title" class="m-0 text-[75px] font-semibold mb-4 text-white flex items-center">
+        <span>{{ title.slice(0, 60) }}</span>
+      </h1>
+      <p v-if="description" class="text-[32px] text-neutral-300 leading-tight w-[700px]">
+        {{ description.slice(0, 200) }}
+      </p>
+    </div>
+  </div>
+</template>

package/app/components/OgImage/OgImageLanding.satori.vue

@@ -0,0 +1,41 @@
+<script lang="ts" setup>
+/**
+ * Centred OG card variant for landing pages — `defineOgImage("LandingSatori", ...)`.
+ *
+ * Same brand contract as {@link OgImageDocs}: accent from the consumer's token,
+ * decoration and wordmark as overridable components.
+ */
+withDefaults(defineProps<{ title?: string; description?: string; headline?: string }>(), {
+  title: "",
+  description: "",
+  headline: "",
+});
+
+const appConfig = useAppConfig();
+const accent = computed(() => appConfig.ogImage?.accent);
+</script>
+
+<template>
+  <div class="w-full h-full flex items-center justify-center bg-neutral-900">
+    <AppOgDecoration />
+
+    <div class="flex flex-col justify-center p-8">
+      <div class="flex justify-center mb-8">
+        <AppOgLogo />
+      </div>
+      <p
+        v-if="headline"
+        class="flex justify-center uppercase text-[24px] mb-4 font-semibold"
+        :style="{ color: accent }"
+      >
+        {{ headline }}
+      </p>
+      <h1 v-if="title" class="flex justify-center m-0 text-5xl font-semibold mb-4 text-white">
+        <span>{{ title.slice(0, 60) }}</span>
+      </h1>
+      <p v-if="description" class="text-center text-2xl text-neutral-300 leading-tight">
+        {{ description.slice(0, 200) }}
+      </p>
+    </div>
+  </div>
+</template>

package/app/components/app/AppOgDecoration.vue

@@ -0,0 +1,27 @@
+<script lang="ts" setup>
+/**
+ * Decorative flourish behind the OG card — the "slot" of the OG templates.
+ *
+ * `defineOgImage(name, props)` serialises its props into the payload, so a real
+ * Vue slot cannot cross that boundary. The Nuxt-native equivalent is app-dir
+ * component precedence: a consumer shadows this file at the same path to supply
+ * its own decoration, or ships an empty template to render nothing. That is the
+ * same override mechanism consumers already use for `DocsAsideLeftBody`.
+ *
+ * Geometry only, no brand mark: a soft radial wash in the top-right corner.
+ * Deliberately not the source SVG blob — satori implements a subset of SVG and
+ * does not apply `filter` / `feGaussianBlur`, so the blurred shape would render
+ * as a hard-edged starburst. A `radial-gradient` background is satori-native
+ * and preserves what the blur was there for.
+ *
+ * Bound rather than written as a `style` attribute so it stays on one line:
+ * satori's gradient parser rejects a value containing newlines, and a formatter
+ * will wrap an attribute this long across lines given the chance.
+ */
+const backgroundImage =
+  "radial-gradient(circle at 75% 15%, rgba(255, 255, 255, 0.28) 0%, rgba(255, 255, 255, 0.1) 35%, rgba(255, 255, 255, 0) 70%)";
+</script>
+
+<template>
+  <div class="absolute right-0 top-0 h-[593px] w-[629px]" :style="{ backgroundImage }" />
+</template>

package/app/components/app/AppOgLogo.vue

@@ -0,0 +1,19 @@
+<script lang="ts" setup>
+/**
+ * Wordmark for the OG card. Overridable at the same path, like
+ * {@link AppOgDecoration}.
+ *
+ * Text, not `AppHeaderLogo`: that component renders `UColorModeImage`, which
+ * needs a colour mode and resolves relative image paths against the browser —
+ * satori has neither, so it needs an absolute URL and no colour mode at all. A
+ * brand that wants its mark here overrides this file with an `<img>` pointing
+ * at an absolute URL; stating that limit rather than half-solving it.
+ */
+const appConfig = useAppConfig();
+</script>
+
+<template>
+  <span class="text-[32px] font-semibold text-white">
+    {{ appConfig.header?.title }}
+  </span>
+</template>

package/app/components/content/StorybookEmbed.vue

@@ -0,0 +1,160 @@
+<script setup lang="ts">
+import { useIntersectionObserver } from "@vueuse/core";
+// Resolved through `#components` rather than imported by path so a consumer
+// that ships its own `BrowserFrame` overrides this one, as with any other
+// component in the layer.
+import { BrowserFrame } from "#components";
+import { docsEmbedMessageNames, readDocsEmbedHeight } from "../../../storybook";
+import {
+  buildStorybookEmbedUrl,
+  STORYBOOK_EMBED_DEFAULT_HEIGHTS,
+  storybookEmbedCssHeight,
+  type StorybookEmbedMode,
+} from "../../utils/storybookEmbed";
+
+/**
+ * Embeds a single story from the consumer's deployed Storybook.
+ *
+ * The Storybook host is a consumer fact, never a layer one: it comes from
+ * `runtimeConfig.public.storybookBaseUrl`, which is empty here and set per
+ * consumer — in `nuxt.config.ts` or, without a rebuild,
+ * `NUXT_PUBLIC_STORYBOOK_BASE_URL`.
+ *
+ * ```md
+ * :storybook-embed{story="components-actions-button--default"}
+ * :storybook-embed{story="components-forms-input--default" mode="panel"}
+ * ```
+ *
+ * Three behaviours are always on, and all three degrade rather than fail:
+ *
+ * - **Lazy mount.** The iframe is not created until the embed comes near the
+ *   viewport, so a page with twenty embeds loads one Storybook, not twenty.
+ * - **Theme sync.** The page's colour mode is posted to the story on load and
+ *   on every change, so an embed never sits light inside a dark page.
+ * - **Auto-height.** The story reports what it needs and the frame follows.
+ *
+ * Theme and height both need `@uxfront/layer-docs/storybook` installed in the
+ * Storybook config. Without it the frame keeps `height` (or the mode's
+ * default) and the story renders in its own theme — degraded, not broken.
+ */
+interface Props {
+  /** Storybook story id, e.g. `components-actions-button--default`. */
+  story: string;
+  /**
+   * Framework substituted into the base URL's `{framework}` placeholder.
+   * Defaults to the reader's selected framework, so an embed inside a
+   * `FrameworkSwitcher` tab needs it and a standalone one does not.
+   */
+  framework?: string;
+  /** Storybook surface to embed. */
+  mode?: StorybookEmbedMode;
+  /**
+   * Fixed height. Set this and auto-height is off — the story's own report is
+   * ignored, which is what you want for a story whose height oscillates.
+   */
+  height?: number | string;
+  /** Caption for the browser frame. Omit to render the story unframed. */
+  title?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  framework: undefined,
+  mode: "preview",
+  height: undefined,
+  title: undefined,
+});
+
+const config = useRuntimeConfig();
+const storybookBaseUrl = computed(() => (config.public.storybookBaseUrl as string) ?? "");
+const messageNames = computed(() =>
+  docsEmbedMessageNames(config.public.storybookLegacyMessageNamespace as string),
+);
+
+const { framework: selectedFramework } = useFramework();
+const framework = computed(() => props.framework ?? selectedFramework.value);
+
+const colorMode = useColorMode();
+const containerRef = useTemplateRef<HTMLElement>("container");
+const iframeRef = useTemplateRef<HTMLIFrameElement>("iframe");
+
+// Mount the iframe just before it is scrolled to, then stop observing — the
+// answer cannot change back.
+const visible = ref(false);
+const { stop } = useIntersectionObserver(
+  containerRef,
+  ([entry]) => {
+    if (!entry?.isIntersecting) return;
+    visible.value = true;
+    stop();
+  },
+  { rootMargin: "200px" },
+);
+
+const src = computed(() =>
+  buildStorybookEmbedUrl({
+    template: storybookBaseUrl.value,
+    story: props.story,
+    framework: framework.value,
+    mode: props.mode,
+  }),
+);
+
+const reportedHeight = ref<number | null>(null);
+const cssHeight = computed(() =>
+  storybookEmbedCssHeight(
+    props.height ?? reportedHeight.value ?? STORYBOOK_EMBED_DEFAULT_HEIGHTS[props.mode],
+  ),
+);
+
+// An iframe is an unlabelled frame to a screen reader. The caption names it
+// when there is one; otherwise say what it holds rather than leaving it silent.
+const frameTitle = computed(
+  () => props.title ?? `Storybook preview: ${props.story.replace(/-+/g, " ")}`,
+);
+
+const wrapper = computed(() => (props.title ? BrowserFrame : "div"));
+const wrapperProps = computed(() => (props.title ? { title: props.title } : {}));
+
+function sendTheme() {
+  const target = iframeRef.value?.contentWindow;
+  if (!target) return;
+
+  const theme = colorMode.value === "dark" ? "dark" : "light";
+  for (const type of messageNames.value.theme) {
+    target.postMessage({ type, theme }, "*");
+  }
+}
+
+function onMessage(event: MessageEvent) {
+  // Scope by source, not by origin: the Storybook host is consumer-configured
+  // and may differ per framework, but only one window can be this iframe.
+  if (event.source !== iframeRef.value?.contentWindow) return;
+
+  const height = readDocsEmbedHeight(event.data, messageNames.value.height);
+  if (height !== null) reportedHeight.value = height;
+}
+
+onMounted(() => window.addEventListener("message", onMessage));
+onUnmounted(() => window.removeEventListener("message", onMessage));
+
+watch(() => colorMode.value, sendTheme);
+</script>
+
+<template>
+  <component :is="wrapper" v-bind="wrapperProps">
+    <div
+      ref="container"
+      class="storybook-embed border border-default rounded overflow-hidden min-h-25 resize-y transition-[height] duration-150 ease-out motion-reduce:transition-none"
+      :style="{ height: cssHeight }"
+    >
+      <iframe
+        v-if="visible"
+        ref="iframe"
+        :src="src"
+        :title="frameTitle"
+        class="block w-full h-full border-0"
+        @load="sendTheme"
+      />
+    </div>
+  </component>
+</template>

package/app/pages/[[lang]]/[...slug].vue

@@ -35,11 +35,21 @@ useSeoMeta({
   ogDescription: description,
 });
 
+const appConfig = useAppConfig();
+
+// An explicit `seo.ogImage` in the page's front matter wins; otherwise the card
+// is generated from the shared template.
 if (page.value?.seo?.ogImage) {
   useSeoMeta({
     ogImage: page.value.seo.ogImage,
     twitterImage: page.value.seo.ogImage,
   });
+} else {
+  defineOgImage("DocsSatori", {
+    headline: appConfig.header?.title,
+    title,
+    description,
+  });
 }
 </script>
 

package/app/pages/[[lang]]/docs/[section]/[...slug].vue

@@ -83,6 +83,12 @@ watch(
   },
 );
 
+defineOgImage("DocsSatori", {
+  headline: headline.value,
+  title,
+  description,
+});
+
 const github = computed(() => (appConfig.github ? appConfig.github : null));
 
 const editLink = computed(() => {