@uxfront/layer-docs 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @uxfront/layer-docs
 
+## 0.4.1
+
+### Patch Changes
+
+- Republish the `0.4.0` code through automated release tooling. No code changes.
+
+  `0.4.0` and every version before it were published by hand from a maintainer's machine. Nothing linked a version on the registry back to the commit it was built from, and the release depended on a long-lived npm token.
+
+  `0.4.1` is the first version published from CI, by Changesets, over npm trusted publishing. No npm token takes part: the registry credential is minted for each run from a GitHub OIDC token. Every shipped file is byte-identical to `0.4.0` except this changelog entry and the `version` field.
+
+  This release carries **no provenance attestation**. npm does not generate provenance for a package built from a private source repository, and `uxfront` is private. Provenance becomes available if the repository becomes public. It is not a property of this version.
+
+## 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

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
 
@@ -134,6 +135,112 @@ The second reads the built stylesheet and asserts every base utility is emitted
 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(() => {

package/app/utils/storybookEmbed.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildStorybookEmbedUrl,
+  resolveStorybookBaseUrl,
+  STORYBOOK_EMBED_DEFAULT_HEIGHTS,
+  storybookEmbedCssHeight,
+} from "./storybookEmbed";
+
+const TEMPLATE = "https://{framework}.storybook.example.com";
+const STORY = "components-actions-button--default";
+
+describe("resolveStorybookBaseUrl", () => {
+  it("substitutes every occurrence of the framework placeholder", () => {
+    expect(resolveStorybookBaseUrl("https://{framework}.example.com/{framework}", "vue")).toBe(
+      "https://vue.example.com/vue",
+    );
+  });
+
+  it("passes a template without a placeholder through, for a single Storybook", () => {
+    expect(resolveStorybookBaseUrl("https://storybook.example.com", "vue")).toBe(
+      "https://storybook.example.com",
+    );
+  });
+
+  it("trims trailing slashes so the built URL never doubles them", () => {
+    expect(resolveStorybookBaseUrl("https://storybook.example.com//")).toBe(
+      "https://storybook.example.com",
+    );
+  });
+});
+
+describe("buildStorybookEmbedUrl", () => {
+  it("addresses the preview surface by default and marks itself as a direct embed", () => {
+    expect(buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue" })).toBe(
+      `https://vue.storybook.example.com/iframe.html?id=${STORY}&viewMode=story&docsEmbed=1`,
+    );
+  });
+
+  // `full` and `panel` reproduce the manager URLs the migrating docs site
+  // already ships; a changed parameter here is a changed rendering there.
+  it("addresses the manager in full mode", () => {
+    expect(
+      buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue", mode: "full" }),
+    ).toBe(
+      `https://vue.storybook.example.com/?path=/story/${STORY}&full=1&shortcuts=false&singleStory=true`,
+    );
+  });
+
+  it("addresses the manager with its addon panel in panel mode", () => {
+    expect(
+      buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, framework: "vue", mode: "panel" }),
+    ).toBe(
+      `https://vue.storybook.example.com/?path=/story/${STORY}&shortcuts=false&singleStory=true`,
+    );
+  });
+
+  it("only marks the preview surface — a manager embed is relayed, not direct", () => {
+    for (const mode of ["full", "panel"] as const) {
+      expect(buildStorybookEmbedUrl({ template: TEMPLATE, story: STORY, mode })).not.toContain(
+        "docsEmbed",
+      );
+    }
+  });
+
+  it("encodes the story id rather than splicing it into the query raw", () => {
+    expect(
+      buildStorybookEmbedUrl({ template: "https://sb.example.com", story: "a&b=c" }),
+    ).toContain("id=a%26b%3Dc&");
+  });
+
+  it("degrades to a same-origin URL when no consumer configured a host", () => {
+    expect(buildStorybookEmbedUrl({ template: "", story: STORY })).toBe(
+      `/iframe.html?id=${STORY}&viewMode=story&docsEmbed=1`,
+    );
+  });
+});
+
+describe("STORYBOOK_EMBED_DEFAULT_HEIGHTS", () => {
+  // Reserved before the story reports anything — the space that keeps the embed
+  // from shifting the page. Panel carries the addon panel on top of the story.
+  it("reserves more room for the panel surface than the bare story", () => {
+    expect(STORYBOOK_EMBED_DEFAULT_HEIGHTS).toEqual({ preview: 320, full: 320, panel: 600 });
+  });
+});
+
+describe("storybookEmbedCssHeight", () => {
+  it("reads a bare number as pixels, in either type markdown may deliver", () => {
+    expect(storybookEmbedCssHeight(420)).toBe("420px");
+    expect(storybookEmbedCssHeight("420")).toBe("420px");
+    expect(storybookEmbedCssHeight(" 420 ")).toBe("420px");
+  });
+
+  it("passes a CSS length through untouched", () => {
+    expect(storybookEmbedCssHeight("30rem")).toBe("30rem");
+    expect(storybookEmbedCssHeight("420px")).toBe("420px");
+    expect(storybookEmbedCssHeight("min(80vh, 600px)")).toBe("min(80vh, 600px)");
+  });
+});