From e71609685931cf37ae43e8bac8f2f3d2394e4ff2 Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Fri, 24 Jul 2026 19:18:05 +0700
Subject: [PATCH] =?UTF-8?q?Render=20BFM=20embeds=20across=20the=20full=20f?=
 =?UTF-8?q?ormat=20=C3=97=20placement=20matrix?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Embedding a card or file in a markdown field only rendered correctly for
the default format+placement combos. `isolated` collapsed to nothing (its
default template lays out at height: 100%), inline `embedded` collapsed in
a shrink-wrapping inline-block, and non-default combos were unverified.

Add a shared `bfmResolvedEmbedStyle(format, kind, fittedSizeStyle)` helper
that hands every non-atom resolved embed a definite footprint so it can no
longer collapse: inline embedded 16rem×9.375rem, inline isolated
24rem×18.75rem, block isolated a growable `min-height: 18.75rem`, and fitted
its requested dimensions plus `overflow: hidden`. Apply it in all four
render surfaces — the saved MarkdownTemplate, the operator-mode preview
panel, the CodeMirror source editor, and the embed chooser preview (which
previously carried its own copy of this logic) — so footprints stay in
lockstep everywhere.

Plain `MarkdownField` (a StringField) has no relationship to resolve embeds,
so its directives stay unresolved by design; documented at the class.

Cover the full card and file × {atom, embedded, fitted, isolated} ×
{inline, block} matrix on the saved render path, plus a unit test for the
helper and updated CodeMirror-editor footprint assertions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/base/card-api.gts                    |   8 ++
 packages/base/default-templates/markdown.gts  |  17 +--
 .../markdown-embed-chooser/preview/index.gts  |  36 ++---
 .../preview-panel/rendered-markdown.gts       |  17 +--
 packages/host/app/lib/codemirror-context.ts   |  13 +-
 .../acceptance/markdown-file-def-test.gts     |  52 +++++++
 .../components/codemirror-editor-test.gts     |  42 +++++-
 .../components/rich-markdown-field-test.gts   | 127 ++++++++++++++++++
 .../tests/unit/bfm-card-references-test.ts    |  55 ++++++++
 .../runtime-common/bfm-card-references.ts     |  49 +++++++
 10 files changed, 365 insertions(+), 51 deletions(-)

diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
index 5adccbb7efe..cdbff4f60fd 100644
--- a/packages/base/card-api.gts
+++ b/packages/base/card-api.gts
@@ -2913,6 +2913,14 @@ export class CSSField extends TextAreaField {
   };
 }
 
+// A plain markdown StringField. BFM embed directives (`:card[…]` / `:file[…]`)
+// in its content render as (correctly-sized) broken-link placeholders and do
+// NOT resolve: a StringField is a bare string with no `id` to resolve relative
+// refs against, no `linksToMany` storage to hold resolved instances, and no
+// query to populate them at index time. Resolution is an index-time
+// relationship concern — use `RichMarkdownField` (or a `.md` `MarkdownDef`
+// file), which own the `linkedCards`/`linkedFiles` relationships, when embeds
+// must render live.
 export class MarkdownField extends StringField {
   static displayName = 'Markdown';
   static icon = MarkdownIcon;
diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 8a65f1c3ff2..2ae8f5be44d 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -10,6 +10,7 @@ import LinkOffIcon from '@cardstack/boxel-icons/link-off';
 
 import {
   bfmRefFormatAndSize,
+  bfmResolvedEmbedStyle,
   buildWaiter,
   cardTypeName,
   fileNameFromUrl,
@@ -271,14 +272,14 @@ export default class MarkDownTemplate extends GlimmerComponent<{
           let format: CardSlotFormat = derived.format;
           let sizeStyle: string | undefined = derived.sizeStyle;
 
-          // Fitted slots carry an inline width/height plus `overflow: hidden`
-          // so the resolved instance occupies the requested footprint.
-          let resolvedStyle: ReturnType<typeof htmlSafe> | undefined;
-          if (format === 'fitted') {
-            resolvedStyle = htmlSafe(
-              sizeStyle ? `${sizeStyle}; overflow: hidden` : 'overflow: hidden',
-            );
-          }
+          // Non-atom resolved slots carry a footprint so the instance occupies
+          // a definite box instead of collapsing (isolated/inline-embedded
+          // default templates lay out at 100%). Fitted uses its requested
+          // dimensions; embedded/isolated get shared defaults. Same helper as
+          // the other render surfaces so footprints stay in lockstep.
+          let resolvedStyleRaw = bfmResolvedEmbedStyle(format, kind, sizeStyle);
+          let resolvedStyle: ReturnType<typeof htmlSafe> | undefined =
+            resolvedStyleRaw ? htmlSafe(resolvedStyleRaw) : undefined;
 
           let resolvedUrl = resolveUrl(rawUrl, baseUrl);
 
diff --git a/packages/host/app/components/markdown-embed-chooser/preview/index.gts b/packages/host/app/components/markdown-embed-chooser/preview/index.gts
index 07cf88bdd32..ba2c99fba07 100644
--- a/packages/host/app/components/markdown-embed-chooser/preview/index.gts
+++ b/packages/host/app/components/markdown-embed-chooser/preview/index.gts
@@ -13,6 +13,7 @@ import { eq, not } from '@cardstack/boxel-ui/helpers';
 
 import {
   bfmRefFormatAndSize,
+  bfmResolvedEmbedStyle,
   type BfmSizeSpec,
 } from '@cardstack/runtime-common/bfm-card-references';
 
@@ -266,38 +267,25 @@ export default class MarkdownEmbedPreview extends Component<Signature> {
     return sizeStyle ? htmlSafe(sizeStyle) : undefined;
   }
 
-  // Fitted slots carry an inline width/height plus `overflow: hidden` so the
-  // instance occupies the requested footprint — derived through the same helper
-  // the live markdown renderer uses (`rendered-markdown.gts`). Inline embedded
-  // and isolated have no intrinsic inline width: the default template's
-  // `width/height: 100%` resolves against the inline-block wrapper, which is
-  // itself shrink-wrapping, and the box collapses. Give the wrapper a definite
-  // footprint that matches the live renderer's loading placeholders so the
-  // preview shows a real card body.
+  // Resolved-embed footprint, shared with the live markdown render surfaces
+  // (saved `MarkdownTemplate`, host preview panel, CodeMirror editor) through
+  // `bfmResolvedEmbedStyle`. Isolated and inline embedded have no intrinsic
+  // inline width — their default `width/height: 100%` resolves against a
+  // shrink-wrapping wrapper and the box collapses — so the helper hands back a
+  // definite footprint that matches the live renderers' loading placeholders.
   private get sizeStyle(): ReturnType<typeof htmlSafe> | undefined {
     let { format } = this.args;
+    let fittedSizeStyle: string | undefined;
     if (format === 'fitted') {
       let { width, height } = this.args.sizeSpec ?? { format: 'fitted' };
-      let { sizeStyle } = bfmRefFormatAndSize(
+      fittedSizeStyle = bfmRefFormatAndSize(
         'fitted',
         width === undefined ? undefined : String(width),
         height === undefined ? undefined : String(height),
-      );
-      return htmlSafe(
-        sizeStyle ? `${sizeStyle}; overflow: hidden` : 'overflow: hidden',
-      );
+      ).sizeStyle;
     }
-    if (
-      this.kind === 'inline' &&
-      (format === 'embedded' || format === 'isolated')
-    ) {
-      let footprint =
-        format === 'isolated'
-          ? 'width: 24rem; height: 18.75rem'
-          : 'width: 16rem; height: 9.375rem';
-      return htmlSafe(`${footprint}; overflow: hidden`);
-    }
-    return undefined;
+    let style = bfmResolvedEmbedStyle(format, this.kind, fittedSizeStyle);
+    return style ? htmlSafe(style) : undefined;
   }
 
   <template>
diff --git a/packages/host/app/components/operator-mode/preview-panel/rendered-markdown.gts b/packages/host/app/components/operator-mode/preview-panel/rendered-markdown.gts
index ad0932a0904..46e92a5360f 100644
--- a/packages/host/app/components/operator-mode/preview-panel/rendered-markdown.gts
+++ b/packages/host/app/components/operator-mode/preview-panel/rendered-markdown.gts
@@ -23,6 +23,7 @@ import { eq } from '@cardstack/boxel-ui/helpers';
 
 import {
   bfmRefFormatAndSize,
+  bfmResolvedEmbedStyle,
   CardContextName,
   cardTypeName,
   extractCardReferenceUrls,
@@ -271,14 +272,14 @@ export default class RenderedMarkdown extends Component<Signature> {
           let format: CardSlotFormat = derived.format;
           let sizeStyle: string | undefined = derived.sizeStyle;
 
-          // Fitted slots carry an inline width/height plus `overflow: hidden`
-          // so the resolved instance occupies the requested footprint.
-          let resolvedStyle: ReturnType<typeof htmlSafe> | undefined;
-          if (format === 'fitted') {
-            resolvedStyle = htmlSafe(
-              sizeStyle ? `${sizeStyle}; overflow: hidden` : 'overflow: hidden',
-            );
-          }
+          // Non-atom resolved slots carry a footprint so the instance occupies
+          // a definite box instead of collapsing (isolated/inline-embedded
+          // default templates lay out at 100%). Fitted uses its requested
+          // dimensions; embedded/isolated get shared defaults. Same helper as
+          // the other render surfaces so footprints stay in lockstep.
+          let resolvedStyleRaw = bfmResolvedEmbedStyle(format, kind, sizeStyle);
+          let resolvedStyle: ReturnType<typeof htmlSafe> | undefined =
+            resolvedStyleRaw ? htmlSafe(resolvedStyleRaw) : undefined;
 
           let resolvedUrl = resolveUrl(rawUrl, baseUrl);
 
diff --git a/packages/host/app/lib/codemirror-context.ts b/packages/host/app/lib/codemirror-context.ts
index 329fc513d23..dc6b1bb2aee 100644
--- a/packages/host/app/lib/codemirror-context.ts
+++ b/packages/host/app/lib/codemirror-context.ts
@@ -48,6 +48,7 @@ import {
   type BfmRefFormat,
   type BfmRefRange,
   bfmRefFormatAndSize,
+  bfmResolvedEmbedStyle,
   extractBfmRefRanges,
   parseBfmSizeSpec,
 } from '@cardstack/runtime-common/bfm-card-references';
@@ -941,14 +942,10 @@ function createCardTargetNotifier(
                 el.getAttribute('data-boxel-bfm-height') ?? undefined,
                 kind === 'inline' ? 'atom' : 'embedded',
               );
-              // Fitted slots carry the width/height plus `overflow: hidden` so
-              // the resolved instance occupies the requested footprint.
-              let style =
-                format === 'fitted'
-                  ? sizeStyle
-                    ? `${sizeStyle}; overflow: hidden`
-                    : 'overflow: hidden'
-                  : undefined;
+              // Non-atom slots carry a footprint so the resolved instance
+              // occupies a definite box instead of collapsing. Same helper as
+              // the saved/preview renderers so footprints stay in lockstep.
+              let style = bfmResolvedEmbedStyle(format, kind, sizeStyle);
               targets.push({
                 element: el as HTMLElement,
                 cardId,
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 164a4a77cc8..402adfd9428 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -324,6 +324,29 @@ module('Acceptance | markdown BFM card references', function (hooks) {
             '',
             '::file[https://nonexistent.example/gone.pdf]',
           ].join('\n'),
+          // A plain markdown target embedded across the full format matrix.
+          // MarkdownDef defines atom/embedded/fitted/isolated, so each combo
+          // renders a distinct `data-test-markdown-*` hook.
+          'documents/target.md': ['# Target Doc', '', 'Body text.'].join('\n'),
+          'bfm-file-matrix.md': [
+            '# BFM File Matrix',
+            '',
+            `:file[${testRealmURL}documents/target.md | atom]`,
+            '',
+            `:file[${testRealmURL}documents/target.md | embedded]`,
+            '',
+            `:file[${testRealmURL}documents/target.md | fitted w:200 h:150]`,
+            '',
+            `:file[${testRealmURL}documents/target.md | isolated]`,
+            '',
+            `::file[${testRealmURL}documents/target.md | atom]`,
+            '',
+            `::file[${testRealmURL}documents/target.md | embedded]`,
+            '',
+            `::file[${testRealmURL}documents/target.md | fitted w:200 h:150]`,
+            '',
+            `::file[${testRealmURL}documents/target.md | isolated]`,
+          ].join('\n'),
           'mermaid-test.md': [
             '# Mermaid Test',
             '',
@@ -472,6 +495,35 @@ module('Acceptance | markdown BFM card references', function (hooks) {
       );
   });
 
+  test('every file format renders in both inline and block placement', async function (assert) {
+    // CS-12320: the file half of the resolved-render matrix. Each format ×
+    // placement must render the referenced markdown file in the requested
+    // format — isolated must not collapse.
+    await visitOperatorMode({
+      submode: 'code',
+      codePath: `${testRealmURL}bfm-file-matrix.md`,
+    });
+    await settled();
+
+    for (let [placement, wrapper] of [
+      ['inline', '[data-test-markdown-bfm-inline-file]'],
+      ['block', '[data-test-markdown-bfm-block-file]'],
+    ] as const) {
+      for (let format of ['atom', 'embedded', 'fitted', 'isolated'] as const) {
+        assert
+          .dom(`${wrapper} [data-test-markdown-${format}]`)
+          .exists(`${format} file renders in ${placement} placement`);
+      }
+    }
+
+    assert
+      .dom('[data-test-markdown-bfm-unresolved-inline]')
+      .doesNotExist('no unresolved inline file placeholders remain');
+    assert
+      .dom('[data-test-markdown-bfm-unresolved-block]')
+      .doesNotExist('no unresolved block file placeholders remain');
+  });
+
   test('shows fallback for unresolvable file references', async function (assert) {
     await visitOperatorMode({
       submode: 'code',
diff --git a/packages/host/tests/integration/components/codemirror-editor-test.gts b/packages/host/tests/integration/components/codemirror-editor-test.gts
index a4e0c054686..cd2a05dd6f1 100644
--- a/packages/host/tests/integration/components/codemirror-editor-test.gts
+++ b/packages/host/tests/integration/components/codemirror-editor-test.gts
@@ -515,14 +515,45 @@ module('Integration | codemirror-context', function (hooks) {
     }
   });
 
-  test('block isolated embed threads isolated format with no size style', async function (assert) {
+  test('block isolated embed threads isolated format with a growable footprint', async function (assert) {
     let { targets, destroy } = await collectTargets(
       '::card[https://example.com/cards/1 | isolated]',
     );
     try {
       let target = targets.find((t) => t.kind === 'block');
       assert.strictEqual(target?.format, 'isolated', 'format is isolated');
-      assert.notOk(target?.style, 'isolated embed has no inline size style');
+      // CS-12320: block isolated gets a growable min-height so it does not
+      // collapse (its default template lays out at height: 100%).
+      assert.strictEqual(
+        target?.style,
+        'min-height: 18.75rem',
+        'isolated embed carries a growable min-height footprint',
+      );
+    } finally {
+      destroy();
+    }
+  });
+
+  test('inline isolated / embedded embeds carry a definite footprint', async function (assert) {
+    // CS-12320: inline isolated/embedded collapse without a definite width +
+    // height (the default template lays out at 100% inside a shrink-wrapping
+    // inline-block wrapper).
+    let { targets, destroy } = await collectTargets(
+      ':card[https://example.com/cards/1 | isolated] and :card[https://example.com/cards/2 | embedded]',
+    );
+    try {
+      let isolated = targets.find((t) => t.format === 'isolated');
+      assert.strictEqual(
+        isolated?.style,
+        'width: 24rem; height: 18.75rem; overflow: hidden',
+        'inline isolated carries the shared footprint',
+      );
+      let embedded = targets.find((t) => t.format === 'embedded');
+      assert.strictEqual(
+        embedded?.style,
+        'width: 16rem; height: 9.375rem; overflow: hidden',
+        'inline embedded carries the shared footprint',
+      );
     } finally {
       destroy();
     }
@@ -573,7 +604,12 @@ module('Integration | codemirror-context', function (hooks) {
         (t) => t.refType === 'file' && t.format === 'isolated',
       );
       assert.ok(isolated, 'isolated file target is present');
-      assert.notOk(isolated?.style, 'isolated file target has no size style');
+      // CS-12320: block isolated gets a growable min-height footprint.
+      assert.strictEqual(
+        isolated?.style,
+        'min-height: 18.75rem',
+        'isolated file target carries a growable min-height footprint',
+      );
     } finally {
       destroy();
     }
diff --git a/packages/host/tests/integration/components/rich-markdown-field-test.gts b/packages/host/tests/integration/components/rich-markdown-field-test.gts
index 32358d6dd52..3d4b9a49c8b 100644
--- a/packages/host/tests/integration/components/rich-markdown-field-test.gts
+++ b/packages/host/tests/integration/components/rich-markdown-field-test.gts
@@ -502,6 +502,133 @@ module('Integration | RichMarkdownField', function (hooks) {
       .doesNotExist('no unresolved Pill remains after card resolves (block)');
   });
 
+  test('every card format renders in both inline and block placement (saved MarkdownTemplate path)', async function (assert) {
+    // CS-12320: the resolved-render matrix. Each format × placement must render
+    // the referenced card in the requested format — not collapse (isolated) or
+    // fall back. Exercises the saved MarkdownTemplate render path (not the
+    // CodeMirror compose preview).
+    class Pet extends CardDef {
+      static displayName = 'Pet';
+      @field name = contains(StringField);
+      @field cardTitle = contains(StringField, {
+        computeVia: function (this: Pet) {
+          return this.name;
+        },
+      });
+      static atom = class Atom extends Component<typeof this> {
+        <template>
+          <span data-test-pet-atom>{{@model.name}}</span>
+        </template>
+      };
+      static embedded = class Embedded extends Component<typeof this> {
+        <template>
+          <div data-test-pet-embedded>{{@model.name}}</div>
+        </template>
+      };
+      static fitted = class Fitted extends Component<typeof this> {
+        <template>
+          <div data-test-pet-fitted>{{@model.name}}</div>
+        </template>
+      };
+      static isolated = class Isolated extends Component<typeof this> {
+        <template>
+          <div data-test-pet-isolated>{{@model.name}}</div>
+        </template>
+      };
+    }
+
+    class ArticleCard extends CardDef {
+      @field body = contains(RichMarkdownField);
+      static isolated = class Isolated extends Component<typeof this> {
+        <template><@fields.body /></template>
+      };
+    }
+
+    let url = `${testRealmURL}Pet/mango`;
+    let content = [
+      `:card[${url} | atom]`,
+      `:card[${url} | embedded]`,
+      `:card[${url} | fitted w:200 h:150]`,
+      `:card[${url} | isolated]`,
+      `::card[${url} | atom]`,
+      `::card[${url} | embedded]`,
+      `::card[${url} | fitted w:200 h:150]`,
+      `::card[${url} | isolated]`,
+    ].join('\n\n');
+
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'pet.gts': { Pet },
+        'article.gts': { ArticleCard },
+        'Pet/mango.json': {
+          data: {
+            attributes: { name: 'Mango', cardTitle: 'Mango' },
+            meta: { adoptsFrom: { module: '../pet', name: 'Pet' } },
+          },
+        },
+        'article-1.json': {
+          data: {
+            attributes: { body: { content } },
+            meta: { adoptsFrom: { module: './article', name: 'ArticleCard' } },
+          },
+        },
+      },
+    });
+
+    let store = getService('store');
+    let article = (await store.get(`${testRealmURL}article-1`)) as BaseDef;
+    await store.loaded();
+
+    await renderCard(loader, article, 'isolated');
+    await waitFor('[data-test-pet-isolated]', { timeout: 10_000 });
+
+    let inline = '[data-test-markdown-bfm-inline-card]';
+    let block = '[data-test-markdown-bfm-block-card]';
+    for (let [placement, wrapper] of [
+      ['inline', inline],
+      ['block', block],
+    ] as const) {
+      for (let format of ['atom', 'embedded', 'fitted', 'isolated'] as const) {
+        assert
+          .dom(`${wrapper} [data-test-pet-${format}]`)
+          .exists(`${format} card renders in ${placement} placement`);
+      }
+    }
+
+    // The bug this ticket fixes: isolated (and inline embedded) collapse
+    // without a definite footprint. Spot-check that the shared footprint
+    // reached the resolved slot.
+    assert
+      .dom(`${inline}:has([data-test-pet-isolated])`)
+      .hasAttribute(
+        'style',
+        /width: 24rem/,
+        'inline isolated slot carries the shared footprint',
+      );
+    assert
+      .dom(`${block}:has([data-test-pet-isolated])`)
+      .hasAttribute(
+        'style',
+        /min-height: 18\.75rem/,
+        'block isolated slot carries a growable min-height',
+      );
+    assert
+      .dom(`${inline}:has([data-test-pet-embedded])`)
+      .hasAttribute(
+        'style',
+        /width: 16rem/,
+        'inline embedded slot carries the shared footprint',
+      );
+
+    assert
+      .dom('[data-test-markdown-bfm-unresolved-inline]')
+      .doesNotExist('no unresolved inline placeholders remain');
+    assert
+      .dom('[data-test-markdown-bfm-unresolved-block]')
+      .doesNotExist('no unresolved block placeholders remain');
+  });
+
   test('compose preview resolves a relative card ref against a prefix-form base', async function (assert) {
     // Regression guard for the compose/edit path: when the realm is
     // prefix-mapped the editor's reference base is a prefix-form RRI, and a
diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 485fa663a65..b8c83769a01 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -8,6 +8,7 @@ import {
   extractBfmReferences,
   extractBfmRefRanges,
   bfmRefFormatAndSize,
+  bfmResolvedEmbedStyle,
   bfmCardReferenceExtensions,
   bfmExtensionsForKeyword,
   parseBfmSizeSpec,
@@ -1047,6 +1048,60 @@ module('Unit | bfm-card-references', function () {
     });
   });
 
+  module('bfmResolvedEmbedStyle', function () {
+    test('atom has no footprint in either placement', function (assert) {
+      assert.strictEqual(bfmResolvedEmbedStyle('atom', 'inline'), undefined);
+      assert.strictEqual(bfmResolvedEmbedStyle('atom', 'block'), undefined);
+    });
+
+    test('inline embedded gets a definite footprint so it does not collapse', function (assert) {
+      assert.strictEqual(
+        bfmResolvedEmbedStyle('embedded', 'inline'),
+        'width: 16rem; height: 9.375rem; overflow: hidden',
+      );
+    });
+
+    test('block embedded flows naturally (no footprint)', function (assert) {
+      assert.strictEqual(bfmResolvedEmbedStyle('embedded', 'block'), undefined);
+    });
+
+    test('inline isolated gets a definite footprint so it does not collapse', function (assert) {
+      assert.strictEqual(
+        bfmResolvedEmbedStyle('isolated', 'inline'),
+        'width: 24rem; height: 18.75rem; overflow: hidden',
+      );
+    });
+
+    test('block isolated gets a growable min-height so it does not collapse', function (assert) {
+      assert.strictEqual(
+        bfmResolvedEmbedStyle('isolated', 'block'),
+        'min-height: 18.75rem',
+      );
+    });
+
+    test('fitted with dimensions carries them plus overflow clipping', function (assert) {
+      assert.strictEqual(
+        bfmResolvedEmbedStyle('fitted', 'block', 'width: 400px; height: 300px'),
+        'width: 400px; height: 300px; overflow: hidden',
+      );
+      assert.strictEqual(
+        bfmResolvedEmbedStyle(
+          'fitted',
+          'inline',
+          'width: 400px; height: 300px',
+        ),
+        'width: 400px; height: 300px; overflow: hidden',
+      );
+    });
+
+    test('fitted without dimensions still clips overflow', function (assert) {
+      assert.strictEqual(
+        bfmResolvedEmbedStyle('fitted', 'block'),
+        'overflow: hidden',
+      );
+    });
+  });
+
   module('serializeBfmSizeSpec', function () {
     test('atom / isolated / embedded round-trip to their keyword', function (assert) {
       assert.strictEqual(serializeBfmSizeSpec({ format: 'atom' }), 'atom');
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
index 31658312265..53008509f67 100644
--- a/packages/runtime-common/bfm-card-references.ts
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -237,6 +237,55 @@ export function bfmRefFormatAndSize(
   return { format, sizeStyle: parts.length ? parts.join('; ') : undefined };
 }
 
+/**
+ * Inline style for a *resolved* BFM embed slot so `isolated` / `embedded` /
+ * `fitted` occupy a definite footprint instead of collapsing to zero.
+ *
+ * The default `isolated` and (inline) `embedded` card/file templates lay out
+ * with `width`/`height: 100%`, which resolves against a shrink-wrapping
+ * inline-block — or an unbounded block — and collapses. Every render surface
+ * (the saved `MarkdownTemplate`, the host preview panel, the CodeMirror source
+ * editor, and the embed chooser preview) shares this helper so a resolved
+ * embed occupies the same footprint everywhere, matching the loading/broken
+ * placeholders.
+ *
+ * `fittedSizeStyle` is the `width`/`height` string that `bfmRefFormatAndSize`
+ * derives for a fitted spec; it is ignored for the other formats.
+ *
+ * Footprints:
+ *  - `atom`                 — none (intrinsic pill).
+ *  - `fitted`               — the requested dimensions + `overflow: hidden`.
+ *  - inline `embedded`      — 16rem × 9.375rem (matches `--embedded` placeholder height).
+ *  - inline `isolated`      — 24rem × 18.75rem (matches `--isolated` placeholder height).
+ *  - block `embedded`       — none (flows naturally at full width).
+ *  - block `isolated`       — `min-height: 18.75rem`, growable (matches `--isolated` placeholder).
+ */
+export function bfmResolvedEmbedStyle(
+  format: BfmRefFormat,
+  kind: 'inline' | 'block',
+  fittedSizeStyle?: string,
+): string | undefined {
+  if (format === 'fitted') {
+    return fittedSizeStyle
+      ? `${fittedSizeStyle}; overflow: hidden`
+      : 'overflow: hidden';
+  }
+  if (kind === 'inline') {
+    if (format === 'embedded') {
+      return 'width: 16rem; height: 9.375rem; overflow: hidden';
+    }
+    if (format === 'isolated') {
+      return 'width: 24rem; height: 18.75rem; overflow: hidden';
+    }
+    return undefined; // inline atom
+  }
+  // block placement
+  if (format === 'isolated') {
+    return 'min-height: 18.75rem';
+  }
+  return undefined; // block atom / block embedded flow naturally
+}
+
 /**
  * Builds the `data-boxel-bfm-format` / `-width` / `-height` attribute string
  * for a BFM size specifier (the part after `|`). Returns `''` when there is no