From dfd15ba5153a5334d7ae4c44d8f24f7a9a6f48d7 Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Fri, 26 Jun 2026 15:18:15 +0700
Subject: [PATCH 01/12] =?UTF-8?q?Add=20MarkdownEmbedChooserModal=20?=
 =?UTF-8?q?=E2=80=94=20combined=20card/file=20chooser=20(CS-11675)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A tabbed modal that wraps the existing mini choosers and the
MarkdownEmbedPreviewPane from #5303. Both tabs stay mounted so each tab's
search query, highlighted row, scroll position, and pane W×H survive a
switch. Driven by a new `markdown-embed-chooser` service exposing
`chooseCardOrFile({ defaultTab })` (edit-mode `editEmbed` follows in
CS-11676). Pane teach: render with `@target` undefined so layout doesn't
jump before a row is picked, CTA disabled until then.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ...11677-markdown-embed-chooser-modal-plan.md | 152 +++++++++++
 .../markdown-embed-chooser/modal.gts          | 125 +++++++++
 .../markdown-embed-chooser/pane.gts           |  52 +++-
 .../markdown-embed-chooser/tab-panel.gts      | 119 +++++++++
 .../markdown-embed-chooser/tabs.gts           | 130 ++++++++++
 .../components/operator-mode/container.gts    |   2 +
 .../app/services/markdown-embed-chooser.ts    |  87 +++++++
 .../markdown-embed-chooser-modal-test.gts     | 245 ++++++++++++++++++
 8 files changed, 901 insertions(+), 11 deletions(-)
 create mode 100644 docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md
 create mode 100644 packages/host/app/components/markdown-embed-chooser/modal.gts
 create mode 100644 packages/host/app/components/markdown-embed-chooser/tab-panel.gts
 create mode 100644 packages/host/app/components/markdown-embed-chooser/tabs.gts
 create mode 100644 packages/host/app/services/markdown-embed-chooser.ts
 create mode 100644 packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts

diff --git a/docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md b/docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md
new file mode 100644
index 0000000000..1f60ea2092
--- /dev/null
+++ b/docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md
@@ -0,0 +1,152 @@
+# CS-11675 / CS-11676 / CS-11677 — Combined Chooser, Edit Modal, Toolbar Wiring
+
+## Context
+
+The "Markdown Editing UI" project lets a user pick a card/file from inside the markdown editor and embed it as a BFM directive (`:card[URL]` inline / `::card[URL | size]` block). Foundation already on `main`:
+
+- `MiniCardChooser` — `packages/host/app/components/card-chooser/mini/index.gts` (PR #5288, merged)
+- `MiniFileChooser` — `packages/host/app/components/file-chooser/mini/index.gts` (PR #5298, merged)
+- BFM parsing / serialization in `packages/runtime-common/bfm-card-references.ts`
+- `CardChooserModal` / `FileChooserModal` give the canonical `Deferred<…>`-based modal pattern.
+
+PR #5303 (merged as `dd7cdf8f71`) added:
+
+- `MarkdownEmbedPreviewPane` — `packages/host/app/components/markdown-embed-chooser/pane.gts`. Signature today: `{ target: CardDef | FileDef; refType: 'card' | 'file'; onInsert: (bfm: string) => void }`. Owns format dropdown, W×H inputs, Inline/Block toggle; serializes its own BFM via `serializeBfmRef` + `serializeBfmSizeSpec`.
+- `MarkdownEmbedPreview` — the pure render component the pane uses.
+
+This worktree picks up where #5303 left off: glue the mini choosers to the pane in a tabbed modal, support an edit variant of the same shell, and wire it into the CodeMirror toolbar.
+
+## Branch / PR strategy
+
+- Worktree branch off latest `origin/main` (already includes #5303). Suggested name: `cs-11675-11676-11677-markdown-embed-chooser-modal`.
+- **One combined draft PR** for all three tickets (per user decision). Three commits inside it, one per ticket, so reviewers can scan ticket-by-ticket. Stays a draft until promoted (`feedback_open_drafts_not_prs`).
+- Plan doc lives at `docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md`; deleted before merge (`feedback_plan_doc_not_in_merged_branch`).
+
+---
+
+## CS-11675 — Combined chooser modal
+
+All new files under `packages/host/app/components/markdown-embed-chooser/`.
+
+- **`modal.gts` — `MarkdownEmbedChooserModal`**. Mirrors `card-chooser/modal.gts`: holds a `Deferred<{ refType, url, bfm } | { remove: true } | undefined>`, renders a `ModalContainer` with focus trap, owns the tab state and the current target per tab.
+- **`tabs.gts`** — internal tabbed shell. Two tabs ("Cards" / "Files"). Both panels stay mounted (CSS-hidden when inactive) so left-panel state (search query, highlighted item, scroll, W×H) is preserved across tab switches. State lives on the modal component, not in the inactive child via `{{#if}}`.
+- **`tab-panel.gts`** — pairs one mini chooser with the preview pane. Cards panel: `MiniCardChooser` + pane with `refType='card'`. Files panel: `MiniFileChooser` + pane with `refType='file'`. Clicking a row in the mini chooser sets that tab's `selectedTarget`; the pane re-renders with the new `@target`.
+
+**New service**: `packages/host/app/services/markdown-embed-chooser.ts` — exposes `chooseCardOrFile({ defaultTab })` and `editEmbed({ url, refType, sizeSpec })`. Same request-queue pattern as `card-chooser/modal.gts`. Composed into `operator-mode/container.gts` next to the existing chooser modals.
+
+**Pane changes** (`pane.gts`): teach it to render when `@target` is `undefined` (empty preview, matching Zeplin 02). The format/W×H controls remain visible (disabled / no-op CTA) so layout doesn't jump when a row is picked.
+
+**Acceptance**: matches the 5 bullets on the ticket. Verify with a new integration test at `packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts` + the existing freestyle host page.
+
+---
+
+## CS-11676 — Edit mode of the same modal
+
+Per user decision + Zeplin 08B screenshot: the edit modal is the _same combined chooser modal_ with the same tabs. The only change is that the active tab's **left panel** swaps from the search/chooser view to a "current target" view.
+
+**Per-tab left-panel state** lives in each `tab-panel.gts` instance:
+
+- `mode: 'choose'` (default) — renders the mini chooser (`MiniCardChooser` / `MiniFileChooser`).
+- `mode: 'current'` (edit mode initial) — renders a single tile for the placed target with two buttons:
+  - **Replace Card / Replace File** → flips that tab's `mode` back to `choose` and exposes the mini chooser. Picking a new row sets the new target.
+  - **Remove Card / Remove File** → resolves the modal's Deferred with `{ remove: true }` and closes.
+
+**Modal changes** (`modal.gts`):
+
+- Accept an optional `initialTarget: { refType, url, sizeSpec }` on the request.
+- When present: open on the matching tab, set that tab's `mode` to `current` with the resolved target, and preload the pane with the parsed `sizeSpec`. Switching to the other tab still works (Zeplin 08B note: "TOGGLING TO FILES WILL DISPLAY FILE CHOOSER UI") — the inactive tab starts in `choose` mode.
+
+**Pane extension** (`pane.gts`) — required for preload + dirty tracking:
+
+```ts
+// New args:
+initialFormat?: OptionValue;
+initialWidth?: number | string;
+initialHeight?: number;
+initialKind?: 'inline' | 'block';
+onDirtyChange?: (dirty: boolean) => void;
+ctaLabelOverride?: string;  // 'DONE' / 'ACCEPT' for edit mode
+```
+
+Inbound `BfmSizeSpec` → `OptionValue` mapping mirrors `selectFormat` + `syncVariantFromSize`. Dirty = the serialized current BFM differs from the initial BFM. In edit mode the parent passes `ctaLabelOverride = dirty ? 'ACCEPT' : 'DONE'`, and the CTA is always active (per Zeplin 08B note 2).
+
+**Acceptance**: matches the 5 ticket bullets. The modal's caller (CS-11677 wiring) does the actual in-place text replacement once `ACCEPT` resolves the Deferred with the new BFM string.
+
+---
+
+## CS-11677 — Toolbar + cursor-aware Edit
+
+Per user decision: drop the standalone "dimensions overlay chip on every inline preview" sub-piece. The W×H readout lives inside `MarkdownEmbedPreviewPane` (already there via the W/H inputs in #5303), so the user sees dimensions when picking / editing — no separate editor-side overlay required.
+
+Two pieces remain.
+
+### (a) Toolbar item — Add a card / Add a file
+
+Per the third screenshot: a single toolbar trigger that opens a popover with two items, **Add a card** and **Add a file**. Each calls into the host to open the combined modal with `defaultTab: 'cards'` or `'files'`.
+
+In `packages/base/codemirror-editor.gts` around line 418 (`toolbarButtons`), insert a new entry left of the formatting group. The toolbar item type already supports inline toggles + dividers; add a new variant (or a dedicated popover button beside the array) for the dropdown trigger. Each menu item calls a new host-supplied callback (the editor lives in `packages/base/`, a card-definition surface, and surfaces hooks rather than importing host services — same pattern as existing toolbar actions). The host wires that callback to `markdownEmbedChooser.chooseCardOrFile({ defaultTab })`.
+
+On resolution with `{ bfm }`: dispatch a CodeMirror transaction at the current selection. Insert pattern at `codemirror-editor.gts:580–594`. For block embeds, surround the directive with the newline-padding rules already used there.
+
+### (b) Cursor-aware Edit button
+
+A new BFM-range tracker, two layers:
+
+1. **New helper** in `packages/runtime-common/bfm-card-references.ts`:
+
+   ```ts
+   export function extractBfmRefRanges(markdown: string): Array<{
+     kind: 'inline' | 'block';
+     from: number;
+     to: number;
+     refType: 'card' | 'file';
+     url: string; // unresolved, as written in the source
+     sizeSpec?: string;
+   }>;
+   ```
+
+   Pure string scan reusing the block (line 288) and inline (line 290) regexes already in the file. No URL resolution — cheap to run on every doc change.
+
+2. **CodeMirror extension** wired in `packages/host/app/lib/codemirror-context.ts`: a `ViewPlugin` that recomputes ranges on `update.docChanged`, then on `update.selectionSet` tests `update.state.selection.main.head` against the ranges. Surface the result via a tracked value on the editor's controller — same channel `EditorView.updateListener` uses around lines 1120–1146.
+
+When `currentRef` is non-null, the toolbar swaps the "Add embed" item for an Edit pencil; click opens `markdownEmbedChooser.editEmbed({ refType, url, sizeSpec })`.
+
+On the modal's resolution:
+
+- `{ bfm }` (ACCEPT) → dispatch a transaction replacing the original `[from, to]` range with the new BFM string.
+- `{ remove: true }` → dispatch a transaction deleting `[from, to]` (and the surrounding newlines for block).
+- `undefined` (DONE / cancel) → no-op.
+
+### Acceptance
+
+Matches the remaining ticket bullets except the dimensions-overlay one (descoped per user). Verify via a new integration test at `packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts` + the freestyle host page + the live dev stack walk-through below.
+
+---
+
+## Verification
+
+Per-ticket integration tests above + the existing `markdown-embed` suite from #5303 continue to pass.
+
+End-to-end in the dev stack (`feedback_boxel_run_dev_all`, `feedback_faster_dev_stack_split`):
+
+```
+mise exec -- pnpm -C packages/host start    # one terminal
+mise run dev                                 # another
+```
+
+Then at `https://localhost:4200/tests` or the dev host:
+
+1. Open a markdown file in code mode → toolbar shows the Add embed control.
+2. Add a card → modal opens on the Cards tab → pick a card → pane updates → click "Insert as …" → directive inserted at cursor and renders inline/block per the toggle.
+3. Switch tabs mid-session → verify the other tab's search query / W×H survive.
+4. Place the cursor inside the inserted ref → toolbar swaps to the Edit pencil.
+5. Click Edit → modal reopens preloaded with the current target + size. Change the format → CTA label flips to ACCEPT. Click ACCEPT → ref is replaced in place.
+6. Open Edit again → click Remove → ref disappears.
+
+## Critical reused utilities
+
+- `Deferred` (`packages/runtime-common/deferred.ts`) — same modal-resolution pattern as `card-chooser/modal.gts`.
+- `serializeBfmRef`, `serializeBfmSizeSpec`, `parseBfmSizeSpec` — `packages/runtime-common/bfm-card-references.ts` (last two on `main`, first on #5303 branch).
+- `MarkdownEmbedPreviewPane` — `packages/host/app/components/markdown-embed-chooser/pane.gts` (extended in CS-11676).
+- `MiniCardChooser`, `MiniFileChooser` — composed verbatim inside each tab.
+- CodeMirror selection-listener pattern at `packages/host/app/lib/codemirror-context.ts:1120–1146`; insert-at-cursor pattern at `packages/base/codemirror-editor.gts:580–594`.
diff --git a/packages/host/app/components/markdown-embed-chooser/modal.gts b/packages/host/app/components/markdown-embed-chooser/modal.gts
new file mode 100644
index 0000000000..e527d07954
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/modal.gts
@@ -0,0 +1,125 @@
+import { hash } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { action } from '@ember/object';
+import { service } from '@ember/service';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import focusTrap from 'ember-focus-trap/modifiers/focus-trap';
+
+import ModalContainer from '@cardstack/host/components/modal-container';
+
+import type MarkdownEmbedChooserService from '@cardstack/host/services/markdown-embed-chooser';
+import type {
+  MarkdownEmbedChooserRequest,
+  MarkdownEmbedRefType,
+} from '@cardstack/host/services/markdown-embed-chooser';
+
+import TabPanel from './tab-panel';
+import Tabs from './tabs';
+
+interface Signature {
+  Args: {};
+}
+
+// Modal shell for the combined chooser. Driven by the
+// `markdown-embed-chooser` service: opens when a `chooseCardOrFile` /
+// `editEmbed` call lands, closes when the user picks/cancels or hits Escape.
+// Both tabs stay mounted while the modal is open so each tab keeps its own
+// search/selection/W×H state across switches.
+export default class MarkdownEmbedChooserModal extends Component<Signature> {
+  @service declare private markdownEmbedChooser: MarkdownEmbedChooserService;
+
+  // User clicks pinned to the request they were made against. The getter
+  // ignores them once a new request arrives so the next opening starts on
+  // its own `defaultTab`.
+  @tracked private manuallySelectedTab: MarkdownEmbedRefType | undefined;
+  @tracked
+  private manualSelectionRequest: MarkdownEmbedChooserRequest | undefined;
+
+  private get request() {
+    return this.markdownEmbedChooser.currentRequest;
+  }
+
+  get activeTab(): MarkdownEmbedRefType {
+    let req = this.request;
+    if (
+      this.manualSelectionRequest === req &&
+      this.manuallySelectedTab !== undefined
+    ) {
+      return this.manuallySelectedTab;
+    }
+    return req?.defaultTab ?? 'card';
+  }
+
+  @action
+  private setActiveTab(tab: MarkdownEmbedRefType) {
+    this.manualSelectionRequest = this.request;
+    this.manuallySelectedTab = tab;
+  }
+
+  @action
+  private handleInsertCard(bfm: string, url: string) {
+    this.markdownEmbedChooser.resolve({ refType: 'card', url, bfm });
+  }
+
+  @action
+  private handleInsertFile(bfm: string, url: string) {
+    this.markdownEmbedChooser.resolve({ refType: 'file', url, bfm });
+  }
+
+  @action
+  private handleClose() {
+    this.markdownEmbedChooser.resolve(undefined);
+  }
+
+  @action
+  private handleKeydown(event: Event) {
+    if ((event as KeyboardEvent).key === 'Escape') {
+      this.handleClose();
+    }
+  }
+
+  <template>
+    {{#if this.request}}
+      <ModalContainer
+        class='markdown-embed-chooser-modal'
+        @title='Embed a card or file'
+        @onClose={{this.handleClose}}
+        @size='large'
+        @centered={{true}}
+        @cardContainerClass='markdown-embed-chooser-modal__container'
+        {{focusTrap
+          isActive=true
+          focusTrapOptions=(hash allowOutsideClick=true)
+        }}
+        {{on 'keydown' this.handleKeydown}}
+        data-test-markdown-embed-chooser-modal
+      >
+        <:content>
+          <Tabs
+            @activeTab={{this.activeTab}}
+            @onTabChange={{this.setActiveTab}}
+          >
+            <:cards>
+              <TabPanel @refType='card' @onInsert={{this.handleInsertCard}} />
+            </:cards>
+            <:files>
+              <TabPanel @refType='file' @onInsert={{this.handleInsertFile}} />
+            </:files>
+          </Tabs>
+        </:content>
+      </ModalContainer>
+    {{/if}}
+    <style scoped>
+      .markdown-embed-chooser-modal :deep(.dialog-box__content) {
+        display: flex;
+        flex-direction: column;
+        padding: var(--boxel-sp-sm) var(--boxel-sp);
+      }
+      :deep(.markdown-embed-chooser-modal__container) {
+        height: 36rem;
+      }
+    </style>
+  </template>
+}
diff --git a/packages/host/app/components/markdown-embed-chooser/pane.gts b/packages/host/app/components/markdown-embed-chooser/pane.gts
index 16edfe376d..23e2de71e7 100644
--- a/packages/host/app/components/markdown-embed-chooser/pane.gts
+++ b/packages/host/app/components/markdown-embed-chooser/pane.gts
@@ -88,8 +88,11 @@ function buildFormatOptions(): FormatOption[] {
 interface Signature {
   Element: HTMLElement;
   Args: {
-    // Resolved instance being previewed. Its `id` is the BFM ref URL.
-    target: CardDef | FileDef;
+    // Resolved instance being previewed. Its `id` is the BFM ref URL. May be
+    // undefined when the chooser is open but the user hasn't picked a row yet;
+    // the pane keeps the format/W×H controls visible (disabled CTA) so the
+    // layout doesn't jump when a target arrives.
+    target?: CardDef | FileDef;
     // Which BFM keyword to emit: `:card[...]` vs `:file[...]`.
     refType: 'card' | 'file';
     // Receives the serialized BFM directive when the CTA is clicked. The host
@@ -209,13 +212,20 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   }
 
   private get bfmString(): string {
-    let url = this.args.target.id;
+    let url = this.args.target?.id;
+    if (!url) {
+      return '';
+    }
     return serializeBfmRef(this.args.refType, url, {
       kind: this.kind,
       size: this.sizeSpecifier,
     });
   }
 
+  private get isCtaDisabled(): boolean {
+    return !this.args.target?.id;
+  }
+
   @action
   private selectFormat(option: FormatOption) {
     this.selectedValue = option.value;
@@ -266,7 +276,9 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
 
   @action
   private insert() {
-    this.args.onInsert(this.bfmString);
+    let bfm = this.bfmString;
+    if (!bfm) return;
+    this.args.onInsert(bfm);
   }
 
   <template>
@@ -302,13 +314,24 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
       </div>
 
       <div class='markdown-embed-preview-pane__viewport'>
-        <MarkdownEmbedPreview
-          @target={{@target}}
-          @format={{this.previewFormat}}
-          @sizeSpec={{this.sizeSpec}}
-          @kind={{this.kind}}
-          @showSurroundingText={{true}}
-        />
+        {{#if @target}}
+          <MarkdownEmbedPreview
+            @target={{@target}}
+            @format={{this.previewFormat}}
+            @sizeSpec={{this.sizeSpec}}
+            @kind={{this.kind}}
+            @showSurroundingText={{true}}
+          />
+        {{else}}
+          <p
+            class='markdown-embed-preview-pane__empty'
+            data-test-markdown-embed-preview-empty
+          >
+            Pick a
+            {{@refType}}
+            to preview its embed.
+          </p>
+        {{/if}}
       </div>
 
       <footer class='markdown-embed-preview-pane__footer'>
@@ -343,6 +366,7 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
         <Button
           @kind='primary'
           @size='small'
+          @disabled={{this.isCtaDisabled}}
           class='markdown-embed-preview-pane__cta'
           data-test-markdown-embed-preview-cta
           {{on 'click' this.insert}}
@@ -408,6 +432,12 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
         overflow: auto;
         background-color: var(--boxel-100);
       }
+      .markdown-embed-preview-pane__empty {
+        margin: 0;
+        font: var(--boxel-font-sm);
+        color: var(--boxel-450);
+        text-align: center;
+      }
       .markdown-embed-preview-pane__format-select {
         flex: 1 1 auto;
         min-width: 0;
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
new file mode 100644
index 0000000000..6710c53370
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
@@ -0,0 +1,119 @@
+import { action } from '@ember/object';
+import { service } from '@ember/service';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import { restartableTask } from 'ember-concurrency';
+
+import { eq } from '@cardstack/boxel-ui/helpers';
+
+import { isCardErrorJSONAPI } from '@cardstack/runtime-common';
+
+import MiniCardChooser from '@cardstack/host/components/card-chooser/mini';
+import MiniFileChooser from '@cardstack/host/components/file-chooser/mini';
+
+import type StoreService from '@cardstack/host/services/store';
+
+import type { CardDef, FileDef } from 'https://cardstack.com/base/card-api';
+
+import MarkdownEmbedPreviewPane from './pane';
+
+interface Signature {
+  Element: HTMLDivElement;
+  Args: {
+    refType: 'card' | 'file';
+    onInsert: (bfm: string, url: string) => void;
+  };
+}
+
+// One tab of the combined chooser: pairs the matching mini chooser (left
+// panel) with the shared preview pane (right panel). Owns the tab-local
+// `selectedTarget` so left-panel state — search query, highlighted row,
+// scroll position — and pane state survive a switch to the other tab.
+export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
+  @service declare private store: StoreService;
+
+  @tracked private selectedTarget: CardDef | FileDef | undefined;
+  @tracked private selectedUrl: string | undefined;
+
+  @action
+  private onCardSelect(url: string) {
+    this.loadTarget.perform(url, 'card');
+  }
+
+  @action
+  private onFileSelect(url: string) {
+    this.loadTarget.perform(url, 'file');
+  }
+
+  // Restart on every pick so a slow earlier load can't stomp the newer one.
+  private loadTarget = restartableTask(
+    async (url: string, refType: 'card' | 'file') => {
+      this.selectedUrl = url;
+      let result =
+        refType === 'card'
+          ? await this.store.get(url)
+          : await this.store.get<FileDef>(url, { type: 'file-meta' });
+      if (isCardErrorJSONAPI(result)) {
+        this.selectedTarget = undefined;
+        return;
+      }
+      this.selectedTarget = result as CardDef | FileDef;
+    },
+  );
+
+  @action
+  private handleInsert(bfm: string) {
+    let url = this.selectedTarget?.id ?? this.selectedUrl;
+    if (!url) return;
+    this.args.onInsert(bfm, url);
+  }
+
+  <template>
+    <div
+      class='markdown-embed-chooser-tab-panel'
+      data-test-markdown-embed-chooser-tab-panel={{@refType}}
+      ...attributes
+    >
+      <div class='markdown-embed-chooser-tab-panel__left'>
+        {{#if (eq @refType 'card')}}
+          <MiniCardChooser
+            @onSelect={{this.onCardSelect}}
+            @selected={{this.selectedUrl}}
+          />
+        {{else}}
+          <MiniFileChooser
+            @onSelect={{this.onFileSelect}}
+            @selected={{this.selectedUrl}}
+          />
+        {{/if}}
+      </div>
+      <div class='markdown-embed-chooser-tab-panel__right'>
+        <MarkdownEmbedPreviewPane
+          @target={{this.selectedTarget}}
+          @refType={{@refType}}
+          @onInsert={{this.handleInsert}}
+        />
+      </div>
+    </div>
+    <style scoped>
+      .markdown-embed-chooser-tab-panel {
+        display: flex;
+        gap: var(--boxel-sp);
+        width: 100%;
+        height: 100%;
+        min-height: 0;
+      }
+      .markdown-embed-chooser-tab-panel__left,
+      .markdown-embed-chooser-tab-panel__right {
+        flex: 1 1 0;
+        min-width: 0;
+        min-height: 0;
+        border: 1px solid var(--boxel-300);
+        border-radius: var(--boxel-border-radius);
+        overflow: hidden;
+        background-color: var(--boxel-light);
+      }
+    </style>
+  </template>
+}
diff --git a/packages/host/app/components/markdown-embed-chooser/tabs.gts b/packages/host/app/components/markdown-embed-chooser/tabs.gts
new file mode 100644
index 0000000000..41b469b984
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/tabs.gts
@@ -0,0 +1,130 @@
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+
+import { eq } from '@cardstack/boxel-ui/helpers';
+
+import type { MarkdownEmbedRefType } from '@cardstack/host/services/markdown-embed-chooser';
+
+interface Signature {
+  Element: HTMLDivElement;
+  Args: {
+    activeTab: MarkdownEmbedRefType;
+    onTabChange: (tab: MarkdownEmbedRefType) => void;
+  };
+  Blocks: {
+    cards: [];
+    files: [];
+  };
+}
+
+// Two-tab shell for the combined chooser. Both panels stay mounted — the
+// inactive one is `display: none` rather than `{{#if}}`'d out — so each tab's
+// mini-chooser keeps its search query, highlighted row, scroll position, and
+// the pane's W×H / format selection across a switch.
+const MarkdownEmbedChooserTabs: TemplateOnlyComponent<Signature> = <template>
+  <div class='markdown-embed-chooser-tabs' ...attributes>
+    <div
+      class='markdown-embed-chooser-tabs__strip'
+      role='tablist'
+      aria-label='Choose card or file'
+    >
+      <button
+        type='button'
+        role='tab'
+        id='markdown-embed-chooser-tab-cards'
+        aria-controls='markdown-embed-chooser-panel-cards'
+        aria-selected={{if (eq @activeTab 'card') 'true' 'false'}}
+        tabindex={{if (eq @activeTab 'card') '0' '-1'}}
+        class='markdown-embed-chooser-tabs__tab
+          {{if (eq @activeTab "card") "is-active"}}'
+        data-test-markdown-embed-chooser-tab='card'
+        {{on 'click' (fn @onTabChange 'card')}}
+      >
+        Cards
+      </button>
+      <button
+        type='button'
+        role='tab'
+        id='markdown-embed-chooser-tab-files'
+        aria-controls='markdown-embed-chooser-panel-files'
+        aria-selected={{if (eq @activeTab 'file') 'true' 'false'}}
+        tabindex={{if (eq @activeTab 'file') '0' '-1'}}
+        class='markdown-embed-chooser-tabs__tab
+          {{if (eq @activeTab "file") "is-active"}}'
+        data-test-markdown-embed-chooser-tab='file'
+        {{on 'click' (fn @onTabChange 'file')}}
+      >
+        Files
+      </button>
+    </div>
+    <div
+      role='tabpanel'
+      id='markdown-embed-chooser-panel-cards'
+      aria-labelledby='markdown-embed-chooser-tab-cards'
+      class='markdown-embed-chooser-tabs__panel
+        {{unless (eq @activeTab "card") "is-hidden"}}'
+      data-test-markdown-embed-chooser-panel='card'
+    >
+      {{yield to='cards'}}
+    </div>
+    <div
+      role='tabpanel'
+      id='markdown-embed-chooser-panel-files'
+      aria-labelledby='markdown-embed-chooser-tab-files'
+      class='markdown-embed-chooser-tabs__panel
+        {{unless (eq @activeTab "file") "is-hidden"}}'
+      data-test-markdown-embed-chooser-panel='file'
+    >
+      {{yield to='files'}}
+    </div>
+  </div>
+  <style scoped>
+    .markdown-embed-chooser-tabs {
+      display: flex;
+      flex-direction: column;
+      width: 100%;
+      height: 100%;
+      min-height: 0;
+    }
+    .markdown-embed-chooser-tabs__strip {
+      flex: 0 0 auto;
+      display: flex;
+      gap: var(--boxel-sp-xs);
+      padding: 0 var(--boxel-sp-xs);
+      border-bottom: 1px solid var(--boxel-300);
+    }
+    .markdown-embed-chooser-tabs__tab {
+      appearance: none;
+      background: none;
+      border: none;
+      padding: var(--boxel-sp-xs) var(--boxel-sp-sm);
+      font: 600 var(--boxel-font-sm);
+      color: var(--boxel-450);
+      cursor: pointer;
+      border-bottom: 2px solid transparent;
+      margin-bottom: -1px;
+    }
+    .markdown-embed-chooser-tabs__tab:hover {
+      color: var(--boxel-dark);
+    }
+    .markdown-embed-chooser-tabs__tab.is-active {
+      color: var(--boxel-dark);
+      border-bottom-color: var(--boxel-highlight);
+    }
+    .markdown-embed-chooser-tabs__tab:focus-visible {
+      outline: 2px solid var(--boxel-highlight);
+      outline-offset: 2px;
+    }
+    .markdown-embed-chooser-tabs__panel {
+      flex: 1 1 auto;
+      min-height: 0;
+      padding-top: var(--boxel-sp-sm);
+    }
+    .markdown-embed-chooser-tabs__panel.is-hidden {
+      display: none;
+    }
+  </style>
+</template>;
+
+export default MarkdownEmbedChooserTabs;
diff --git a/packages/host/app/components/operator-mode/container.gts b/packages/host/app/components/operator-mode/container.gts
index 9d2d4adace..898d40ec60 100644
--- a/packages/host/app/components/operator-mode/container.gts
+++ b/packages/host/app/components/operator-mode/container.gts
@@ -39,6 +39,7 @@ import type { CardContext } from 'https://cardstack.com/base/card-api';
 import CardChooserModal from '../card-chooser/modal';
 import SearchResults from '../card-search/search-results';
 import FileChooserModal from '../file-chooser/modal';
+import MarkdownEmbedChooserModal from '../markdown-embed-chooser/modal';
 import { Submodes } from '../submode-switcher';
 
 import CreateListingModal from './create-listing-modal';
@@ -147,6 +148,7 @@ export default class OperatorModeContainer extends Component<Signature> {
       <FileChooserModal />
       <CreateListingModal />
       <CardChooserModal />
+      <MarkdownEmbedChooserModal />
       <FromElseWhere @name='modal-elsewhere' />
 
       {{#if
diff --git a/packages/host/app/services/markdown-embed-chooser.ts b/packages/host/app/services/markdown-embed-chooser.ts
new file mode 100644
index 0000000000..fdb0b25409
--- /dev/null
+++ b/packages/host/app/services/markdown-embed-chooser.ts
@@ -0,0 +1,87 @@
+import Service from '@ember/service';
+
+import { tracked } from '@glimmer/tracking';
+
+import { Deferred } from '@cardstack/runtime-common';
+
+import type { BfmSizeSpec } from '@cardstack/runtime-common/bfm-card-references';
+
+export type MarkdownEmbedRefType = 'card' | 'file';
+
+export interface MarkdownEmbedResult {
+  refType: MarkdownEmbedRefType;
+  url: string;
+  bfm: string;
+}
+
+export type MarkdownEmbedResolution =
+  | MarkdownEmbedResult
+  | { remove: true }
+  | undefined;
+
+export interface MarkdownEmbedInitialTarget {
+  refType: MarkdownEmbedRefType;
+  url: string;
+  // Either a pre-parsed `BfmSizeSpec` (from extractBfmRefRanges) or the raw
+  // specifier text after `|`. The pane parses the string form itself.
+  sizeSpec?: BfmSizeSpec | string;
+}
+
+export interface MarkdownEmbedChooserRequest {
+  defaultTab: MarkdownEmbedRefType;
+  initialTarget?: MarkdownEmbedInitialTarget;
+  deferred: Deferred<MarkdownEmbedResolution>;
+}
+
+// Single in-flight request at a time — the modal is the only consumer. If
+// another `chooseCardOrFile`/`editEmbed` call lands while a modal is already
+// open, the prior caller is resolved with `undefined` (cancel) before the new
+// request displaces it.
+export default class MarkdownEmbedChooserService extends Service {
+  @tracked currentRequest: MarkdownEmbedChooserRequest | undefined;
+
+  chooseCardOrFile(
+    opts: { defaultTab?: MarkdownEmbedRefType } = {},
+  ): Promise<MarkdownEmbedResolution> {
+    return this.open({ defaultTab: opts.defaultTab ?? 'card' });
+  }
+
+  editEmbed(
+    target: MarkdownEmbedInitialTarget,
+  ): Promise<MarkdownEmbedResolution> {
+    return this.open({
+      defaultTab: target.refType,
+      initialTarget: target,
+    });
+  }
+
+  resolve(result: MarkdownEmbedResolution) {
+    let req = this.currentRequest;
+    if (!req) return;
+    req.deferred.fulfill(result);
+  }
+
+  private async open(opts: {
+    defaultTab: MarkdownEmbedRefType;
+    initialTarget?: MarkdownEmbedInitialTarget;
+  }): Promise<MarkdownEmbedResolution> {
+    if (this.currentRequest) {
+      this.currentRequest.deferred.fulfill(undefined);
+    }
+    let deferred = new Deferred<MarkdownEmbedResolution>();
+    this.currentRequest = { ...opts, deferred };
+    try {
+      return await deferred.promise;
+    } finally {
+      if (this.currentRequest?.deferred === deferred) {
+        this.currentRequest = undefined;
+      }
+    }
+  }
+}
+
+declare module '@ember/service' {
+  interface Registry {
+    'markdown-embed-chooser': MarkdownEmbedChooserService;
+  }
+}
diff --git a/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
new file mode 100644
index 0000000000..c5ee94f1de
--- /dev/null
+++ b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
@@ -0,0 +1,245 @@
+import {
+  type RenderingTestContext,
+  click,
+  fillIn,
+  render,
+  waitFor,
+  waitUntil,
+} from '@ember/test-helpers';
+
+import GlimmerComponent from '@glimmer/component';
+
+import { getService } from '@universal-ember/test-support';
+import { provide } from 'ember-provide-consume-context';
+
+import { module, test } from 'qunit';
+
+import {
+  baseRealm,
+  CardContextName,
+  GetCardContextName,
+  GetCardCollectionContextName,
+  GetCardsContextName,
+} from '@cardstack/runtime-common';
+
+import MarkdownEmbedChooserModal from '@cardstack/host/components/markdown-embed-chooser/modal';
+import { getCardCollection } from '@cardstack/host/resources/card-collection';
+import { getCard } from '@cardstack/host/resources/card-resource';
+import type MarkdownEmbedChooserService from '@cardstack/host/services/markdown-embed-chooser';
+import type StoreService from '@cardstack/host/services/store';
+
+import {
+  setupIntegrationTestRealm,
+  setupLocalIndexing,
+  testRealmURL,
+} from '../../helpers';
+import {
+  CardDef,
+  StringField,
+  contains,
+  field,
+  setupBaseRealm,
+} from '../../helpers/base-realm';
+import { setupMockMatrix } from '../../helpers/mock-matrix';
+import { setupRenderingTest } from '../../helpers/setup';
+
+// The mini choosers consume host context via @consume — provide it here so the
+// modal renders standalone in this rendering test.
+class HostContextProvider extends GlimmerComponent<{
+  Blocks: { default: [] };
+}> {
+  @provide(GetCardContextName)
+  get getCardFn() {
+    return getCard;
+  }
+  @provide(GetCardsContextName)
+  get getCardsFn() {
+    let store = getService('store') as StoreService;
+    return store.getSearchResource.bind(store);
+  }
+  @provide(GetCardCollectionContextName)
+  get getCardCollectionFn() {
+    return getCardCollection;
+  }
+  @provide(CardContextName)
+  get cardContext() {
+    return {};
+  }
+  <template>
+    {{! template-lint-disable no-yield-only }}
+    {{yield}}
+  </template>
+}
+
+module('Integration | markdown-embed-chooser-modal', function (hooks) {
+  setupRenderingTest(hooks);
+  setupBaseRealm(hooks);
+  setupLocalIndexing(hooks);
+
+  let mockMatrixUtils = setupMockMatrix(hooks, {
+    loggedInAs: '@testuser:localhost',
+    activeRealms: [baseRealm.url, testRealmURL],
+    autostart: true,
+  });
+
+  const mango = `${testRealmURL}books/mango`;
+
+  hooks.beforeEach(async function (this: RenderingTestContext) {
+    class Book extends CardDef {
+      static displayName = 'Book';
+      @field title = contains(StringField);
+    }
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      realmURL: testRealmURL,
+      contents: {
+        'book.gts': { Book },
+        'books/mango.json': new Book({ title: 'Mango' }),
+        'books/vincent.json': new Book({ title: 'Vincent' }),
+        'notes/hello.txt': 'hello',
+      },
+    });
+    await getService('realm').login(testRealmURL);
+  });
+
+  test('opens on the default tab and mounts both tabpanels', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    assert
+      .dom('[data-test-markdown-embed-chooser-modal]')
+      .doesNotExist('the modal is closed by default');
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile({ defaultTab: 'card' });
+
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab="card"]')
+      .hasAttribute('aria-selected', 'true', 'cards tab is active');
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab="file"]')
+      .hasAttribute('aria-selected', 'false', 'files tab is inactive');
+    // Both panels stay in the DOM so per-tab state survives a switch.
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab-panel="card"]')
+      .exists('card tab-panel is mounted');
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab-panel="file"]')
+      .exists('file tab-panel is mounted even while inactive');
+
+    // Resolve to clean up the pending promise.
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('the cards tab search query survives a switch to files and back', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile({ defaultTab: 'card' });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Type into the cards search bar (scoped to the card tab-panel).
+    await fillIn(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      'Vinc',
+    );
+
+    await click('[data-test-markdown-embed-chooser-tab="file"]');
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab="file"]')
+      .hasAttribute('aria-selected', 'true');
+
+    await click('[data-test-markdown-embed-chooser-tab="card"]');
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      )
+      .hasValue('Vinc', 'card-tab search query survived the round-trip');
+
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('closing the modal resolves the deferred with undefined', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile();
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    await click('[data-test-close-modal]');
+    let result = await pending;
+    assert.strictEqual(result, undefined, 'cancelling resolves with undefined');
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+  });
+
+  test('picking a card resolves the deferred with the serialized BFM', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile({ defaultTab: 'card' });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Search for the seeded card and click its row. SearchResultSection
+    // renders rows under [data-test-search-result] in the mini variant.
+    await fillIn(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      'Mango',
+    );
+    await waitFor(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mango}"]`,
+      { timeout: 5000 },
+    );
+    await click(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mango}"]`,
+    );
+
+    // Pane unlocks once the target loads.
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    await click('[data-test-markdown-embed-preview-cta]');
+
+    let result = await pending;
+    assert.deepEqual(
+      result,
+      { refType: 'card', url: mango, bfm: `:card[${mango}]` },
+      'resolves with the serialized BFM directive for the picked card',
+    );
+  });
+});

From 7753457c92e596b561f853d9dd9f08d5f5614de1 Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Fri, 26 Jun 2026 15:26:19 +0700
Subject: [PATCH 02/12] Edit mode for MarkdownEmbedChooserModal (CS-11676)

When opened via `editEmbed({ url, refType, sizeSpec })` the matching tab
starts in `current` mode showing the placed target with Replace / Remove
buttons; the other tab still mounts its mini chooser per Zeplin 08B.
Replace flips the tab back to the chooser. Remove resolves the modal's
deferred with `{ remove: true }`. The pane gains edit-mode preload args
(initialFormat / initialWidth / initialHeight / initialKind) plus a
`ctaLabelOverride` and an `onDirtyChange` callback the parent uses to
flip the CTA between DONE and ACCEPT.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../markdown-embed-chooser/modal.gts          |  31 ++-
 .../markdown-embed-chooser/pane.gts           |  89 ++++++++-
 .../markdown-embed-chooser/tab-panel.gts      | 189 +++++++++++++++++-
 .../markdown-embed-chooser-modal-test.gts     | 108 ++++++++++
 4 files changed, 409 insertions(+), 8 deletions(-)

diff --git a/packages/host/app/components/markdown-embed-chooser/modal.gts b/packages/host/app/components/markdown-embed-chooser/modal.gts
index e527d07954..f30487dfe0 100644
--- a/packages/host/app/components/markdown-embed-chooser/modal.gts
+++ b/packages/host/app/components/markdown-embed-chooser/modal.gts
@@ -68,6 +68,11 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
     this.markdownEmbedChooser.resolve({ refType: 'file', url, bfm });
   }
 
+  @action
+  private handleRemove() {
+    this.markdownEmbedChooser.resolve({ remove: true });
+  }
+
   @action
   private handleClose() {
     this.markdownEmbedChooser.resolve(undefined);
@@ -80,6 +85,18 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
     }
   }
 
+  // Edit-mode preload is scoped to the matching tab. The other tab still
+  // opens its mini chooser per Zeplin 08B.
+  private get cardInitialTarget() {
+    let it = this.request?.initialTarget;
+    return it?.refType === 'card' ? it : undefined;
+  }
+
+  private get fileInitialTarget() {
+    let it = this.request?.initialTarget;
+    return it?.refType === 'file' ? it : undefined;
+  }
+
   <template>
     {{#if this.request}}
       <ModalContainer
@@ -102,10 +119,20 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
             @onTabChange={{this.setActiveTab}}
           >
             <:cards>
-              <TabPanel @refType='card' @onInsert={{this.handleInsertCard}} />
+              <TabPanel
+                @refType='card'
+                @onInsert={{this.handleInsertCard}}
+                @initialTarget={{this.cardInitialTarget}}
+                @onRemove={{this.handleRemove}}
+              />
             </:cards>
             <:files>
-              <TabPanel @refType='file' @onInsert={{this.handleInsertFile}} />
+              <TabPanel
+                @refType='file'
+                @onInsert={{this.handleInsertFile}}
+                @initialTarget={{this.fileInitialTarget}}
+                @onRemove={{this.handleRemove}}
+              />
             </:files>
           </Tabs>
         </:content>
diff --git a/packages/host/app/components/markdown-embed-chooser/pane.gts b/packages/host/app/components/markdown-embed-chooser/pane.gts
index 23e2de71e7..5b56b65cc3 100644
--- a/packages/host/app/components/markdown-embed-chooser/pane.gts
+++ b/packages/host/app/components/markdown-embed-chooser/pane.gts
@@ -1,5 +1,6 @@
 import { on } from '@ember/modifier';
 import { action } from '@ember/object';
+import type Owner from '@ember/owner';
 
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
@@ -30,7 +31,12 @@ import MarkdownEmbedPreview from './preview';
 
 type EmbedFormat = 'atom' | 'embedded' | 'fitted' | 'isolated';
 type FormatCategory = 'atom' | 'embedded' | 'fitted' | 'isolated' | 'custom';
-type OptionValue = 'atom' | 'embedded' | 'isolated' | FittedFormatId | 'custom';
+export type OptionValue =
+  | 'atom'
+  | 'embedded'
+  | 'isolated'
+  | FittedFormatId
+  | 'custom';
 
 interface FormatOption {
   value: OptionValue;
@@ -98,6 +104,21 @@ interface Signature {
     // Receives the serialized BFM directive when the CTA is clicked. The host
     // owns actual cursor insertion (a later ticket).
     onInsert: (bfm: string) => void;
+    // Edit-mode preload: seed the format dropdown, W×H inputs, and placement
+    // toggle from the BFM directive the user is editing. Read once at
+    // construction; later updates are ignored so the pane is free to mutate
+    // its own state as the user edits.
+    initialFormat?: OptionValue;
+    initialWidth?: number | string;
+    initialHeight?: number;
+    initialKind?: 'inline' | 'block';
+    // Fired with `true` once the pane's state diverges from the initial
+    // preload (and back to `false` if it matches again). The parent uses this
+    // to flip the CTA label between 'DONE' and 'ACCEPT' in edit mode.
+    onDirtyChange?: (dirty: boolean) => void;
+    // Overrides the dynamic "Insert as …" CTA label. Used in edit mode to
+    // show 'DONE' (clean) or 'ACCEPT' (dirty) per the design spec.
+    ctaLabelOverride?: string;
   };
 }
 
@@ -116,6 +137,43 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   @tracked private widthInput = '';
   @tracked private heightInput = '';
 
+  // Frozen snapshot of the initial pane state, captured once on mount from the
+  // edit-mode preload args. Used by `dirty` to detect divergence so the parent
+  // can flip the CTA between DONE and ACCEPT.
+  private initialSelectedValue: OptionValue;
+  private initialKind: 'inline' | 'block';
+  private initialWidthInput: string;
+  private initialHeightInput: string;
+  private initialTargetUrl: string | undefined;
+
+  constructor(owner: Owner, args: Signature['Args']) {
+    super(owner, args);
+    if (args.initialFormat !== undefined) {
+      this.selectedValue = args.initialFormat;
+    }
+    if (args.initialKind !== undefined) {
+      this.kind = args.initialKind;
+    } else if (args.initialFormat !== undefined) {
+      // Mirror `selectFormat`'s placement default (atom → inline, sized →
+      // block) when no explicit initial kind is supplied.
+      let cat = this.formatOptions.find(
+        (o) => o.value === args.initialFormat,
+      )?.category;
+      this.kind = cat === 'atom' ? 'inline' : 'block';
+    }
+    if (args.initialWidth !== undefined) {
+      this.widthInput = String(args.initialWidth);
+    }
+    if (args.initialHeight !== undefined) {
+      this.heightInput = String(args.initialHeight);
+    }
+    this.initialSelectedValue = this.selectedValue;
+    this.initialKind = this.kind;
+    this.initialWidthInput = this.widthInput;
+    this.initialHeightInput = this.heightInput;
+    this.initialTargetUrl = args.target?.id;
+  }
+
   private get selectedOption(): FormatOption {
     return (
       this.formatOptions.find((o) => o.value === this.selectedValue) ??
@@ -183,9 +241,37 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   }
 
   private get ctaLabel(): string {
+    if (this.args.ctaLabelOverride !== undefined) {
+      return this.args.ctaLabelOverride;
+    }
     return `Insert as ${this.categoryLabel}`;
   }
 
+  // True once any tracked piece of state (format, placement, W×H, or the
+  // resolved target URL) has diverged from the constructor snapshot. The
+  // parent watches via `onDirtyChange` to drive its CTA label.
+  get isDirty(): boolean {
+    return (
+      this.selectedValue !== this.initialSelectedValue ||
+      this.kind !== this.initialKind ||
+      this.widthInput !== this.initialWidthInput ||
+      this.heightInput !== this.initialHeightInput ||
+      (this.args.target?.id ?? undefined) !== this.initialTargetUrl
+    );
+  }
+
+  // Re-runs on every render. Auto-tracking re-evaluates `isDirty` whenever any
+  // of its dependencies changes; the equality guard keeps onDirtyChange from
+  // firing on every render in addition to genuine transitions.
+  private lastReportedDirty: boolean | undefined;
+  private reportDirty = () => {
+    let dirty = this.isDirty;
+    if (dirty !== this.lastReportedDirty) {
+      this.lastReportedDirty = dirty;
+      this.args.onDirtyChange?.(dirty);
+    }
+  };
+
   // Size specifier for the chosen format. Atom is the default for inline
   // placement, so an inline atom embed emits the size-less `:card[url]`;
   // every other combination carries an explicit specifier so the rendered
@@ -282,6 +368,7 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   }
 
   <template>
+    {{this.reportDirty}}
     <section
       class='markdown-embed-preview-pane'
       data-test-markdown-embed-preview-pane
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
index 6710c53370..43220f85f3 100644
--- a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
@@ -1,40 +1,106 @@
+import { on } from '@ember/modifier';
 import { action } from '@ember/object';
+import type Owner from '@ember/owner';
 import { service } from '@ember/service';
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 
 import { restartableTask } from 'ember-concurrency';
 
+import { BoxelButton } from '@cardstack/boxel-ui/components';
 import { eq } from '@cardstack/boxel-ui/helpers';
 
 import { isCardErrorJSONAPI } from '@cardstack/runtime-common';
 
+import {
+  type BfmSizeSpec,
+  fileNameFromUrl,
+  parseBfmSizeSpec,
+} from '@cardstack/runtime-common/bfm-card-references';
+
 import MiniCardChooser from '@cardstack/host/components/card-chooser/mini';
 import MiniFileChooser from '@cardstack/host/components/file-chooser/mini';
 
+import type {
+  MarkdownEmbedInitialTarget,
+  MarkdownEmbedRefType,
+} from '@cardstack/host/services/markdown-embed-chooser';
 import type StoreService from '@cardstack/host/services/store';
 
 import type { CardDef, FileDef } from 'https://cardstack.com/base/card-api';
 
-import MarkdownEmbedPreviewPane from './pane';
+import MarkdownEmbedPreviewPane, { type OptionValue } from './pane';
 
 interface Signature {
   Element: HTMLDivElement;
   Args: {
-    refType: 'card' | 'file';
+    refType: MarkdownEmbedRefType;
     onInsert: (bfm: string, url: string) => void;
+    // Optional edit-mode preload for this tab. When set, the tab starts in
+    // `current` mode showing the placed target with Replace / Remove buttons;
+    // the pane is seeded with the matching size + placement.
+    initialTarget?: MarkdownEmbedInitialTarget;
+    // Fired when the user clicks "Remove" in `current` mode. The modal
+    // resolves its deferred with `{ remove: true }`.
+    onRemove?: () => void;
   };
 }
 
 // One tab of the combined chooser: pairs the matching mini chooser (left
 // panel) with the shared preview pane (right panel). Owns the tab-local
 // `selectedTarget` so left-panel state — search query, highlighted row,
-// scroll position — and pane state survive a switch to the other tab.
+// scroll position — and pane state survive a switch to the other tab. In
+// edit mode (`initialTarget` set), the left panel renders a "current target"
+// tile with Replace / Remove buttons instead of the mini chooser; clicking
+// Replace flips it back to the chooser so the user can swap in a new ref.
 export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
   @service declare private store: StoreService;
 
   @tracked private selectedTarget: CardDef | FileDef | undefined;
   @tracked private selectedUrl: string | undefined;
+  @tracked private mode: 'choose' | 'current' = 'choose';
+  @tracked private dirty = false;
+
+  private initialPaneFormat: OptionValue | undefined;
+  private initialPaneWidth: number | string | undefined;
+  private initialPaneHeight: number | undefined;
+  private initialPaneKind: 'inline' | 'block' | undefined;
+
+  constructor(owner: Owner, args: Signature['Args']) {
+    super(owner, args);
+    let it = args.initialTarget;
+    if (it) {
+      this.mode = 'current';
+      this.selectedUrl = it.url;
+      let derived = derivePaneSeeds(normalizeSizeSpec(it.sizeSpec));
+      this.initialPaneFormat = derived.format;
+      this.initialPaneWidth = derived.width;
+      this.initialPaneHeight = derived.height;
+      this.initialPaneKind = derived.kind;
+      this.loadTarget.perform(it.url, it.refType);
+    }
+  }
+
+  private get isEditMode(): boolean {
+    return !!this.args.initialTarget;
+  }
+
+  // 'DONE' until the user diverges from the initial preload, 'ACCEPT' once
+  // they do — matches Zeplin 08B. Non-edit (choose) tabs keep the dynamic
+  // "Insert as …" label.
+  private get ctaLabelOverride(): string | undefined {
+    if (!this.isEditMode) return undefined;
+    return this.dirty ? 'ACCEPT' : 'DONE';
+  }
+
+  private get currentTargetLabel(): string {
+    let t = this.selectedTarget;
+    if (!t) return this.selectedUrl ?? '';
+    if (this.args.refType === 'file') {
+      return fileNameFromUrl(t.id ?? this.selectedUrl ?? '');
+    }
+    return (t as CardDef).title ?? t.id ?? this.selectedUrl ?? '';
+  }
 
   @action
   private onCardSelect(url: string) {
@@ -48,7 +114,7 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
 
   // Restart on every pick so a slow earlier load can't stomp the newer one.
   private loadTarget = restartableTask(
-    async (url: string, refType: 'card' | 'file') => {
+    async (url: string, refType: MarkdownEmbedRefType) => {
       this.selectedUrl = url;
       let result =
         refType === 'card'
@@ -69,6 +135,21 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
     this.args.onInsert(bfm, url);
   }
 
+  @action
+  private onPaneDirtyChange(dirty: boolean) {
+    this.dirty = dirty;
+  }
+
+  @action
+  private startReplace() {
+    this.mode = 'choose';
+  }
+
+  @action
+  private clickRemove() {
+    this.args.onRemove?.();
+  }
+
   <template>
     <div
       class='markdown-embed-chooser-tab-panel'
@@ -76,7 +157,42 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
       ...attributes
     >
       <div class='markdown-embed-chooser-tab-panel__left'>
-        {{#if (eq @refType 'card')}}
+        {{#if (eq this.mode 'current')}}
+          <div
+            class='markdown-embed-chooser-tab-panel__current'
+            data-test-markdown-embed-chooser-current
+          >
+            <span
+              class='markdown-embed-chooser-tab-panel__current-label'
+              data-test-markdown-embed-chooser-current-label
+            >
+              {{this.currentTargetLabel}}
+            </span>
+            <div class='markdown-embed-chooser-tab-panel__current-actions'>
+              <BoxelButton
+                {{on 'click' this.startReplace}}
+                data-test-markdown-embed-chooser-replace
+              >
+                {{#if (eq @refType 'card')}}
+                  Replace Card
+                {{else}}
+                  Replace File
+                {{/if}}
+              </BoxelButton>
+              <BoxelButton
+                @kind='secondary-light'
+                {{on 'click' this.clickRemove}}
+                data-test-markdown-embed-chooser-remove
+              >
+                {{#if (eq @refType 'card')}}
+                  Remove Card
+                {{else}}
+                  Remove File
+                {{/if}}
+              </BoxelButton>
+            </div>
+          </div>
+        {{else if (eq @refType 'card')}}
           <MiniCardChooser
             @onSelect={{this.onCardSelect}}
             @selected={{this.selectedUrl}}
@@ -93,6 +209,12 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
           @target={{this.selectedTarget}}
           @refType={{@refType}}
           @onInsert={{this.handleInsert}}
+          @initialFormat={{this.initialPaneFormat}}
+          @initialWidth={{this.initialPaneWidth}}
+          @initialHeight={{this.initialPaneHeight}}
+          @initialKind={{this.initialPaneKind}}
+          @ctaLabelOverride={{this.ctaLabelOverride}}
+          @onDirtyChange={{this.onPaneDirtyChange}}
         />
       </div>
     </div>
@@ -114,6 +236,63 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
         overflow: hidden;
         background-color: var(--boxel-light);
       }
+      .markdown-embed-chooser-tab-panel__current {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: var(--boxel-sp);
+        height: 100%;
+        padding: var(--boxel-sp);
+        text-align: center;
+      }
+      .markdown-embed-chooser-tab-panel__current-label {
+        font: 600 var(--boxel-font);
+        word-break: break-word;
+      }
+      .markdown-embed-chooser-tab-panel__current-actions {
+        display: flex;
+        gap: var(--boxel-sp-xs);
+      }
     </style>
   </template>
 }
+
+function normalizeSizeSpec(
+  input: BfmSizeSpec | string | undefined,
+): BfmSizeSpec | undefined {
+  if (!input) return undefined;
+  if (typeof input === 'string') {
+    return parseBfmSizeSpec(input) ?? undefined;
+  }
+  return input;
+}
+
+interface PaneSeeds {
+  format?: OptionValue;
+  width?: number | string;
+  height?: number;
+  kind?: 'inline' | 'block';
+}
+
+function derivePaneSeeds(spec: BfmSizeSpec | undefined): PaneSeeds {
+  if (!spec) {
+    return {};
+  }
+  if (spec.format === 'atom') {
+    return { format: 'atom', kind: 'inline' };
+  }
+  if (spec.format === 'embedded') {
+    return { format: 'embedded', kind: 'block' };
+  }
+  if (spec.format === 'isolated') {
+    return { format: 'isolated', kind: 'block' };
+  }
+  // Fitted with optional W×H.
+  return {
+    format: 'custom',
+    width: spec.width,
+    height: spec.height,
+    kind: 'block',
+  };
+}
diff --git a/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
index c5ee94f1de..8a8bad747d 100644
--- a/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
+++ b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
@@ -200,6 +200,114 @@ module('Integration | markdown-embed-chooser-modal', function (hooks) {
     );
   });
 
+  test('edit mode preloads the matching tab in current view', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.editEmbed({
+      refType: 'card',
+      url: mango,
+      sizeSpec: 'embedded',
+    });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Cards tab opens in 'current' mode (the placed target tile, not the
+    // chooser); the files tab still shows its chooser per Zeplin 08B.
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-chooser-current]',
+      )
+      .exists('cards tab shows the current-target tile');
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="file"] [data-test-mini-file-chooser]',
+      )
+      .exists('files tab still mounts its chooser');
+
+    // CTA seeds at DONE (initial preload, nothing edited yet).
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview-cta]',
+      )
+      .hasText('DONE', 'edit-mode CTA reads DONE while the form is clean');
+
+    svc.resolve(undefined);
+    await pending;
+  });
+
+  test('Remove resolves the deferred with { remove: true }', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.editEmbed({
+      refType: 'card',
+      url: mango,
+      sizeSpec: 'embedded',
+    });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    await click('[data-test-markdown-embed-chooser-remove]');
+    let result = await pending;
+    assert.deepEqual(
+      result,
+      { remove: true },
+      'Remove resolves the deferred with the remove sentinel',
+    );
+  });
+
+  test('Replace swaps the current-target tile back to the mini chooser', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.editEmbed({
+      refType: 'card',
+      url: mango,
+      sizeSpec: 'embedded',
+    });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    await click('[data-test-markdown-embed-chooser-replace]');
+
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-chooser-current]',
+      )
+      .doesNotExist('current-target tile is hidden after Replace');
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-mini-card-chooser]',
+      )
+      .exists('mini chooser is exposed for picking a new card');
+
+    svc.resolve(undefined);
+    await pending;
+  });
+
   test('picking a card resolves the deferred with the serialized BFM', async function (assert) {
     await render(
       <template>

From 3c8bd4e5b19a83fb4ae4122b0e03ad533c66f531 Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Fri, 26 Jun 2026 15:42:14 +0700
Subject: [PATCH 03/12] Add toolbar Add/Edit-embed + cursor-aware ref tracking
 (CS-11677)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `extractBfmRefRanges(markdown)` (runtime-common) returns one
  `[from, to]` per BFM directive, skipping code blocks; powers in-editor
  range tracking and in-place replacement.
- `codemirror-context.ts` `SelectionInfo` gains a `currentRef` field; the
  doc-wide range scan re-runs on `docChanged` and the cursor is tested
  against the cached ranges on every selection update.
- `codemirror-editor.gts` toolbar gets a new left-most slot: an Add-embed
  popover (Add a card / Add a file) when the cursor is outside any
  directive, an Edit pencil when it's inside. Add inserts the returned
  BFM at the cursor (block placement gets surrounding newlines); Edit
  replaces the matched range, Remove deletes it.
- The combined chooser modal registers a global bridge
  `_CARDSTACK_MARKDOWN_EMBED_CHOOSER`; `chooseMarkdownEmbed` /
  `editMarkdownEmbed` in runtime-common dispatch to it — mirrors the
  `chooseCard` / `chooseFile` pattern so the base editor reaches the
  host modal without a direct import.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/base/codemirror-editor.gts           | 458 ++++++++++++++----
 .../markdown-embed-chooser/modal.gts          |  20 +
 packages/host/app/lib/codemirror-context.ts   |  79 +--
 .../components/codemirror-editor-test.gts     |  78 +++
 .../tests/unit/bfm-card-references-test.ts    |  68 +++
 .../runtime-common/bfm-card-references.ts     | 146 ++++++
 6 files changed, 733 insertions(+), 116 deletions(-)

diff --git a/packages/base/codemirror-editor.gts b/packages/base/codemirror-editor.gts
index 813a9ecd3b..8b776240ab 100644
--- a/packages/base/codemirror-editor.gts
+++ b/packages/base/codemirror-editor.gts
@@ -13,6 +13,11 @@ import {
   maybeRelativeReference,
   type VirtualNetwork,
 } from '@cardstack/runtime-common';
+import {
+  type BfmRefRange,
+  chooseMarkdownEmbed,
+  editMarkdownEmbed,
+} from '@cardstack/runtime-common/bfm-card-references';
 import {
   type BaseDef,
   type CardDef,
@@ -32,6 +37,8 @@ import ListIcon from '@cardstack/boxel-icons/list';
 import ListOrderedIcon from '@cardstack/boxel-icons/list-ordered';
 import BlockquoteIcon from '@cardstack/boxel-icons/blockquote';
 import LinkIcon from '@cardstack/boxel-icons/link';
+import PlusIcon from '@cardstack/boxel-icons/plus';
+import PencilIcon from '@cardstack/boxel-icons/pencil';
 
 // The CodeMirrorContext type is defined in the host app's lazy-loaded module.
 // We only use it as a type here — the actual module is loaded at runtime via
@@ -63,6 +70,9 @@ interface SelectionInfo {
   from: number;
   to: number;
   formats: SelectionFormats;
+  // BFM directive the cursor is currently inside, if any. Drives the toolbar
+  // swap between the Add-embed popover and the Edit-embed pencil.
+  currentRef?: BfmRefRange;
 }
 
 interface CodeMirrorContext {
@@ -193,7 +203,9 @@ function sameToolbarState(a: SelectionInfo, b: SelectionInfo): boolean {
     a.formats.italic === b.formats.italic &&
     a.formats.code === b.formats.code &&
     a.formats.strikethrough === b.formats.strikethrough &&
-    a.formats.link === b.formats.link
+    a.formats.link === b.formats.link &&
+    a.currentRef?.from === b.currentRef?.from &&
+    a.currentRef?.to === b.currentRef?.to
   );
 }
 
@@ -432,19 +444,84 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
     let f = this.toolbarFormats;
     let pressed = (active: boolean) => (active ? 'true' : 'false');
     return [
-      { testId: 'bold', label: 'Bold', icon: BoldIcon, action: this._wrapBold, active: f.bold, ariaPressed: pressed(f.bold) },
-      { testId: 'italic', label: 'Italic', icon: ItalicIcon, action: this._wrapItalic, active: f.italic, ariaPressed: pressed(f.italic) },
-      { testId: 'strikethrough', label: 'Strikethrough', icon: StrikethroughIcon, action: this._wrapStrikethrough, active: f.strikethrough, ariaPressed: pressed(f.strikethrough) },
-      { testId: 'code', label: 'Code', icon: CodeIcon, action: this._wrapCode, active: f.code, ariaPressed: pressed(f.code) },
-      { testId: 'link', label: 'Link', icon: LinkIcon, action: this._toggleLink, active: f.link, ariaPressed: pressed(f.link) },
+      {
+        testId: 'bold',
+        label: 'Bold',
+        icon: BoldIcon,
+        action: this._wrapBold,
+        active: f.bold,
+        ariaPressed: pressed(f.bold),
+      },
+      {
+        testId: 'italic',
+        label: 'Italic',
+        icon: ItalicIcon,
+        action: this._wrapItalic,
+        active: f.italic,
+        ariaPressed: pressed(f.italic),
+      },
+      {
+        testId: 'strikethrough',
+        label: 'Strikethrough',
+        icon: StrikethroughIcon,
+        action: this._wrapStrikethrough,
+        active: f.strikethrough,
+        ariaPressed: pressed(f.strikethrough),
+      },
+      {
+        testId: 'code',
+        label: 'Code',
+        icon: CodeIcon,
+        action: this._wrapCode,
+        active: f.code,
+        ariaPressed: pressed(f.code),
+      },
+      {
+        testId: 'link',
+        label: 'Link',
+        icon: LinkIcon,
+        action: this._toggleLink,
+        active: f.link,
+        ariaPressed: pressed(f.link),
+      },
       { divider: true },
-      { testId: 'h1', label: 'Heading 1', icon: Heading1Icon, action: this._insertH1 },
-      { testId: 'h2', label: 'Heading 2', icon: Heading2Icon, action: this._insertH2 },
-      { testId: 'h3', label: 'Heading 3', icon: Heading3Icon, action: this._insertH3 },
+      {
+        testId: 'h1',
+        label: 'Heading 1',
+        icon: Heading1Icon,
+        action: this._insertH1,
+      },
+      {
+        testId: 'h2',
+        label: 'Heading 2',
+        icon: Heading2Icon,
+        action: this._insertH2,
+      },
+      {
+        testId: 'h3',
+        label: 'Heading 3',
+        icon: Heading3Icon,
+        action: this._insertH3,
+      },
       { divider: true },
-      { testId: 'bullet-list', label: 'Bullet List', icon: ListIcon, action: this._toggleBulletList },
-      { testId: 'numbered-list', label: 'Numbered List', icon: ListOrderedIcon, action: this._toggleNumberedList },
-      { testId: 'blockquote', label: 'Blockquote', icon: BlockquoteIcon, action: this._toggleBlockquote },
+      {
+        testId: 'bullet-list',
+        label: 'Bullet List',
+        icon: ListIcon,
+        action: this._toggleBulletList,
+      },
+      {
+        testId: 'numbered-list',
+        label: 'Numbered List',
+        icon: ListOrderedIcon,
+        action: this._toggleNumberedList,
+      },
+      {
+        testId: 'blockquote',
+        label: 'Blockquote',
+        icon: BlockquoteIcon,
+        action: this._toggleBlockquote,
+      },
     ];
   }
 
@@ -565,6 +642,122 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
     view.focus();
   };
 
+  // ── Markdown embed chooser (toolbar) ────────────────────────────────────
+
+  @tracked _embedPopoverOpen = false;
+
+  get _currentBfmRef(): BfmRefRange | undefined {
+    return this._selectionInfo?.currentRef;
+  }
+
+  _toggleEmbedPopover = () => {
+    this._embedPopoverOpen = !this._embedPopoverOpen;
+  };
+
+  _openEmbedChooser = async (defaultTab: 'card' | 'file') => {
+    this._embedPopoverOpen = false;
+    let result;
+    try {
+      result = await chooseMarkdownEmbed({ defaultTab });
+    } catch (e) {
+      // Bridge not registered (e.g. card running outside the host) — silently
+      // no-op so the toolbar click doesn't blow up the editor.
+      console.warn('markdown-embed chooser unavailable', e);
+      return;
+    }
+    if (!result || 'remove' in result) {
+      // Cancelled, or { remove: true } returned by mistake (no current ref to
+      // remove in Add mode) — either way, do nothing.
+      return;
+    }
+    this._insertBfm(result.bfm);
+  };
+
+  _openEditEmbed = async () => {
+    let ref = this._currentBfmRef;
+    if (!ref) return;
+    let view = this.editorView;
+    if (!view) return;
+    let result;
+    try {
+      result = await editMarkdownEmbed({
+        refType: ref.refType as 'card' | 'file',
+        url: ref.url,
+        sizeSpec: ref.sizeSpec,
+      });
+    } catch (e) {
+      console.warn('markdown-embed chooser unavailable', e);
+      return;
+    }
+    if (!result) return;
+    if ('remove' in result && result.remove) {
+      this._deleteRange(ref);
+      return;
+    }
+    this._replaceRange(ref, result.bfm);
+  };
+
+  _insertBfm = (bfm: string) => {
+    let view = this.editorView;
+    if (!view) return;
+    let { from } = view.state.selection.main;
+
+    // Inline vs block placement is encoded in the directive's `::` prefix.
+    if (bfm.startsWith('::')) {
+      let line = view.state.doc.lineAt(from);
+      let insertPos = line.to;
+      let prefix = line.text.trim() === '' ? '' : '\n';
+      view.dispatch({
+        changes: { from: insertPos, insert: `${prefix}${bfm}\n` },
+      });
+    } else {
+      view.dispatch({ changes: { from, insert: bfm } });
+    }
+    view.focus();
+
+    let onUpdate = this.args.onUpdate;
+    if (onUpdate) {
+      if (this.saveTimer) {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = null;
+      }
+      onUpdate(view.state.doc.toString());
+    }
+  };
+
+  _replaceRange = (range: BfmRefRange, replacement: string) => {
+    let view = this.editorView;
+    if (!view) return;
+    view.dispatch({
+      changes: { from: range.from, to: range.to, insert: replacement },
+    });
+    view.focus();
+    let onUpdate = this.args.onUpdate;
+    if (onUpdate) {
+      onUpdate(view.state.doc.toString());
+    }
+  };
+
+  _deleteRange = (range: BfmRefRange) => {
+    let view = this.editorView;
+    if (!view) return;
+    // Block directives sit on their own line — extend the delete to swallow
+    // the surrounding newline so we don't leave a blank line behind.
+    let doc = view.state.doc;
+    let from = range.from;
+    let to = range.to;
+    if (range.kind === 'block') {
+      if (doc.sliceString(to, to + 1) === '\n') to += 1;
+      else if (from > 0 && doc.sliceString(from - 1, from) === '\n') from -= 1;
+    }
+    view.dispatch({ changes: { from, to, insert: '' } });
+    view.focus();
+    let onUpdate = this.args.onUpdate;
+    if (onUpdate) {
+      onUpdate(view.state.doc.toString());
+    }
+  };
+
   // ── Card insertion ───────────────────────────────────────────────────────
 
   _insertCardWithFormat = (format: string) => {
@@ -886,6 +1079,60 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
             <span class='toolbar-divider'></span>
           {{/if}}
 
+          {{#if this._currentBfmRef}}
+            <button
+              class='toolbar-btn'
+              data-test-toolbar='edit-embed'
+              type='button'
+              title='Edit embed'
+              aria-label='Edit embed'
+              disabled={{not this.toolbarEnabled}}
+              {{on 'mousedown' this._preventFocusLoss}}
+              {{on 'click' this._openEditEmbed}}
+            ><PencilIcon width='16' height='16' /></button>
+          {{else}}
+            <div class='toolbar-embed-trigger'>
+              <button
+                class='toolbar-btn
+                  {{if this._embedPopoverOpen "toolbar-btn--active"}}'
+                data-test-toolbar='add-embed'
+                type='button'
+                title='Add embed'
+                aria-label='Add embed'
+                aria-haspopup='menu'
+                aria-expanded={{if this._embedPopoverOpen 'true' 'false'}}
+                disabled={{not this.toolbarEnabled}}
+                {{on 'mousedown' this._preventFocusLoss}}
+                {{on 'click' this._toggleEmbedPopover}}
+              ><PlusIcon width='16' height='16' /></button>
+              {{#if this._embedPopoverOpen}}
+                <div
+                  class='toolbar-embed-popover'
+                  role='menu'
+                  data-test-toolbar-embed-popover
+                >
+                  <button
+                    type='button'
+                    role='menuitem'
+                    class='toolbar-embed-popover__item'
+                    data-test-toolbar-embed='card'
+                    {{on 'mousedown' this._preventFocusLoss}}
+                    {{on 'click' (fn this._openEmbedChooser 'card')}}
+                  >Add a card</button>
+                  <button
+                    type='button'
+                    role='menuitem'
+                    class='toolbar-embed-popover__item'
+                    data-test-toolbar-embed='file'
+                    {{on 'mousedown' this._preventFocusLoss}}
+                    {{on 'click' (fn this._openEmbedChooser 'file')}}
+                  >Add a file</button>
+                </div>
+              {{/if}}
+            </div>
+          {{/if}}
+          <span class='toolbar-divider'></span>
+
           {{#each this.toolbarButtons as |btn|}}
             {{#if btn.divider}}
               <span class='toolbar-divider'></span>
@@ -917,89 +1164,89 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
         ></div>
 
         {{! ── Card search popup ── }}
-      {{! template-lint-disable no-pointer-down-event-binding }}
-      {{#if this._cardSearchMode}}
-        <div
-          class='codemirror-card-search'
-          style={{this.menuStyle}}
-          data-test-card-search
-        >
-          <input
-            class='codemirror-card-search-input'
-            placeholder='Search cards or paste URL…'
-            aria-label='Search cards or paste URL'
-            value={{this._cardSearchText}}
-            data-codemirror-card-search-input
-            data-test-card-search-input
-            {{on 'input' this._handleCardSearchInput}}
-            {{on 'keydown' this._handleCardSearchKeydown}}
-          />
-          {{#if this.isSearchLoading}}
-            <div class='codemirror-card-search-loading'>Searching…</div>
-          {{/if}}
-          {{#if this.cardSearchResults.length}}
-            <div
-              class='codemirror-card-search-results'
-              data-test-card-search-results
-            >
-              {{#each this.cardSearchResults as |card index|}}
-                <button
-                  class='codemirror-card-search-result
-                    {{if (eq index this._cardSearchIndex) "selected"}}'
-                  data-test-card-search-result
-                  {{on 'mousedown' this._preventFocusLoss}}
-                  {{on 'click' (fn this._selectCardResult card)}}
-                >
-                  <span class='search-result-title'>{{card.title}}</span>
-                  {{#if card.id}}
-                    <span class='search-result-url'>{{card.id}}</span>
-                  {{/if}}
-                </button>
-              {{/each}}
-            </div>
-          {{/if}}
-        </div>
-      {{/if}}
+        {{! template-lint-disable no-pointer-down-event-binding }}
+        {{#if this._cardSearchMode}}
+          <div
+            class='codemirror-card-search'
+            style={{this.menuStyle}}
+            data-test-card-search
+          >
+            <input
+              class='codemirror-card-search-input'
+              placeholder='Search cards or paste URL…'
+              aria-label='Search cards or paste URL'
+              value={{this._cardSearchText}}
+              data-codemirror-card-search-input
+              data-test-card-search-input
+              {{on 'input' this._handleCardSearchInput}}
+              {{on 'keydown' this._handleCardSearchKeydown}}
+            />
+            {{#if this.isSearchLoading}}
+              <div class='codemirror-card-search-loading'>Searching…</div>
+            {{/if}}
+            {{#if this.cardSearchResults.length}}
+              <div
+                class='codemirror-card-search-results'
+                data-test-card-search-results
+              >
+                {{#each this.cardSearchResults as |card index|}}
+                  <button
+                    class='codemirror-card-search-result
+                      {{if (eq index this._cardSearchIndex) "selected"}}'
+                    data-test-card-search-result
+                    {{on 'mousedown' this._preventFocusLoss}}
+                    {{on 'click' (fn this._selectCardResult card)}}
+                  >
+                    <span class='search-result-title'>{{card.title}}</span>
+                    {{#if card.id}}
+                      <span class='search-result-url'>{{card.id}}</span>
+                    {{/if}}
+                  </button>
+                {{/each}}
+              </div>
+            {{/if}}
+          </div>
+        {{/if}}
 
-      {{! ── Format picker popup ── }}
-      {{! template-lint-disable no-pointer-down-event-binding }}
-      {{#if this._formatPickerCardUrl}}
-        <div
-          class='codemirror-format-picker'
-          style={{this.menuStyle}}
-          data-test-format-picker
-        >
-          <span class='format-picker-label'>
-            Insert "{{this._formatPickerCardTitle}}" as:
-          </span>
-          <div class='format-picker-buttons'>
-            <button
-              class='format-picker-btn'
-              data-test-format-inline
-              {{on 'mousedown' this._preventFocusLoss}}
-              {{on 'click' (fn this._insertCardWithFormat 'inline')}}
-            >
-              Inline
-            </button>
+        {{! ── Format picker popup ── }}
+        {{! template-lint-disable no-pointer-down-event-binding }}
+        {{#if this._formatPickerCardUrl}}
+          <div
+            class='codemirror-format-picker'
+            style={{this.menuStyle}}
+            data-test-format-picker
+          >
+            <span class='format-picker-label'>
+              Insert "{{this._formatPickerCardTitle}}" as:
+            </span>
+            <div class='format-picker-buttons'>
+              <button
+                class='format-picker-btn'
+                data-test-format-inline
+                {{on 'mousedown' this._preventFocusLoss}}
+                {{on 'click' (fn this._insertCardWithFormat 'inline')}}
+              >
+                Inline
+              </button>
+              <button
+                class='format-picker-btn format-picker-btn--primary'
+                data-test-format-block
+                {{on 'mousedown' this._preventFocusLoss}}
+                {{on 'click' (fn this._insertCardWithFormat 'block')}}
+              >
+                Block
+              </button>
+            </div>
             <button
-              class='format-picker-btn format-picker-btn--primary'
-              data-test-format-block
+              class='format-picker-dismiss'
+              data-test-format-picker-dismiss
               {{on 'mousedown' this._preventFocusLoss}}
-              {{on 'click' (fn this._insertCardWithFormat 'block')}}
+              {{on 'click' this._dismissFormatPicker}}
             >
-              Block
+              Cancel
             </button>
           </div>
-          <button
-            class='format-picker-dismiss'
-            data-test-format-picker-dismiss
-            {{on 'mousedown' this._preventFocusLoss}}
-            {{on 'click' this._dismissFormatPicker}}
-          >
-            Cancel
-          </button>
-        </div>
-      {{/if}}
+        {{/if}}
       </div>
 
       {{#if this.livePreview}}
@@ -1389,6 +1636,39 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
           margin: 0 var(--boxel-sp-5xs);
         }
 
+        .toolbar-embed-trigger {
+          position: relative;
+          display: inline-flex;
+        }
+        .toolbar-embed-popover {
+          position: absolute;
+          top: 100%;
+          left: 0;
+          margin-top: 4px;
+          min-width: 140px;
+          background: var(--boxel-light);
+          color: var(--boxel-dark);
+          border: 1px solid var(--boxel-300);
+          border-radius: var(--boxel-border-radius);
+          box-shadow: var(--boxel-deep-box-shadow);
+          padding: var(--boxel-sp-4xs) 0;
+          z-index: 5;
+          display: flex;
+          flex-direction: column;
+        }
+        .toolbar-embed-popover__item {
+          appearance: none;
+          background: none;
+          border: none;
+          text-align: left;
+          padding: var(--boxel-sp-4xs) var(--boxel-sp-xs);
+          font: var(--boxel-font-sm);
+          cursor: pointer;
+        }
+        .toolbar-embed-popover__item:hover {
+          background: var(--boxel-100);
+        }
+
         .codemirror-editor-loading {
           min-height: 120px;
           display: flex;
diff --git a/packages/host/app/components/markdown-embed-chooser/modal.gts b/packages/host/app/components/markdown-embed-chooser/modal.gts
index f30487dfe0..2e3f85e335 100644
--- a/packages/host/app/components/markdown-embed-chooser/modal.gts
+++ b/packages/host/app/components/markdown-embed-chooser/modal.gts
@@ -1,6 +1,8 @@
+import { registerDestructor } from '@ember/destroyable';
 import { hash } from '@ember/helper';
 import { on } from '@ember/modifier';
 import { action } from '@ember/object';
+import type Owner from '@ember/owner';
 import { service } from '@ember/service';
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
@@ -37,6 +39,24 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
   @tracked
   private manualSelectionRequest: MarkdownEmbedChooserRequest | undefined;
 
+  constructor(owner: Owner, args: Signature['Args']) {
+    super(owner, args);
+    // Registers the global bridge `chooseMarkdownEmbed` / `editMarkdownEmbed`
+    // in runtime-common dispatch to. Mirrors the card-chooser/file-chooser
+    // pattern so the base-realm markdown editor can open the modal without a
+    // direct host import.
+    (globalThis as any)._CARDSTACK_MARKDOWN_EMBED_CHOOSER = {
+      chooseCardOrFile: (opts: { defaultTab?: MarkdownEmbedRefType }) =>
+        this.markdownEmbedChooser.chooseCardOrFile(opts),
+      editEmbed: (
+        target: Parameters<MarkdownEmbedChooserService['editEmbed']>[0],
+      ) => this.markdownEmbedChooser.editEmbed(target),
+    };
+    registerDestructor(this, () => {
+      delete (globalThis as any)._CARDSTACK_MARKDOWN_EMBED_CHOOSER;
+    });
+  }
+
   private get request() {
     return this.markdownEmbedChooser.currentRequest;
   }
diff --git a/packages/host/app/lib/codemirror-context.ts b/packages/host/app/lib/codemirror-context.ts
index 8e80c89fbb..7c6d19eed5 100644
--- a/packages/host/app/lib/codemirror-context.ts
+++ b/packages/host/app/lib/codemirror-context.ts
@@ -44,6 +44,11 @@ import {
   keymap,
 } from '@codemirror/view';
 
+import {
+  type BfmRefRange,
+  extractBfmRefRanges,
+} from '@cardstack/runtime-common/bfm-card-references';
+
 // ── Card widget target interface ────────────────────────────────────────────
 
 export interface CardWidgetTarget {
@@ -1043,6 +1048,10 @@ export interface SelectionInfo {
     strikethrough: boolean;
     link: boolean;
   };
+  // BFM `:card[…]` / `::file[…]` directive the cursor head is currently
+  // inside. Undefined when the cursor is outside every directive. Drives
+  // the toolbar's Add-vs-Edit-embed swap.
+  currentRef?: BfmRefRange;
 }
 
 function detectFormats(
@@ -1117,33 +1126,49 @@ function createEditorState(options: CreateEditorStateOptions): EditorState {
       override: [slashSource],
       defaultKeymap: true,
     }),
-    EditorView.updateListener.of((update: ViewUpdate) => {
-      if (update.docChanged) {
-        onDocChange(update.state.doc.toString());
-      }
-      if (
-        onSelectionChange &&
-        (update.selectionSet || update.docChanged || update.focusChanged)
-      ) {
-        let { from, to } = update.state.selection.main;
-        let hasSelection = from !== to;
-        onSelectionChange({
-          hasSelection,
-          hasFocus: update.view.hasFocus,
-          from,
-          to,
-          formats: hasSelection
-            ? detectFormats(update.state, from, to)
-            : {
-                bold: false,
-                italic: false,
-                code: false,
-                strikethrough: false,
-                link: false,
-              },
-        });
-      }
-    }),
+    (() => {
+      // BFM ref ranges cached across selection-only updates — `extractBfmRefRanges`
+      // is a doc-wide string scan, so recompute only when the doc changes.
+      let cachedRanges: BfmRefRange[] = extractBfmRefRanges(content);
+
+      return EditorView.updateListener.of((update: ViewUpdate) => {
+        if (update.docChanged) {
+          let nextDoc = update.state.doc.toString();
+          onDocChange(nextDoc);
+          cachedRanges = extractBfmRefRanges(nextDoc);
+        }
+        if (
+          onSelectionChange &&
+          (update.selectionSet || update.docChanged || update.focusChanged)
+        ) {
+          let { from, to } = update.state.selection.main;
+          let hasSelection = from !== to;
+          let head = update.state.selection.main.head;
+          // A directive owns positions in `[from, to)`. Caret on the closing
+          // `]` (== to) reads as "outside" so post-directive typing isn't
+          // surfaced as edit-this-embed.
+          let currentRef = cachedRanges.find(
+            (r) => head >= r.from && head < r.to,
+          );
+          onSelectionChange({
+            hasSelection,
+            hasFocus: update.view.hasFocus,
+            from,
+            to,
+            formats: hasSelection
+              ? detectFormats(update.state, from, to)
+              : {
+                  bold: false,
+                  italic: false,
+                  code: false,
+                  strikethrough: false,
+                  link: false,
+                },
+            currentRef,
+          });
+        }
+      });
+    })(),
     EditorView.lineWrapping,
   ];
 
diff --git a/packages/host/tests/integration/components/codemirror-editor-test.gts b/packages/host/tests/integration/components/codemirror-editor-test.gts
index eeb1487710..b070e0a3a7 100644
--- a/packages/host/tests/integration/components/codemirror-editor-test.gts
+++ b/packages/host/tests/integration/components/codemirror-editor-test.gts
@@ -1820,4 +1820,82 @@ module('Integration | codemirror-context', function (hooks) {
       delete (globalThis as any).__loadCodeMirror;
     }
   });
+
+  // ── currentRef tracking (BFM directive under cursor) ──
+
+  test('onSelectionChange.currentRef reports the BFM directive under the cursor', async function (assert) {
+    let element = document.createElement('div');
+    document.body.appendChild(element);
+    try {
+      let lastInfo: any = null;
+      let content = 'Inline :card[./mango] then more text';
+      let state = cmContext.createEditorState({
+        content,
+        onDocChange: () => {},
+        onCardTargetsChange: () => {},
+        onOpenCardSearch: () => {},
+        onSelectionChange: (info) => {
+          lastInfo = info;
+        },
+      });
+      let view = new cmContext.EditorView({ state, parent: element });
+
+      let directiveStart = content.indexOf(':card');
+      let directiveEnd = content.indexOf(']') + 1;
+
+      // Inside the directive — currentRef populated.
+      view.dispatch({
+        selection: { anchor: directiveStart + 2, head: directiveStart + 2 },
+      });
+      assert.ok(lastInfo?.currentRef, 'currentRef is set inside the directive');
+      assert.strictEqual(lastInfo.currentRef.refType, 'card');
+      assert.strictEqual(lastInfo.currentRef.url, './mango');
+      assert.strictEqual(lastInfo.currentRef.from, directiveStart);
+      assert.strictEqual(lastInfo.currentRef.to, directiveEnd);
+
+      // Outside the directive — currentRef cleared.
+      view.dispatch({ selection: { anchor: 0, head: 0 } });
+      assert.notOk(
+        lastInfo?.currentRef,
+        'currentRef is undefined outside any directive',
+      );
+
+      view.destroy();
+    } finally {
+      element.remove();
+    }
+  });
+
+  test('currentRef refreshes after a doc edit shifts the range', async function (assert) {
+    let element = document.createElement('div');
+    document.body.appendChild(element);
+    try {
+      let lastInfo: any = null;
+      let state = cmContext.createEditorState({
+        content: ':card[./mango]',
+        onDocChange: () => {},
+        onCardTargetsChange: () => {},
+        onOpenCardSearch: () => {},
+        onSelectionChange: (info) => {
+          lastInfo = info;
+        },
+      });
+      let view = new cmContext.EditorView({ state, parent: element });
+
+      // Prepend text — the directive shifts right by 5 chars.
+      view.dispatch({ changes: { from: 0, to: 0, insert: 'pre: ' } });
+      view.dispatch({ selection: { anchor: 7, head: 7 } });
+
+      assert.ok(lastInfo?.currentRef, 'currentRef detected after the edit');
+      assert.strictEqual(
+        lastInfo.currentRef.from,
+        5,
+        'range start tracks the edit',
+      );
+
+      view.destroy();
+    } finally {
+      element.remove();
+    }
+  });
 });
diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 8e16f658c4..ff61df3c33 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -6,6 +6,7 @@ import {
   extractCardReferenceUrls,
   extractFileReferenceUrls,
   extractBfmReferences,
+  extractBfmRefRanges,
   bfmRefFormatAndSize,
   bfmCardReferenceExtensions,
   bfmExtensionsForKeyword,
@@ -1253,4 +1254,71 @@ module('Unit | bfm-card-references', function () {
       assert.strictEqual(serializeBfmRef('card', ''), '');
     });
   });
+
+  module('extractBfmRefRanges', function () {
+    test('returns source-byte ranges for inline and block refs', function (assert) {
+      let markdown = 'Inline :card[./mango] then\n::file[./photo.jpg]\n';
+      let ranges = extractBfmRefRanges(markdown);
+      assert.strictEqual(ranges.length, 2);
+
+      let inline = ranges[0];
+      assert.strictEqual(inline.kind, 'inline');
+      assert.strictEqual(inline.refType, 'card');
+      assert.strictEqual(inline.url, './mango');
+      assert.strictEqual(
+        markdown.slice(inline.from, inline.to),
+        ':card[./mango]',
+        'inline range round-trips through markdown.slice',
+      );
+
+      let block = ranges[1];
+      assert.strictEqual(block.kind, 'block');
+      assert.strictEqual(block.refType, 'file');
+      assert.strictEqual(block.url, './photo.jpg');
+      assert.strictEqual(
+        markdown.slice(block.from, block.to),
+        '::file[./photo.jpg]',
+        'block range round-trips through markdown.slice',
+      );
+    });
+
+    test('captures the size specifier when present', function (assert) {
+      let markdown = '::card[./mango | tall-tile]';
+      let [range] = extractBfmRefRanges(markdown);
+      assert.strictEqual(range.url, './mango');
+      assert.strictEqual(range.sizeSpec, 'tall-tile');
+      assert.strictEqual(markdown.slice(range.from, range.to), markdown);
+    });
+
+    test('skips refs inside fenced and inline code', function (assert) {
+      let markdown = [
+        '```',
+        '::card[./inside-fence]',
+        '```',
+        'See `:card[./inline-code]` and :card[./real] for real.',
+      ].join('\n');
+      let ranges = extractBfmRefRanges(markdown);
+      assert.strictEqual(ranges.length, 1, 'only the un-coded ref is returned');
+      assert.strictEqual(ranges[0].url, './real');
+    });
+
+    test('emits one range per site (no deduplication)', function (assert) {
+      let markdown = ':card[./mango] then :card[./mango]';
+      let ranges = extractBfmRefRanges(markdown);
+      assert.strictEqual(ranges.length, 2, 'both sites are surfaced');
+      assert.notStrictEqual(ranges[0].from, ranges[1].from);
+    });
+
+    test('sorts by document order', function (assert) {
+      let markdown = '::card[./second]\n:card[./first]'.replace(
+        '::card[./second]\n:card[./first]',
+        ':card[./first] then ::card[./second]',
+      );
+      let ranges = extractBfmRefRanges(markdown);
+      assert.deepEqual(
+        ranges.map((r) => r.url),
+        ['./first', './second'],
+      );
+    });
+  });
 });
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
index f1b11d5474..20b1df4894 100644
--- a/packages/runtime-common/bfm-card-references.ts
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -328,6 +328,152 @@ export function extractBfmReferences(
   return refs;
 }
 
+// ── Markdown embed chooser bridge ──
+//
+// Lets the base-realm markdown editor (in `packages/base/`) open the host-
+// side combined chooser modal without importing host services directly. The
+// host modal registers itself on `globalThis` at mount time; runtime-common
+// exposes the typed accessors below. Mirrors the `chooseCard` / `chooseFile`
+// pattern used by other host-side modals.
+
+export interface MarkdownEmbedResult {
+  refType: 'card' | 'file';
+  url: string;
+  bfm: string;
+}
+
+export type MarkdownEmbedResolution =
+  | MarkdownEmbedResult
+  | { remove: true }
+  | undefined;
+
+export interface MarkdownEmbedInitialTarget {
+  refType: 'card' | 'file';
+  url: string;
+  // Either a pre-parsed `BfmSizeSpec` or the raw specifier text after `|`.
+  sizeSpec?: BfmSizeSpec | string;
+}
+
+export interface MarkdownEmbedChooser {
+  chooseCardOrFile(opts: {
+    defaultTab?: 'card' | 'file';
+  }): Promise<MarkdownEmbedResolution>;
+  editEmbed(
+    target: MarkdownEmbedInitialTarget,
+  ): Promise<MarkdownEmbedResolution>;
+}
+
+const MARKDOWN_EMBED_CHOOSER_KEY = '_CARDSTACK_MARKDOWN_EMBED_CHOOSER';
+
+export async function chooseMarkdownEmbed(
+  opts: { defaultTab?: 'card' | 'file' } = {},
+): Promise<MarkdownEmbedResolution> {
+  let here = globalThis as any;
+  let chooser: MarkdownEmbedChooser | undefined =
+    here[MARKDOWN_EMBED_CHOOSER_KEY];
+  if (!chooser) {
+    throw new Error(
+      `no cardstack markdown-embed chooser is available in this environment`,
+    );
+  }
+  return chooser.chooseCardOrFile(opts);
+}
+
+export async function editMarkdownEmbed(
+  target: MarkdownEmbedInitialTarget,
+): Promise<MarkdownEmbedResolution> {
+  let here = globalThis as any;
+  let chooser: MarkdownEmbedChooser | undefined =
+    here[MARKDOWN_EMBED_CHOOSER_KEY];
+  if (!chooser) {
+    throw new Error(
+      `no cardstack markdown-embed chooser is available in this environment`,
+    );
+  }
+  return chooser.editEmbed(target);
+}
+
+export interface BfmRefRange {
+  kind: 'inline' | 'block';
+  // Half-open byte range into the original markdown string: `markdown.slice(
+  // from, to)` reproduces the directive verbatim. Suitable for a CodeMirror
+  // dispatch that replaces or deletes the directive in place.
+  from: number;
+  to: number;
+  refType: string;
+  // Unresolved URL as written between `[` and `]` — callers resolve against
+  // a base URL when they need the canonical form.
+  url: string;
+  // Raw size specifier after `|` (e.g. `'embedded'`, `'tall-tile'`,
+  // `'w:400 h:200'`). Undefined when the directive has no `|` segment.
+  sizeSpec?: string;
+}
+
+/**
+ * Locates every BFM reference site in `markdown` and returns its source-byte
+ * range, refType, URL, and size specifier (verbatim — no URL resolution).
+ *
+ * Differs from `extractBfmReferences` in two ways: indices are into the
+ * ORIGINAL markdown (not a code-stripped copy), and matches are not
+ * deduplicated — every site is its own range. References inside fenced code
+ * blocks and inline code are skipped.
+ *
+ * Intended for editor-side tooling — cursor-over-ref detection, in-place
+ * replacement, deletion — where every directive needs its own `[from, to]`.
+ */
+export function extractBfmRefRanges(
+  markdown: string,
+  keywords: string[] = ['card', 'file'],
+): BfmRefRange[] {
+  // Collect code regions to skip. Sorted spans in the original markdown.
+  let codeRegions: Array<[number, number]> = [];
+  for (let m of markdown.matchAll(FENCED_CODE_RE)) {
+    codeRegions.push([m.index!, m.index! + m[0].length]);
+  }
+  for (let m of markdown.matchAll(INLINE_CODE_RE)) {
+    codeRegions.push([m.index!, m.index! + m[0].length]);
+  }
+  codeRegions.sort((a, b) => a[0] - b[0]);
+  let isInCode = (pos: number) =>
+    codeRegions.some(([s, e]) => pos >= s && pos < e);
+
+  let ranges: BfmRefRange[] = [];
+
+  for (let keyword of keywords) {
+    let escaped = escapeRegExp(keyword);
+    let blockRe = new RegExp(`^::${escaped}\\[([^\\]]+)\\]`, 'gm');
+    let inlineRe = new RegExp(`(?<!:):${escaped}\\[([^\\]]+)\\]`, 'g');
+
+    for (let match of markdown.matchAll(blockRe)) {
+      if (isInCode(match.index!)) continue;
+      let { url, specifier } = splitBfmContent(match[1]);
+      ranges.push({
+        kind: 'block',
+        from: match.index!,
+        to: match.index! + match[0].length,
+        refType: keyword,
+        url,
+        sizeSpec: specifier,
+      });
+    }
+    for (let match of markdown.matchAll(inlineRe)) {
+      if (isInCode(match.index!)) continue;
+      let { url, specifier } = splitBfmContent(match[1]);
+      ranges.push({
+        kind: 'inline',
+        from: match.index!,
+        to: match.index! + match[0].length,
+        refType: keyword,
+        url,
+        sizeSpec: specifier,
+      });
+    }
+  }
+
+  ranges.sort((a, b) => a.from - b.from);
+  return ranges;
+}
+
 /**
  * Convenience wrapper that extracts only `:card[URL]` / `::card[URL]`
  * references and returns just the resolved URL strings.

From dc129260a906ab5d093c77a1518903dc77d5b782 Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Fri, 26 Jun 2026 16:06:52 +0700
Subject: [PATCH 04/12] Add codemirror-embed-toolbar integration test
 (CS-11677)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

End-to-end coverage of the toolbar → modal → editor round-trip:
- Toolbar surfaces an Add-embed popover (Add a card / Add a file) when
  the cursor is outside a directive.
- Picking a card from the popover lands `:card[url]` at the cursor.
- Placing the cursor inside a directive swaps the toolbar to the Edit
  pencil; Remove on the edit modal deletes the directive in place.

Loads CodeMirrorEditor through the loader (virtual-URL module) and
injects it via precompileTemplate's scope so the integration test can
mount the base-realm editor alongside the host-side modal in the same
render pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../codemirror-embed-toolbar-test.gts         | 283 ++++++++++++++++++
 1 file changed, 283 insertions(+)
 create mode 100644 packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts

diff --git a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
new file mode 100644
index 0000000000..332137c00d
--- /dev/null
+++ b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
@@ -0,0 +1,283 @@
+import { precompileTemplate } from '@ember/template-compilation';
+import {
+  type RenderingTestContext,
+  click,
+  fillIn,
+  render,
+  settled,
+  waitFor,
+  waitUntil,
+} from '@ember/test-helpers';
+
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import { getService } from '@universal-ember/test-support';
+import { provide } from 'ember-provide-consume-context';
+
+import { module, test } from 'qunit';
+
+import {
+  baseRealm,
+  CardContextName,
+  GetCardContextName,
+  GetCardCollectionContextName,
+  GetCardsContextName,
+} from '@cardstack/runtime-common';
+
+import MarkdownEmbedChooserModal from '@cardstack/host/components/markdown-embed-chooser/modal';
+import cmContext from '@cardstack/host/lib/codemirror-context';
+import { getCardCollection } from '@cardstack/host/resources/card-collection';
+import { getCard } from '@cardstack/host/resources/card-resource';
+import type LoaderService from '@cardstack/host/services/loader-service';
+import type StoreService from '@cardstack/host/services/store';
+
+import {
+  setupIntegrationTestRealm,
+  setupLocalIndexing,
+  testRealmURL,
+} from '../../helpers';
+import {
+  CardDef,
+  StringField,
+  contains,
+  field,
+  setupBaseRealm,
+} from '../../helpers/base-realm';
+import { setupMockMatrix } from '../../helpers/mock-matrix';
+import { setupRenderingTest } from '../../helpers/setup';
+
+// The mini choosers + card resources consume host context via @consume.
+class HostContextProvider extends GlimmerComponent<{
+  Blocks: { default: [] };
+}> {
+  @provide(GetCardContextName)
+  get getCardFn() {
+    return getCard;
+  }
+  @provide(GetCardsContextName)
+  get getCardsFn() {
+    let store = getService('store') as StoreService;
+    return store.getSearchResource.bind(store);
+  }
+  @provide(GetCardCollectionContextName)
+  get getCardCollectionFn() {
+    return getCardCollection;
+  }
+  @provide(CardContextName)
+  get cardContext() {
+    return {};
+  }
+  <template>
+    {{! template-lint-disable no-yield-only }}
+    {{yield}}
+  </template>
+}
+
+// Tracked content harness so the editor's onUpdate updates the same
+// `@content` arg we read for assertions.
+class ContentHarness {
+  @tracked content = '';
+  set = (text: string) => {
+    this.content = text;
+  };
+}
+
+async function loadCodeMirrorEditor() {
+  let loader = (getService('loader-service') as LoaderService).loader;
+  let mod = (await loader.import(
+    'https://cardstack.com/base/codemirror-editor',
+  )) as { default: unknown };
+  return mod.default as any;
+}
+
+async function renderEditorAndModal(opts: {
+  CodeMirrorEditor: any;
+  harness: ContentHarness;
+}) {
+  // Static `<template>` in this file can't reference a runtime-loaded
+  // component, so build the layout with precompileTemplate and inject
+  // CodeMirrorEditor through the scope. The modal is a regular host
+  // component import so it can live alongside in static scope.
+  let { CodeMirrorEditor, harness } = opts;
+  await render(
+    precompileTemplate(
+      `
+      <HostContextProvider>
+        <MarkdownEmbedChooserModal />
+        <div class="editor-sized">
+          <CodeMirrorEditor
+            @content={{harness.content}}
+            @onUpdate={{harness.set}}
+          />
+        </div>
+      </HostContextProvider>
+      <style>
+        .editor-sized {
+          width: 600px;
+          height: 240px;
+        }
+      </style>
+    `,
+      {
+        strictMode: true,
+        scope: () => ({
+          HostContextProvider,
+          MarkdownEmbedChooserModal,
+          CodeMirrorEditor,
+          harness,
+        }),
+      },
+    ),
+  );
+}
+
+module('Integration | codemirror embed toolbar', function (hooks) {
+  setupRenderingTest(hooks);
+  setupBaseRealm(hooks);
+  setupLocalIndexing(hooks);
+
+  let mockMatrixUtils = setupMockMatrix(hooks, {
+    loggedInAs: '@testuser:localhost',
+    activeRealms: [baseRealm.url, testRealmURL],
+    autostart: true,
+  });
+
+  // The base codemirror-editor lazy-loads its host-side CodeMirror context
+  // via `globalThis.__loadCodeMirror`. Wire it to the real context so the
+  // editor mounts (instead of the loading placeholder).
+  hooks.beforeEach(function () {
+    (globalThis as any).__loadCodeMirror = async () => cmContext;
+  });
+  hooks.afterEach(function () {
+    delete (globalThis as any).__loadCodeMirror;
+  });
+
+  let CodeMirrorEditor: any;
+
+  hooks.beforeEach(async function () {
+    CodeMirrorEditor = await loadCodeMirrorEditor();
+  });
+
+  const mango = `${testRealmURL}books/mango`;
+
+  hooks.beforeEach(async function (this: RenderingTestContext) {
+    class Book extends CardDef {
+      static displayName = 'Book';
+      @field title = contains(StringField);
+    }
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      realmURL: testRealmURL,
+      contents: {
+        'book.gts': { Book },
+        'books/mango.json': new Book({ title: 'Mango' }),
+      },
+    });
+    await getService('realm').login(testRealmURL);
+  });
+
+  test('toolbar shows Add-embed by default; popover opens Cards/Files items', async function (assert) {
+    let harness = new ContentHarness();
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-codemirror-editor]', { timeout: 5000 });
+    await waitFor('[data-test-toolbar="add-embed"]', { timeout: 5000 });
+    assert
+      .dom('[data-test-toolbar="add-embed"]')
+      .exists('Add embed lives in the toolbar when no directive is focused');
+    assert
+      .dom('[data-test-toolbar-embed-popover]')
+      .doesNotExist('popover is closed by default');
+
+    await click('[data-test-toolbar="add-embed"]');
+    assert.dom('[data-test-toolbar-embed-popover]').exists();
+    assert
+      .dom('[data-test-toolbar-embed="card"]')
+      .hasText('Add a card', 'first menu item targets the Cards tab');
+    assert
+      .dom('[data-test-toolbar-embed="file"]')
+      .hasText('Add a file', 'second menu item targets the Files tab');
+  });
+
+  test('picking a card from the popover inserts `:card[URL]` at the cursor', async function (assert) {
+    let harness = new ContentHarness();
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-toolbar="add-embed"]', { timeout: 5000 });
+    await click('[data-test-toolbar="add-embed"]');
+    await click('[data-test-toolbar-embed="card"]');
+
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    await fillIn(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      'Mango',
+    );
+    await waitFor(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mango}"]`,
+      { timeout: 5000 },
+    );
+    await click(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mango}"]`,
+    );
+
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    await click('[data-test-markdown-embed-preview-cta]');
+
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+    await settled();
+    assert.strictEqual(
+      harness.content,
+      `:card[${mango}]`,
+      'editor content carries the inserted BFM directive',
+    );
+  });
+
+  test('cursor over a directive swaps the toolbar to Edit; Remove deletes the ref', async function (assert) {
+    let harness = new ContentHarness();
+    harness.content = `:card[${mango}]`;
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-codemirror-editor] .cm-content', {
+      timeout: 5000,
+    });
+
+    // Drop the cursor inside the directive by dispatching against the
+    // CodeMirror view (the contenteditable .cm-content sits on the view).
+    let editor = document.querySelector(
+      '[data-test-codemirror-editor] .cm-editor',
+    ) as HTMLElement | null;
+    // @ts-ignore — `cmView` is attached by CodeMirror to the editor root.
+    let view = editor?.cmView?.view;
+    view?.focus();
+    view?.dispatch({ selection: { anchor: 3, head: 3 } });
+
+    await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
+    assert
+      .dom('[data-test-toolbar="edit-embed"]')
+      .exists(
+        'Edit pencil replaces the Add popover when the cursor is inside a directive',
+      );
+
+    await click('[data-test-toolbar="edit-embed"]');
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    assert
+      .dom('[data-test-markdown-embed-chooser-current]')
+      .exists('edit modal opens with the current-target tile');
+
+    await click('[data-test-markdown-embed-chooser-remove]');
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+    await settled();
+    assert.strictEqual(
+      harness.content,
+      '',
+      'Remove deletes the directive from the source',
+    );
+  });
+});

From 54f8bda6a1beeac619f676875163c95e2f6055bc Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Fri, 26 Jun 2026 16:11:08 +0700
Subject: [PATCH 05/12] Add acceptance test for markdown embed chooser
 (CS-11675/76/77)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drives the full operator-mode flow: interact submode → open a Note card
with a RichMarkdownField → switch to edit → click Add embed in the
markdown toolbar → pick a card from the combined chooser modal → assert
the editor's source now carries the inserted `:card[url]` directive.
Second test asserts cursor-inside-directive swaps the toolbar to the
Edit pencil and opens the modal on the current-target tile.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../markdown-embed-chooser-test.gts           | 251 ++++++++++++++++++
 1 file changed, 251 insertions(+)
 create mode 100644 packages/host/tests/acceptance/markdown-embed-chooser-test.gts

diff --git a/packages/host/tests/acceptance/markdown-embed-chooser-test.gts b/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
new file mode 100644
index 0000000000..0b88ace7ab
--- /dev/null
+++ b/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
@@ -0,0 +1,251 @@
+import {
+  click,
+  fillIn,
+  settled,
+  waitFor,
+  waitUntil,
+} from '@ember/test-helpers';
+
+import { module, test } from 'qunit';
+
+import {
+  setupAuthEndpoints,
+  setupLocalIndexing,
+  setupOnSave,
+  setupRealmCacheTeardown,
+  setupUserSubscription,
+  setupAcceptanceTestRealm,
+  SYSTEM_CARD_FIXTURE_CONTENTS,
+  testRealmURL,
+  visitOperatorMode,
+  withCachedRealmSetup,
+} from '../helpers';
+import { setupMockMatrix } from '../helpers/mock-matrix';
+import { setupApplicationTest } from '../helpers/setup';
+
+module('Acceptance | markdown embed chooser modal', function (hooks) {
+  setupApplicationTest(hooks);
+  setupLocalIndexing(hooks);
+  setupOnSave(hooks);
+  setupRealmCacheTeardown(hooks);
+
+  let mockMatrixUtils = setupMockMatrix(hooks, {
+    loggedInAs: '@testuser:localhost',
+    activeRealms: [testRealmURL],
+  });
+
+  const noteId = `${testRealmURL}Note/welcome`;
+  const mangoId = `${testRealmURL}Pet/mango`;
+
+  hooks.beforeEach(async function () {
+    let { createAndJoinRoom } = mockMatrixUtils;
+    createAndJoinRoom({
+      sender: '@testuser:localhost',
+      name: 'room-test',
+    });
+    setupUserSubscription();
+    setupAuthEndpoints();
+
+    // Realm contents:
+    // - `note.gts` defines a Note card with a RichMarkdownField body. The
+    //   edit template renders the field, which mounts the CodeMirror editor
+    //   + the toolbar we're testing.
+    // - `pet.gts` is the card we'll embed via the chooser.
+    // - One Note instance ("Welcome") starts empty; one Pet instance
+    //   ("Mango") is the row we pick in the chooser.
+    await withCachedRealmSetup(async () =>
+      setupAcceptanceTestRealm({
+        mockMatrixUtils,
+        contents: {
+          ...SYSTEM_CARD_FIXTURE_CONTENTS,
+          'note.gts': `
+              import { CardDef, Component, contains, field, StringField } from 'https://cardstack.com/base/card-api';
+              import { RichMarkdownField } from 'https://cardstack.com/base/rich-markdown';
+              export class Note extends CardDef {
+                static displayName = 'Note';
+                @field title = contains(StringField);
+                @field body = contains(RichMarkdownField);
+                static isolated = class Isolated extends Component<typeof this> {
+                  <template>
+                    <div data-test-note-isolated>
+                      <h1 data-test-note-title><@fields.title /></h1>
+                      <@fields.body />
+                    </div>
+                  </template>
+                };
+                static edit = class Edit extends Component<typeof this> {
+                  <template>
+                    <div data-test-note-edit>
+                      <h1 data-test-note-title><@fields.title /></h1>
+                      <@fields.body />
+                    </div>
+                  </template>
+                };
+              }
+            `,
+          'pet.gts': `
+              import { CardDef, Component, contains, field, StringField } from 'https://cardstack.com/base/card-api';
+              export class Pet extends CardDef {
+                static displayName = 'Pet';
+                @field name = contains(StringField);
+                @field cardTitle = contains(StringField, {
+                  computeVia: function () {
+                    return this.name;
+                  },
+                });
+                static atom = class Atom extends Component<typeof this> {
+                  <template>
+                    <span data-test-pet-atom>{{@model.name}}</span>
+                  </template>
+                };
+              }
+            `,
+          'Pet/mango.json': {
+            data: {
+              attributes: { name: 'Mango', cardTitle: 'Mango' },
+              meta: {
+                adoptsFrom: { module: '../pet', name: 'Pet' },
+              },
+            },
+          },
+          'Note/welcome.json': {
+            data: {
+              attributes: {
+                title: 'Welcome',
+                cardTitle: 'Welcome',
+                body: { content: '' },
+              },
+              meta: {
+                adoptsFrom: { module: '../note', name: 'Note' },
+              },
+            },
+          },
+        },
+      }),
+    );
+  });
+
+  test('opens via the toolbar Add-embed popover and inserts the picked card as a BFM directive', async function (assert) {
+    await visitOperatorMode({
+      stacks: [
+        [
+          {
+            id: noteId,
+            format: 'isolated',
+          },
+        ],
+      ],
+    });
+
+    // Switch the open card to edit mode so the RichMarkdownField renders
+    // its CodeMirror editor (with the toolbar we are exercising).
+    await click(`[data-test-operator-mode-stack="0"] [data-test-edit-button]`);
+    await waitFor(
+      `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor]`,
+      { timeout: 5000 },
+    );
+    await waitFor('[data-test-toolbar="add-embed"]', { timeout: 5000 });
+
+    // Open the Add-embed popover and pick the Cards menu item.
+    await click('[data-test-toolbar="add-embed"]');
+    assert
+      .dom('[data-test-toolbar-embed-popover]')
+      .exists('popover renders with the two menu items');
+    await click('[data-test-toolbar-embed="card"]');
+
+    // The combined chooser modal opens on the Cards tab.
+    await waitFor('[data-test-markdown-embed-chooser-modal]', {
+      timeout: 5000,
+    });
+    assert
+      .dom('[data-test-markdown-embed-chooser-tab="card"]')
+      .hasAttribute('aria-selected', 'true', 'cards tab is the default');
+
+    // Search for Mango, click the row, wait for the pane to unlock, insert.
+    await fillIn(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      'Mango',
+    );
+    await waitFor(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mangoId}"]`,
+      { timeout: 5000 },
+    );
+    await click(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mangoId}"]`,
+    );
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    await click('[data-test-markdown-embed-preview-cta]');
+
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+    await settled();
+
+    // Read the editor's doc directly: the toolbar dispatched a CM change
+    // and the source now carries the BFM directive at the cursor position.
+    let editorEl = document.querySelector(
+      `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor] .cm-editor`,
+    ) as HTMLElement | null;
+    // @ts-ignore — CodeMirror attaches `cmView` to the editor root.
+    let docText = editorEl?.cmView?.view?.state.doc.toString();
+    assert.strictEqual(
+      docText,
+      `:card[${mangoId}]`,
+      'source carries the inserted inline atom directive',
+    );
+  });
+
+  test('cursor inside an existing directive swaps the toolbar to the Edit pencil', async function (assert) {
+    // Open the card on the stack, then patch the body content to a pre-
+    // existing :card[...] directive so the cursor lands inside it once the
+    // editor mounts.
+    await visitOperatorMode({
+      stacks: [
+        [
+          {
+            id: noteId,
+            format: 'isolated',
+          },
+        ],
+      ],
+    });
+    await click(`[data-test-operator-mode-stack="0"] [data-test-edit-button]`);
+    await waitFor(
+      `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor]`,
+      { timeout: 5000 },
+    );
+
+    // Inject the directive directly into the CodeMirror view, then drop
+    // the cursor inside it.
+    let editorEl = document.querySelector(
+      `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor] .cm-editor`,
+    ) as HTMLElement | null;
+    // @ts-ignore — CodeMirror attaches `cmView` to the editor root.
+    let view = editorEl?.cmView?.view;
+    assert.ok(view, 'codemirror view is reachable');
+    view.focus();
+    view.dispatch({
+      changes: { from: 0, insert: `:card[${mangoId}]` },
+    });
+    view.dispatch({ selection: { anchor: 3, head: 3 } });
+
+    await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
+    assert
+      .dom('[data-test-toolbar="edit-embed"]')
+      .exists('Edit pencil replaces the Add popover when cursor is inside');
+
+    await click('[data-test-toolbar="edit-embed"]');
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    assert
+      .dom('[data-test-markdown-embed-chooser-current]')
+      .exists('edit modal opens on the current-target tile');
+
+    // Cancel via the X to leave the source untouched.
+    await click('[data-test-close-modal]');
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+  });
+});

From bfa4a9c42ddd80f31aa02af3b669a3a86badd148 Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Fri, 26 Jun 2026 16:37:41 +0700
Subject: [PATCH 06/12] Fix issues surfaced by running the chooser tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- externals.ts: shim `@cardstack/runtime-common/bfm-card-references` as
  an async module so the base-realm editor (and anything else that
  reaches the subpath through the loader) resolves it via the virtual
  network — the loader has no way to fetch it otherwise.
- codemirror-editor.gts: drop `disabled={{not this.toolbarEnabled}}`
  from the Add-embed and Edit-embed buttons; both open modals that own
  their own state, so editor focus isn't a prerequisite.
- pane.gts: new `initialTargetUrl` arg. Without it, in edit mode the
  dirty check briefly flips true once the resolved target instance
  lands (constructor records `undefined`, then `args.target?.id` changes
  to the URL), making the CTA read ACCEPT before the user edits
  anything. Tab-panel passes the URL through verbatim.
- Tests: switch from `editor.cmView.view` (not a public CM6 surface) to
  `cmContext.EditorView.findFromDOM(editor)`; fix one unit-test
  assertion where the block-ref form needed to sit at the start of a
  line for the `^::` regex to match.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/base/codemirror-editor.gts              |  2 --
 .../components/markdown-embed-chooser/pane.gts   | 10 +++++++++-
 .../markdown-embed-chooser/tab-panel.gts         |  1 +
 packages/host/app/lib/externals.ts               |  4 ++++
 .../acceptance/markdown-embed-chooser-test.gts   | 16 +++++++++-------
 .../components/codemirror-embed-toolbar-test.gts |  6 +++---
 .../host/tests/unit/bfm-card-references-test.ts  |  5 ++---
 7 files changed, 28 insertions(+), 16 deletions(-)

diff --git a/packages/base/codemirror-editor.gts b/packages/base/codemirror-editor.gts
index 8b776240ab..ab4f7a0fb4 100644
--- a/packages/base/codemirror-editor.gts
+++ b/packages/base/codemirror-editor.gts
@@ -1086,7 +1086,6 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
               type='button'
               title='Edit embed'
               aria-label='Edit embed'
-              disabled={{not this.toolbarEnabled}}
               {{on 'mousedown' this._preventFocusLoss}}
               {{on 'click' this._openEditEmbed}}
             ><PencilIcon width='16' height='16' /></button>
@@ -1101,7 +1100,6 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
                 aria-label='Add embed'
                 aria-haspopup='menu'
                 aria-expanded={{if this._embedPopoverOpen 'true' 'false'}}
-                disabled={{not this.toolbarEnabled}}
                 {{on 'mousedown' this._preventFocusLoss}}
                 {{on 'click' this._toggleEmbedPopover}}
               ><PlusIcon width='16' height='16' /></button>
diff --git a/packages/host/app/components/markdown-embed-chooser/pane.gts b/packages/host/app/components/markdown-embed-chooser/pane.gts
index 5b56b65cc3..bd30e4c2cf 100644
--- a/packages/host/app/components/markdown-embed-chooser/pane.gts
+++ b/packages/host/app/components/markdown-embed-chooser/pane.gts
@@ -112,6 +112,11 @@ interface Signature {
     initialWidth?: number | string;
     initialHeight?: number;
     initialKind?: 'inline' | 'block';
+    // URL of the placed target the user is editing. Distinct from
+    // `target.id` because the resolved instance arrives asynchronously —
+    // without this, the dirty check would briefly flip true as soon as the
+    // target loads.
+    initialTargetUrl?: string;
     // Fired with `true` once the pane's state diverges from the initial
     // preload (and back to `false` if it matches again). The parent uses this
     // to flip the CTA label between 'DONE' and 'ACCEPT' in edit mode.
@@ -171,7 +176,10 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
     this.initialKind = this.kind;
     this.initialWidthInput = this.widthInput;
     this.initialHeightInput = this.heightInput;
-    this.initialTargetUrl = args.target?.id;
+    // `initialTargetUrl` arg wins over `args.target?.id` because the resolved
+    // instance is loaded asynchronously — at construction time the parent
+    // already knows the URL but the store has not yet returned the instance.
+    this.initialTargetUrl = args.initialTargetUrl ?? args.target?.id;
   }
 
   private get selectedOption(): FormatOption {
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
index 43220f85f3..a97aa24a09 100644
--- a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
@@ -213,6 +213,7 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
           @initialWidth={{this.initialPaneWidth}}
           @initialHeight={{this.initialPaneHeight}}
           @initialKind={{this.initialPaneKind}}
+          @initialTargetUrl={{@initialTarget.url}}
           @ctaLabelOverride={{this.ctaLabelOverride}}
           @onDirtyChange={{this.onPaneDirtyChange}}
         />
diff --git a/packages/host/app/lib/externals.ts b/packages/host/app/lib/externals.ts
index 19719801b0..c0dc99cde1 100644
--- a/packages/host/app/lib/externals.ts
+++ b/packages/host/app/lib/externals.ts
@@ -202,6 +202,10 @@ export function shimExternals(virtualNetwork: VirtualNetwork) {
     id: '@cardstack/runtime-common/marked-sync',
     resolve: () => import('@cardstack/runtime-common/marked-sync'),
   });
+  virtualNetwork.shimAsyncModule({
+    id: '@cardstack/runtime-common/bfm-card-references',
+    resolve: () => import('@cardstack/runtime-common/bfm-card-references'),
+  });
 
   shimModulesForLiveTests(virtualNetwork);
 
diff --git a/packages/host/tests/acceptance/markdown-embed-chooser-test.gts b/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
index 0b88ace7ab..2caab53995 100644
--- a/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
+++ b/packages/host/tests/acceptance/markdown-embed-chooser-test.gts
@@ -8,6 +8,8 @@ import {
 
 import { module, test } from 'qunit';
 
+import cmContext from '@cardstack/host/lib/codemirror-context';
+
 import {
   setupAuthEndpoints,
   setupLocalIndexing,
@@ -188,8 +190,9 @@ module('Acceptance | markdown embed chooser modal', function (hooks) {
     let editorEl = document.querySelector(
       `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor] .cm-editor`,
     ) as HTMLElement | null;
-    // @ts-ignore — CodeMirror attaches `cmView` to the editor root.
-    let docText = editorEl?.cmView?.view?.state.doc.toString();
+    let docText = editorEl
+      ? cmContext.EditorView.findFromDOM(editorEl)?.state.doc.toString()
+      : undefined;
     assert.strictEqual(
       docText,
       `:card[${mangoId}]`,
@@ -222,14 +225,13 @@ module('Acceptance | markdown embed chooser modal', function (hooks) {
     let editorEl = document.querySelector(
       `[data-test-stack-card="${noteId}"] [data-test-codemirror-editor] .cm-editor`,
     ) as HTMLElement | null;
-    // @ts-ignore — CodeMirror attaches `cmView` to the editor root.
-    let view = editorEl?.cmView?.view;
+    let view = editorEl ? cmContext.EditorView.findFromDOM(editorEl) : null;
     assert.ok(view, 'codemirror view is reachable');
-    view.focus();
-    view.dispatch({
+    view!.focus();
+    view!.dispatch({
       changes: { from: 0, insert: `:card[${mangoId}]` },
     });
-    view.dispatch({ selection: { anchor: 3, head: 3 } });
+    view!.dispatch({ selection: { anchor: 3, head: 3 } });
 
     await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
     assert
diff --git a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
index 332137c00d..3d8b736e2d 100644
--- a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
+++ b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
@@ -247,12 +247,12 @@ module('Integration | codemirror embed toolbar', function (hooks) {
     });
 
     // Drop the cursor inside the directive by dispatching against the
-    // CodeMirror view (the contenteditable .cm-content sits on the view).
+    // CodeMirror view. `EditorView.findFromDOM` walks up from any node
+    // under the editor; the cmContext exposes the constructor.
     let editor = document.querySelector(
       '[data-test-codemirror-editor] .cm-editor',
     ) as HTMLElement | null;
-    // @ts-ignore — `cmView` is attached by CodeMirror to the editor root.
-    let view = editor?.cmView?.view;
+    let view = editor ? cmContext.EditorView.findFromDOM(editor) : null;
     view?.focus();
     view?.dispatch({ selection: { anchor: 3, head: 3 } });
 
diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index ff61df3c33..858f2d1e03 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -1310,9 +1310,8 @@ module('Unit | bfm-card-references', function () {
     });
 
     test('sorts by document order', function (assert) {
-      let markdown = '::card[./second]\n:card[./first]'.replace(
-        '::card[./second]\n:card[./first]',
-        ':card[./first] then ::card[./second]',
+      let markdown = [':card[./first] inline', '', '::card[./second]'].join(
+        '\n',
       );
       let ranges = extractBfmRefRanges(markdown);
       assert.deepEqual(

From d3c567d31eddaacddedb6a36094a0e5edf1fc3c1 Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Fri, 26 Jun 2026 21:43:29 +0700
Subject: [PATCH 07/12] Refine markdown embed chooser: tab pills + matched
 chooser styling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move the card/file tab control from a full-width strip into a segmented
pill control (tab-pills.gts) that sits at the top of each panel's left
search column, directly above its search bar. Both tabpanels stay mounted
so each tab keeps its search query, highlighted row, scroll position, and
the pane's size/format selection across a switch.

Harmonize the two mini choosers so toggling tabs no longer jumps in scale:
both now render their chrome and list rows at the shared 14px
(--boxel-font-sm) size — the file tree (was 12px), the card chooser
baseline, and the mini "Search Results" summary (was 16px). Each list
keeps its own natural weight.

Give the card chooser's search header a small bottom inset so the bar's
2px focus outline is no longer painted over by the results list below it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../components/card-chooser/mini/index.gts    |   7 +-
 .../components/card-search/panel-content.gts  |   5 +
 .../components/card-search/sheet-results.gts  |  48 +++++---
 .../components/file-chooser/mini/index.gts    |  20 +++-
 .../markdown-embed-chooser/modal.gts          |  32 ++++-
 .../markdown-embed-chooser/pane.gts           |  55 +++------
 .../markdown-embed-chooser/tab-panel.gts      | 109 +++++++++++++++---
 .../markdown-embed-chooser/tab-pills.gts      |  94 +++++++++++++++
 .../markdown-embed-chooser/tabs.gts           |  78 ++-----------
 9 files changed, 290 insertions(+), 158 deletions(-)
 create mode 100644 packages/host/app/components/markdown-embed-chooser/tab-pills.gts

diff --git a/packages/host/app/components/card-chooser/mini/index.gts b/packages/host/app/components/card-chooser/mini/index.gts
index f40aae5e95..6dc24bd350 100644
--- a/packages/host/app/components/card-chooser/mini/index.gts
+++ b/packages/host/app/components/card-chooser/mini/index.gts
@@ -82,10 +82,15 @@ export default class MiniCardChooser extends Component<Signature> {
         height: 100%;
         min-height: 0;
         background-color: var(--boxel-light);
+        /* Share the file chooser's compact scale so the two lists match when
+           toggling tabs in the markdown embed chooser. */
+        font: var(--boxel-font-sm);
       }
       .mini-card-chooser__header {
         flex: 0 0 auto;
-        padding: var(--boxel-sp-xs) var(--boxel-sp-xs) 0;
+        /* Small bottom inset so the search bar's 2px focus outline isn't
+           painted over by the results list sitting directly below it. */
+        padding: var(--boxel-sp-xs) var(--boxel-sp-xs) var(--boxel-sp-4xs);
       }
       /* Pill-shaped, design-matched bar height. SearchBar's defaults are
          tuned for the full search-sheet (50px tall, generous focus ring);
diff --git a/packages/host/app/components/card-search/panel-content.gts b/packages/host/app/components/card-search/panel-content.gts
index d0b05585b3..469e423a38 100644
--- a/packages/host/app/components/card-search/panel-content.gts
+++ b/packages/host/app/components/card-search/panel-content.gts
@@ -461,6 +461,11 @@ export default class PanelContent extends Component<Signature> {
       .search-sheet-content.mini :deep(.search-result-header) {
         padding-block: var(--boxel-sp-xs);
       }
+      /* The summary is 16px bold in the full sheet; in the mini envelope drop
+         it to the chooser's shared 14px scale (weight stays 600). */
+      .search-sheet-content.mini :deep(.search-result-header .summary) {
+        font: 600 var(--boxel-font-sm);
+      }
       /* Summary + Sort sit on one row, with the Sort dropdown shrunk to
          fit its label rather than padded to a comfortable touch target. */
       .search-sheet-content.mini :deep(.search-result-header .controls) {
diff --git a/packages/host/app/components/card-search/sheet-results.gts b/packages/host/app/components/card-search/sheet-results.gts
index 2514ae2afb..a2224133e6 100644
--- a/packages/host/app/components/card-search/sheet-results.gts
+++ b/packages/host/app/components/card-search/sheet-results.gts
@@ -205,6 +205,20 @@ export default class SheetResults extends Component<Signature> {
     return [...new Set(urls)];
   }
 
+  // The global summary + Sort row. Hidden in the mini chooser's default
+  // Recents view (empty search): there the Recents section supplies its own
+  // header (label + count), and the design shows no Sort control until the
+  // user actually searches. Unaffected for the full search sheet.
+  private get showGlobalHeader(): boolean {
+    if (!this.args.showHeader || this.args.isCompact) {
+      return false;
+    }
+    if (this.args.variant === 'mini' && this.args.isSearchKeyEmpty) {
+      return false;
+    }
+    return true;
+  }
+
   private get hasNoResults(): boolean {
     return (
       this.sections.length === 0 &&
@@ -230,24 +244,22 @@ export default class SheetResults extends Component<Signature> {
   }
 
   <template>
-    {{#if @showHeader}}
-      {{#unless @isCompact}}
-        <SearchResultHeader
-          @summaryText={{this.summaryText}}
-          @viewOptions={{this.VIEW_OPTIONS}}
-          @activeViewId={{@activeViewId}}
-          @activeSort={{@activeSort}}
-          @sortOptions={{this.SORT_OPTIONS}}
-          @onChangeView={{@onChangeView}}
-          @onChangeSort={{@onChangeSort}}
-          @multiSelect={{@multiSelect}}
-          @selectedCards={{@selectedCards}}
-          @allCards={{this.allCards}}
-          @onSelectAll={{@onSelectAll}}
-          @onDeselectAll={{@onDeselectAll}}
-          @hideViewSelector={{eq @variant 'mini'}}
-        />
-      {{/unless}}
+    {{#if this.showGlobalHeader}}
+      <SearchResultHeader
+        @summaryText={{this.summaryText}}
+        @viewOptions={{this.VIEW_OPTIONS}}
+        @activeViewId={{@activeViewId}}
+        @activeSort={{@activeSort}}
+        @sortOptions={{this.SORT_OPTIONS}}
+        @onChangeView={{@onChangeView}}
+        @onChangeSort={{@onChangeSort}}
+        @multiSelect={{@multiSelect}}
+        @selectedCards={{@selectedCards}}
+        @allCards={{this.allCards}}
+        @onSelectAll={{@onSelectAll}}
+        @onDeselectAll={{@onDeselectAll}}
+        @hideViewSelector={{eq @variant 'mini'}}
+      />
     {{/if}}
 
     {{! Handle empty URL search state — only after loading completes }}
diff --git a/packages/host/app/components/file-chooser/mini/index.gts b/packages/host/app/components/file-chooser/mini/index.gts
index 11160c059c..29b7a04176 100644
--- a/packages/host/app/components/file-chooser/mini/index.gts
+++ b/packages/host/app/components/file-chooser/mini/index.gts
@@ -16,10 +16,15 @@ import FileChooser, { type FileChooserRealm } from '../panel';
 interface Signature {
   Element: HTMLDivElement;
   Args: {
-    // Fired with the absolute URL of the file the user picks from the tree or
-    // finishes uploading. The hosting container decides what to do with it
-    // (this primitive never confirms or dismisses on its own).
+    // Fired with the absolute URL of the file the user confirms (Enter on a
+    // tree row) or finishes uploading. The hosting container decides what to do
+    // with it (this primitive never confirms or dismisses on its own).
     onSelect: (url: string) => void;
+    // Fired on a single-click highlight of a tree row, before confirmation.
+    // Lets a host preview the highlighted file without committing to it — the
+    // card chooser previews on a single click, so this keeps the file chooser
+    // symmetric for consumers that want the same.
+    onHighlight?: (url: string) => void;
     // Workspace to open on first render. Read once at mount; later parent
     // updates are ignored. Defaults to the first known realm.
     initialRealmURL?: string;
@@ -72,8 +77,11 @@ export default class MiniFileChooser extends Component<Signature> {
       return;
     }
     this.userSelectedFile = path;
-    // Deliberately does NOT call this.args.onSelect — that only happens on
-    // confirmation (Enter) to avoid double-fire.
+    // Single click highlights the row and previews it via onHighlight, but does
+    // NOT call onSelect — that's reserved for confirmation (Enter) so a host
+    // can distinguish "previewing" from "committing".
+    let url = new RealmPaths(realm.url).fileURL(path);
+    this.args.onHighlight?.(url.href);
   }
 
   @action
@@ -211,7 +219,7 @@ export default class MiniFileChooser extends Component<Signature> {
         padding: var(--boxel-sp-xs);
         background-color: var(--boxel-light);
         color: var(--boxel-dark);
-        font: var(--boxel-font-xs);
+        font: var(--boxel-font-sm);
       }
       .mini-file-chooser__field {
         display: flex;
diff --git a/packages/host/app/components/markdown-embed-chooser/modal.gts b/packages/host/app/components/markdown-embed-chooser/modal.gts
index 2e3f85e335..57e219c6fa 100644
--- a/packages/host/app/components/markdown-embed-chooser/modal.gts
+++ b/packages/host/app/components/markdown-embed-chooser/modal.gts
@@ -121,7 +121,7 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
     {{#if this.request}}
       <ModalContainer
         class='markdown-embed-chooser-modal'
-        @title='Embed a card or file'
+        @title=''
         @onClose={{this.handleClose}}
         @size='large'
         @centered={{true}}
@@ -134,13 +134,12 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
         data-test-markdown-embed-chooser-modal
       >
         <:content>
-          <Tabs
-            @activeTab={{this.activeTab}}
-            @onTabChange={{this.setActiveTab}}
-          >
+          <Tabs @activeTab={{this.activeTab}}>
             <:cards>
               <TabPanel
                 @refType='card'
+                @activeTab={{this.activeTab}}
+                @onTabChange={{this.setActiveTab}}
                 @onInsert={{this.handleInsertCard}}
                 @initialTarget={{this.cardInitialTarget}}
                 @onRemove={{this.handleRemove}}
@@ -149,6 +148,8 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
             <:files>
               <TabPanel
                 @refType='file'
+                @activeTab={{this.activeTab}}
+                @onTabChange={{this.setActiveTab}}
                 @onInsert={{this.handleInsertFile}}
                 @initialTarget={{this.fileInitialTarget}}
                 @onRemove={{this.handleRemove}}
@@ -159,14 +160,33 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
       </ModalContainer>
     {{/if}}
     <style scoped>
+      /* Collapse the (empty) modal header band to nothing. With @title='' and
+         no <:header> content it holds only the built-in close button, which is
+         position:absolute and out of flow — so the band disappears while the
+         × keeps floating at the modal's top-right corner. */
+      .markdown-embed-chooser-modal :deep(.dialog-box__header) {
+        min-height: 0;
+        padding: 0;
+      }
+      /* Full-bleed body: the two columns and the divider between them run to
+         the modal edges, so the content gets no padding of its own — each
+         column's inner components supply their own insets. */
       .markdown-embed-chooser-modal :deep(.dialog-box__content) {
         display: flex;
         flex-direction: column;
-        padding: var(--boxel-sp-sm) var(--boxel-sp);
+        padding: 0;
       }
       :deep(.markdown-embed-chooser-modal__container) {
         height: 36rem;
       }
+      /* Re-center the fixed-height modal box vertically. Operator mode ships a
+         global `.operator-mode .boxel-modal__inner { display: block }` that
+         outranks boxel-ui's base `.boxel-modal__inner { display: flex }`, which
+         drops the inner's flex centering and top-aligns our 36rem box. Restore
+         flex on our own inner so `@centered` actually centers it. */
+      .markdown-embed-chooser-modal > :deep(.boxel-modal__inner) {
+        display: flex;
+      }
     </style>
   </template>
 }
diff --git a/packages/host/app/components/markdown-embed-chooser/pane.gts b/packages/host/app/components/markdown-embed-chooser/pane.gts
index bd30e4c2cf..f3d3a84c11 100644
--- a/packages/host/app/components/markdown-embed-chooser/pane.gts
+++ b/packages/host/app/components/markdown-embed-chooser/pane.gts
@@ -94,11 +94,10 @@ function buildFormatOptions(): FormatOption[] {
 interface Signature {
   Element: HTMLElement;
   Args: {
-    // Resolved instance being previewed. Its `id` is the BFM ref URL. May be
-    // undefined when the chooser is open but the user hasn't picked a row yet;
-    // the pane keeps the format/W×H controls visible (disabled CTA) so the
-    // layout doesn't jump when a target arrives.
-    target?: CardDef | FileDef;
+    // Resolved instance being previewed. Its `id` is the BFM ref URL. Always a
+    // real target — the parent (tab-panel) only mounts the pane once a row is
+    // picked and its instance resolves, rendering its own placeholder until then.
+    target: CardDef | FileDef;
     // Which BFM keyword to emit: `:card[...]` vs `:file[...]`.
     refType: 'card' | 'file';
     // Receives the serialized BFM directive when the CTA is clicked. The host
@@ -179,7 +178,7 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
     // `initialTargetUrl` arg wins over `args.target?.id` because the resolved
     // instance is loaded asynchronously — at construction time the parent
     // already knows the URL but the store has not yet returned the instance.
-    this.initialTargetUrl = args.initialTargetUrl ?? args.target?.id;
+    this.initialTargetUrl = args.initialTargetUrl ?? args.target.id;
   }
 
   private get selectedOption(): FormatOption {
@@ -264,7 +263,7 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
       this.kind !== this.initialKind ||
       this.widthInput !== this.initialWidthInput ||
       this.heightInput !== this.initialHeightInput ||
-      (this.args.target?.id ?? undefined) !== this.initialTargetUrl
+      this.args.target.id !== this.initialTargetUrl
     );
   }
 
@@ -306,7 +305,7 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   }
 
   private get bfmString(): string {
-    let url = this.args.target?.id;
+    let url = this.args.target.id;
     if (!url) {
       return '';
     }
@@ -316,10 +315,6 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
     });
   }
 
-  private get isCtaDisabled(): boolean {
-    return !this.args.target?.id;
-  }
-
   @action
   private selectFormat(option: FormatOption) {
     this.selectedValue = option.value;
@@ -409,24 +404,13 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
       </div>
 
       <div class='markdown-embed-preview-pane__viewport'>
-        {{#if @target}}
-          <MarkdownEmbedPreview
-            @target={{@target}}
-            @format={{this.previewFormat}}
-            @sizeSpec={{this.sizeSpec}}
-            @kind={{this.kind}}
-            @showSurroundingText={{true}}
-          />
-        {{else}}
-          <p
-            class='markdown-embed-preview-pane__empty'
-            data-test-markdown-embed-preview-empty
-          >
-            Pick a
-            {{@refType}}
-            to preview its embed.
-          </p>
-        {{/if}}
+        <MarkdownEmbedPreview
+          @target={{@target}}
+          @format={{this.previewFormat}}
+          @sizeSpec={{this.sizeSpec}}
+          @kind={{this.kind}}
+          @showSurroundingText={{true}}
+        />
       </div>
 
       <footer class='markdown-embed-preview-pane__footer'>
@@ -461,7 +445,6 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
         <Button
           @kind='primary'
           @size='small'
-          @disabled={{this.isCtaDisabled}}
           class='markdown-embed-preview-pane__cta'
           data-test-markdown-embed-preview-cta
           {{on 'click' this.insert}}
@@ -508,7 +491,9 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
         width: 100%;
         height: 100%;
         min-height: 0;
-        background-color: var(--boxel-light);
+        /* Inherit the preview column's off-white surface; the inner card
+           viewport supplies its own background. */
+        background-color: transparent;
       }
       .markdown-embed-preview-pane__header {
         flex: 0 0 auto;
@@ -527,12 +512,6 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
         overflow: auto;
         background-color: var(--boxel-100);
       }
-      .markdown-embed-preview-pane__empty {
-        margin: 0;
-        font: var(--boxel-font-sm);
-        color: var(--boxel-450);
-        text-align: center;
-      }
       .markdown-embed-preview-pane__format-select {
         flex: 1 1 auto;
         min-width: 0;
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
index a97aa24a09..a79775faa0 100644
--- a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
@@ -30,11 +30,19 @@ import type StoreService from '@cardstack/host/services/store';
 import type { CardDef, FileDef } from 'https://cardstack.com/base/card-api';
 
 import MarkdownEmbedPreviewPane, { type OptionValue } from './pane';
+import TabPills from './tab-pills';
 
 interface Signature {
   Element: HTMLDivElement;
   Args: {
     refType: MarkdownEmbedRefType;
+    // The chooser's active tab + switch handler. The segmented pill control
+    // lives at the top of this panel's left (search) column, so each visible
+    // tab carries its own pills directly above its search bar — matching the
+    // design where the tabs sit inside the search section, not as a
+    // full-width bar across the modal.
+    activeTab: MarkdownEmbedRefType;
+    onTabChange: (tab: MarkdownEmbedRefType) => void;
     onInsert: (bfm: string, url: string) => void;
     // Optional edit-mode preload for this tab. When set, the tab starts in
     // `current` mode showing the placed target with Replace / Remove buttons;
@@ -157,6 +165,13 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
       ...attributes
     >
       <div class='markdown-embed-chooser-tab-panel__left'>
+        {{! Both tab panels stay mounted to preserve their state, so the pills
+          render only in the active one — a single set of tabs in the DOM. }}
+        {{#if (eq @refType @activeTab)}}
+          <div class='markdown-embed-chooser-tab-panel__tabbar'>
+            <TabPills @activeTab={{@activeTab}} @onTabChange={{@onTabChange}} />
+          </div>
+        {{/if}}
         {{#if (eq this.mode 'current')}}
           <div
             class='markdown-embed-chooser-tab-panel__current'
@@ -200,42 +215,101 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
         {{else}}
           <MiniFileChooser
             @onSelect={{this.onFileSelect}}
+            @onHighlight={{this.onFileSelect}}
             @selected={{this.selectedUrl}}
           />
         {{/if}}
       </div>
       <div class='markdown-embed-chooser-tab-panel__right'>
-        <MarkdownEmbedPreviewPane
-          @target={{this.selectedTarget}}
-          @refType={{@refType}}
-          @onInsert={{this.handleInsert}}
-          @initialFormat={{this.initialPaneFormat}}
-          @initialWidth={{this.initialPaneWidth}}
-          @initialHeight={{this.initialPaneHeight}}
-          @initialKind={{this.initialPaneKind}}
-          @initialTargetUrl={{@initialTarget.url}}
-          @ctaLabelOverride={{this.ctaLabelOverride}}
-          @onDirtyChange={{this.onPaneDirtyChange}}
-        />
+        {{#if this.selectedTarget}}
+          <MarkdownEmbedPreviewPane
+            @target={{this.selectedTarget}}
+            @refType={{@refType}}
+            @onInsert={{this.handleInsert}}
+            @initialFormat={{this.initialPaneFormat}}
+            @initialWidth={{this.initialPaneWidth}}
+            @initialHeight={{this.initialPaneHeight}}
+            @initialKind={{this.initialPaneKind}}
+            @initialTargetUrl={{@initialTarget.url}}
+            @ctaLabelOverride={{this.ctaLabelOverride}}
+            @onDirtyChange={{this.onPaneDirtyChange}}
+          />
+        {{else}}
+          <p
+            class='markdown-embed-chooser-tab-panel__empty'
+            data-test-markdown-embed-preview-empty
+          >
+            Search for a
+            {{@refType}}
+            &amp; preview its format here
+          </p>
+        {{/if}}
       </div>
     </div>
     <style scoped>
       .markdown-embed-chooser-tab-panel {
         display: flex;
-        gap: var(--boxel-sp);
         width: 100%;
         height: 100%;
         min-height: 0;
+        background-color: var(--boxel-light);
       }
       .markdown-embed-chooser-tab-panel__left,
       .markdown-embed-chooser-tab-panel__right {
-        flex: 1 1 0;
         min-width: 0;
         min-height: 0;
-        border: 1px solid var(--boxel-300);
-        border-radius: var(--boxel-border-radius);
         overflow: hidden;
-        background-color: var(--boxel-light);
+      }
+      /* The chooser column is narrower than the preview column (~2:3), per the
+         design. A single full-height divider between the two columns — no boxed
+         borders, so the panels read as one continuous surface. The left
+         column stacks the tab pills above the mini chooser. */
+      .markdown-embed-chooser-tab-panel__left {
+        flex: 2 1 0;
+        display: flex;
+        flex-direction: column;
+        border-right: 1px solid var(--boxel-300);
+      }
+      /* Pills sit at the top of the search column, directly above the search
+         bar; the chooser below fills the remaining height. */
+      .markdown-embed-chooser-tab-panel__tabbar {
+        flex: 0 0 auto;
+        display: flex;
+        align-items: center;
+        padding: var(--boxel-sp-sm) var(--boxel-sp-xs) 0;
+      }
+      /* The chooser (or current-target tile) fills the column below the pills.
+         The mini choosers set their own `height: 100%`, which would resolve
+         against the full column height and overflow past the pills — grow to
+         the remaining space instead. */
+      .markdown-embed-chooser-tab-panel__left > :deep(.mini-card-chooser),
+      .markdown-embed-chooser-tab-panel__left > :deep(.mini-file-chooser),
+      .markdown-embed-chooser-tab-panel__current {
+        flex: 1 1 auto;
+        min-height: 0;
+        height: auto;
+      }
+      .markdown-embed-chooser-tab-panel__right {
+        flex: 3 1 0;
+        display: flex;
+        flex-direction: column;
+        min-height: 0;
+        /* The preview column reads as an off-white surface, distinct from the
+           white chooser column on the left. */
+        background-color: #fbf8f8;
+      }
+      /* Centered placeholder shown until a row is picked and its instance
+         resolves; the pane mounts in its place once a target arrives. */
+      .markdown-embed-chooser-tab-panel__empty {
+        flex: 1 1 auto;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        margin: 0;
+        padding: var(--boxel-sp);
+        font: var(--boxel-font-sm);
+        color: var(--boxel-450);
+        text-align: center;
       }
       .markdown-embed-chooser-tab-panel__current {
         display: flex;
@@ -243,7 +317,6 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
         align-items: center;
         justify-content: center;
         gap: var(--boxel-sp);
-        height: 100%;
         padding: var(--boxel-sp);
         text-align: center;
       }
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-pills.gts b/packages/host/app/components/markdown-embed-chooser/tab-pills.gts
new file mode 100644
index 0000000000..4a6ec3cea6
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/tab-pills.gts
@@ -0,0 +1,94 @@
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+
+import { eq } from '@cardstack/boxel-ui/helpers';
+
+import type { MarkdownEmbedRefType } from '@cardstack/host/services/markdown-embed-chooser';
+
+interface Signature {
+  Element: HTMLDivElement;
+  Args: {
+    activeTab: MarkdownEmbedRefType;
+    onTabChange: (tab: MarkdownEmbedRefType) => void;
+  };
+}
+
+// Segmented pill control for the combined chooser's two tabs. Sits at the top
+// of the active tab's left (search) column, directly above its search bar; the
+// matching tabpanels render alongside in the modal body. Button ids are
+// referenced by the panels' `aria-labelledby`, so they're kept stable here.
+const MarkdownEmbedChooserTabPills: TemplateOnlyComponent<Signature> =
+  <template>
+    <div
+      class='markdown-embed-chooser-tab-pills'
+      role='tablist'
+      aria-label='Choose card or file'
+      ...attributes
+    >
+      <button
+        type='button'
+        role='tab'
+        id='markdown-embed-chooser-tab-cards'
+        aria-controls='markdown-embed-chooser-panel-cards'
+        aria-selected={{if (eq @activeTab 'card') 'true' 'false'}}
+        tabindex={{if (eq @activeTab 'card') '0' '-1'}}
+        class='markdown-embed-chooser-tab-pills__tab
+          {{if (eq @activeTab "card") "is-active"}}'
+        data-test-markdown-embed-chooser-tab='card'
+        {{on 'click' (fn @onTabChange 'card')}}
+      >
+        Cards
+      </button>
+      <button
+        type='button'
+        role='tab'
+        id='markdown-embed-chooser-tab-files'
+        aria-controls='markdown-embed-chooser-panel-files'
+        aria-selected={{if (eq @activeTab 'file') 'true' 'false'}}
+        tabindex={{if (eq @activeTab 'file') '0' '-1'}}
+        class='markdown-embed-chooser-tab-pills__tab
+          {{if (eq @activeTab "file") "is-active"}}'
+        data-test-markdown-embed-chooser-tab='file'
+        {{on 'click' (fn @onTabChange 'file')}}
+      >
+        Files
+      </button>
+    </div>
+    <style scoped>
+      .markdown-embed-chooser-tab-pills {
+        display: flex;
+        width: 100%;
+        gap: var(--boxel-sp-4xs);
+        padding: var(--boxel-sp-5xs);
+        border-radius: 999px;
+        background-color: var(--boxel-200);
+      }
+      .markdown-embed-chooser-tab-pills__tab {
+        appearance: none;
+        flex: 1 1 0;
+        border: none;
+        background: transparent;
+        padding: var(--boxel-sp-4xs) var(--boxel-sp);
+        border-radius: 999px;
+        font: 600 var(--boxel-font-sm);
+        color: var(--boxel-450);
+        cursor: pointer;
+        line-height: 1.4;
+      }
+      .markdown-embed-chooser-tab-pills__tab:hover {
+        color: var(--boxel-dark);
+      }
+      .markdown-embed-chooser-tab-pills__tab.is-active {
+        color: var(--boxel-dark);
+        background-color: var(--boxel-light);
+        box-shadow: var(--boxel-box-shadow-sm, 0 1px 2px rgba(0, 0, 0, 0.15));
+      }
+      .markdown-embed-chooser-tab-pills__tab:focus-visible {
+        outline: 2px solid var(--boxel-highlight);
+        outline-offset: 2px;
+      }
+    </style>
+  </template>;
+
+export default MarkdownEmbedChooserTabPills;
diff --git a/packages/host/app/components/markdown-embed-chooser/tabs.gts b/packages/host/app/components/markdown-embed-chooser/tabs.gts
index 41b469b984..e376d9434a 100644
--- a/packages/host/app/components/markdown-embed-chooser/tabs.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tabs.gts
@@ -1,6 +1,4 @@
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
-import { fn } from '@ember/helper';
-import { on } from '@ember/modifier';
 
 import { eq } from '@cardstack/boxel-ui/helpers';
 
@@ -10,7 +8,6 @@ interface Signature {
   Element: HTMLDivElement;
   Args: {
     activeTab: MarkdownEmbedRefType;
-    onTabChange: (tab: MarkdownEmbedRefType) => void;
   };
   Blocks: {
     cards: [];
@@ -18,46 +15,15 @@ interface Signature {
   };
 }
 
-// Two-tab shell for the combined chooser. Both panels stay mounted — the
-// inactive one is `display: none` rather than `{{#if}}`'d out — so each tab's
-// mini-chooser keeps its search query, highlighted row, scroll position, and
-// the pane's W×H / format selection across a switch.
+// The two tabpanels for the combined chooser. The matching segmented pill
+// control sits at the top of each panel's left search column (see
+// `tab-pills.gts`); each panel's `aria-labelledby` points back to its pill
+// button by id. Both panels stay
+// mounted — the inactive one is `display: none` rather than `{{#if}}`'d out —
+// so each tab's mini-chooser keeps its search query, highlighted row, scroll
+// position, and the pane's W×H / format selection across a switch.
 const MarkdownEmbedChooserTabs: TemplateOnlyComponent<Signature> = <template>
   <div class='markdown-embed-chooser-tabs' ...attributes>
-    <div
-      class='markdown-embed-chooser-tabs__strip'
-      role='tablist'
-      aria-label='Choose card or file'
-    >
-      <button
-        type='button'
-        role='tab'
-        id='markdown-embed-chooser-tab-cards'
-        aria-controls='markdown-embed-chooser-panel-cards'
-        aria-selected={{if (eq @activeTab 'card') 'true' 'false'}}
-        tabindex={{if (eq @activeTab 'card') '0' '-1'}}
-        class='markdown-embed-chooser-tabs__tab
-          {{if (eq @activeTab "card") "is-active"}}'
-        data-test-markdown-embed-chooser-tab='card'
-        {{on 'click' (fn @onTabChange 'card')}}
-      >
-        Cards
-      </button>
-      <button
-        type='button'
-        role='tab'
-        id='markdown-embed-chooser-tab-files'
-        aria-controls='markdown-embed-chooser-panel-files'
-        aria-selected={{if (eq @activeTab 'file') 'true' 'false'}}
-        tabindex={{if (eq @activeTab 'file') '0' '-1'}}
-        class='markdown-embed-chooser-tabs__tab
-          {{if (eq @activeTab "file") "is-active"}}'
-        data-test-markdown-embed-chooser-tab='file'
-        {{on 'click' (fn @onTabChange 'file')}}
-      >
-        Files
-      </button>
-    </div>
     <div
       role='tabpanel'
       id='markdown-embed-chooser-panel-cards'
@@ -87,39 +53,9 @@ const MarkdownEmbedChooserTabs: TemplateOnlyComponent<Signature> = <template>
       height: 100%;
       min-height: 0;
     }
-    .markdown-embed-chooser-tabs__strip {
-      flex: 0 0 auto;
-      display: flex;
-      gap: var(--boxel-sp-xs);
-      padding: 0 var(--boxel-sp-xs);
-      border-bottom: 1px solid var(--boxel-300);
-    }
-    .markdown-embed-chooser-tabs__tab {
-      appearance: none;
-      background: none;
-      border: none;
-      padding: var(--boxel-sp-xs) var(--boxel-sp-sm);
-      font: 600 var(--boxel-font-sm);
-      color: var(--boxel-450);
-      cursor: pointer;
-      border-bottom: 2px solid transparent;
-      margin-bottom: -1px;
-    }
-    .markdown-embed-chooser-tabs__tab:hover {
-      color: var(--boxel-dark);
-    }
-    .markdown-embed-chooser-tabs__tab.is-active {
-      color: var(--boxel-dark);
-      border-bottom-color: var(--boxel-highlight);
-    }
-    .markdown-embed-chooser-tabs__tab:focus-visible {
-      outline: 2px solid var(--boxel-highlight);
-      outline-offset: 2px;
-    }
     .markdown-embed-chooser-tabs__panel {
       flex: 1 1 auto;
       min-height: 0;
-      padding-top: var(--boxel-sp-sm);
     }
     .markdown-embed-chooser-tabs__panel.is-hidden {
       display: none;

From 9e4f2ba1ec8dd3a43a51a078f18eb0617c9015bc Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Sat, 27 Jun 2026 09:06:44 +0700
Subject: [PATCH 08/12] Fix type errors against migrated card-api

Narrow the embed-chooser resolution before reading `bfm`: a negated `&&`
condition doesn't narrow the union, so split the `remove` check into its
own block. And read a card's display title via `cardTitle` (the base
CardDef `title` field was replaced by the cardInfo-derived `cardTitle`).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/base/codemirror-editor.gts                         | 6 ++++--
 .../app/components/markdown-embed-chooser/tab-panel.gts     | 2 +-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/base/codemirror-editor.gts b/packages/base/codemirror-editor.gts
index ab4f7a0fb4..f18bcff5f9 100644
--- a/packages/base/codemirror-editor.gts
+++ b/packages/base/codemirror-editor.gts
@@ -690,8 +690,10 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
       return;
     }
     if (!result) return;
-    if ('remove' in result && result.remove) {
-      this._deleteRange(ref);
+    if ('remove' in result) {
+      if (result.remove) {
+        this._deleteRange(ref);
+      }
       return;
     }
     this._replaceRange(ref, result.bfm);
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
index a79775faa0..d8fbad31e3 100644
--- a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
@@ -107,7 +107,7 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
     if (this.args.refType === 'file') {
       return fileNameFromUrl(t.id ?? this.selectedUrl ?? '');
     }
-    return (t as CardDef).title ?? t.id ?? this.selectedUrl ?? '';
+    return (t as CardDef).cardTitle ?? t.id ?? this.selectedUrl ?? '';
   }
 
   @action

From 451ffcb1b6df3772d11afa03da01664602fe049e Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Mon, 29 Jun 2026 12:42:53 +0700
Subject: [PATCH 09/12] Remove scratch planning doc

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...11677-markdown-embed-chooser-modal-plan.md | 152 ------------------
 1 file changed, 152 deletions(-)
 delete mode 100644 docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md

diff --git a/docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md b/docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md
deleted file mode 100644
index 1f60ea2092..0000000000
--- a/docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md
+++ /dev/null
@@ -1,152 +0,0 @@
-# CS-11675 / CS-11676 / CS-11677 — Combined Chooser, Edit Modal, Toolbar Wiring
-
-## Context
-
-The "Markdown Editing UI" project lets a user pick a card/file from inside the markdown editor and embed it as a BFM directive (`:card[URL]` inline / `::card[URL | size]` block). Foundation already on `main`:
-
-- `MiniCardChooser` — `packages/host/app/components/card-chooser/mini/index.gts` (PR #5288, merged)
-- `MiniFileChooser` — `packages/host/app/components/file-chooser/mini/index.gts` (PR #5298, merged)
-- BFM parsing / serialization in `packages/runtime-common/bfm-card-references.ts`
-- `CardChooserModal` / `FileChooserModal` give the canonical `Deferred<…>`-based modal pattern.
-
-PR #5303 (merged as `dd7cdf8f71`) added:
-
-- `MarkdownEmbedPreviewPane` — `packages/host/app/components/markdown-embed-chooser/pane.gts`. Signature today: `{ target: CardDef | FileDef; refType: 'card' | 'file'; onInsert: (bfm: string) => void }`. Owns format dropdown, W×H inputs, Inline/Block toggle; serializes its own BFM via `serializeBfmRef` + `serializeBfmSizeSpec`.
-- `MarkdownEmbedPreview` — the pure render component the pane uses.
-
-This worktree picks up where #5303 left off: glue the mini choosers to the pane in a tabbed modal, support an edit variant of the same shell, and wire it into the CodeMirror toolbar.
-
-## Branch / PR strategy
-
-- Worktree branch off latest `origin/main` (already includes #5303). Suggested name: `cs-11675-11676-11677-markdown-embed-chooser-modal`.
-- **One combined draft PR** for all three tickets (per user decision). Three commits inside it, one per ticket, so reviewers can scan ticket-by-ticket. Stays a draft until promoted (`feedback_open_drafts_not_prs`).
-- Plan doc lives at `docs/cs-11675-11676-11677-markdown-embed-chooser-modal-plan.md`; deleted before merge (`feedback_plan_doc_not_in_merged_branch`).
-
----
-
-## CS-11675 — Combined chooser modal
-
-All new files under `packages/host/app/components/markdown-embed-chooser/`.
-
-- **`modal.gts` — `MarkdownEmbedChooserModal`**. Mirrors `card-chooser/modal.gts`: holds a `Deferred<{ refType, url, bfm } | { remove: true } | undefined>`, renders a `ModalContainer` with focus trap, owns the tab state and the current target per tab.
-- **`tabs.gts`** — internal tabbed shell. Two tabs ("Cards" / "Files"). Both panels stay mounted (CSS-hidden when inactive) so left-panel state (search query, highlighted item, scroll, W×H) is preserved across tab switches. State lives on the modal component, not in the inactive child via `{{#if}}`.
-- **`tab-panel.gts`** — pairs one mini chooser with the preview pane. Cards panel: `MiniCardChooser` + pane with `refType='card'`. Files panel: `MiniFileChooser` + pane with `refType='file'`. Clicking a row in the mini chooser sets that tab's `selectedTarget`; the pane re-renders with the new `@target`.
-
-**New service**: `packages/host/app/services/markdown-embed-chooser.ts` — exposes `chooseCardOrFile({ defaultTab })` and `editEmbed({ url, refType, sizeSpec })`. Same request-queue pattern as `card-chooser/modal.gts`. Composed into `operator-mode/container.gts` next to the existing chooser modals.
-
-**Pane changes** (`pane.gts`): teach it to render when `@target` is `undefined` (empty preview, matching Zeplin 02). The format/W×H controls remain visible (disabled / no-op CTA) so layout doesn't jump when a row is picked.
-
-**Acceptance**: matches the 5 bullets on the ticket. Verify with a new integration test at `packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts` + the existing freestyle host page.
-
----
-
-## CS-11676 — Edit mode of the same modal
-
-Per user decision + Zeplin 08B screenshot: the edit modal is the _same combined chooser modal_ with the same tabs. The only change is that the active tab's **left panel** swaps from the search/chooser view to a "current target" view.
-
-**Per-tab left-panel state** lives in each `tab-panel.gts` instance:
-
-- `mode: 'choose'` (default) — renders the mini chooser (`MiniCardChooser` / `MiniFileChooser`).
-- `mode: 'current'` (edit mode initial) — renders a single tile for the placed target with two buttons:
-  - **Replace Card / Replace File** → flips that tab's `mode` back to `choose` and exposes the mini chooser. Picking a new row sets the new target.
-  - **Remove Card / Remove File** → resolves the modal's Deferred with `{ remove: true }` and closes.
-
-**Modal changes** (`modal.gts`):
-
-- Accept an optional `initialTarget: { refType, url, sizeSpec }` on the request.
-- When present: open on the matching tab, set that tab's `mode` to `current` with the resolved target, and preload the pane with the parsed `sizeSpec`. Switching to the other tab still works (Zeplin 08B note: "TOGGLING TO FILES WILL DISPLAY FILE CHOOSER UI") — the inactive tab starts in `choose` mode.
-
-**Pane extension** (`pane.gts`) — required for preload + dirty tracking:
-
-```ts
-// New args:
-initialFormat?: OptionValue;
-initialWidth?: number | string;
-initialHeight?: number;
-initialKind?: 'inline' | 'block';
-onDirtyChange?: (dirty: boolean) => void;
-ctaLabelOverride?: string;  // 'DONE' / 'ACCEPT' for edit mode
-```
-
-Inbound `BfmSizeSpec` → `OptionValue` mapping mirrors `selectFormat` + `syncVariantFromSize`. Dirty = the serialized current BFM differs from the initial BFM. In edit mode the parent passes `ctaLabelOverride = dirty ? 'ACCEPT' : 'DONE'`, and the CTA is always active (per Zeplin 08B note 2).
-
-**Acceptance**: matches the 5 ticket bullets. The modal's caller (CS-11677 wiring) does the actual in-place text replacement once `ACCEPT` resolves the Deferred with the new BFM string.
-
----
-
-## CS-11677 — Toolbar + cursor-aware Edit
-
-Per user decision: drop the standalone "dimensions overlay chip on every inline preview" sub-piece. The W×H readout lives inside `MarkdownEmbedPreviewPane` (already there via the W/H inputs in #5303), so the user sees dimensions when picking / editing — no separate editor-side overlay required.
-
-Two pieces remain.
-
-### (a) Toolbar item — Add a card / Add a file
-
-Per the third screenshot: a single toolbar trigger that opens a popover with two items, **Add a card** and **Add a file**. Each calls into the host to open the combined modal with `defaultTab: 'cards'` or `'files'`.
-
-In `packages/base/codemirror-editor.gts` around line 418 (`toolbarButtons`), insert a new entry left of the formatting group. The toolbar item type already supports inline toggles + dividers; add a new variant (or a dedicated popover button beside the array) for the dropdown trigger. Each menu item calls a new host-supplied callback (the editor lives in `packages/base/`, a card-definition surface, and surfaces hooks rather than importing host services — same pattern as existing toolbar actions). The host wires that callback to `markdownEmbedChooser.chooseCardOrFile({ defaultTab })`.
-
-On resolution with `{ bfm }`: dispatch a CodeMirror transaction at the current selection. Insert pattern at `codemirror-editor.gts:580–594`. For block embeds, surround the directive with the newline-padding rules already used there.
-
-### (b) Cursor-aware Edit button
-
-A new BFM-range tracker, two layers:
-
-1. **New helper** in `packages/runtime-common/bfm-card-references.ts`:
-
-   ```ts
-   export function extractBfmRefRanges(markdown: string): Array<{
-     kind: 'inline' | 'block';
-     from: number;
-     to: number;
-     refType: 'card' | 'file';
-     url: string; // unresolved, as written in the source
-     sizeSpec?: string;
-   }>;
-   ```
-
-   Pure string scan reusing the block (line 288) and inline (line 290) regexes already in the file. No URL resolution — cheap to run on every doc change.
-
-2. **CodeMirror extension** wired in `packages/host/app/lib/codemirror-context.ts`: a `ViewPlugin` that recomputes ranges on `update.docChanged`, then on `update.selectionSet` tests `update.state.selection.main.head` against the ranges. Surface the result via a tracked value on the editor's controller — same channel `EditorView.updateListener` uses around lines 1120–1146.
-
-When `currentRef` is non-null, the toolbar swaps the "Add embed" item for an Edit pencil; click opens `markdownEmbedChooser.editEmbed({ refType, url, sizeSpec })`.
-
-On the modal's resolution:
-
-- `{ bfm }` (ACCEPT) → dispatch a transaction replacing the original `[from, to]` range with the new BFM string.
-- `{ remove: true }` → dispatch a transaction deleting `[from, to]` (and the surrounding newlines for block).
-- `undefined` (DONE / cancel) → no-op.
-
-### Acceptance
-
-Matches the remaining ticket bullets except the dimensions-overlay one (descoped per user). Verify via a new integration test at `packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts` + the freestyle host page + the live dev stack walk-through below.
-
----
-
-## Verification
-
-Per-ticket integration tests above + the existing `markdown-embed` suite from #5303 continue to pass.
-
-End-to-end in the dev stack (`feedback_boxel_run_dev_all`, `feedback_faster_dev_stack_split`):
-
-```
-mise exec -- pnpm -C packages/host start    # one terminal
-mise run dev                                 # another
-```
-
-Then at `https://localhost:4200/tests` or the dev host:
-
-1. Open a markdown file in code mode → toolbar shows the Add embed control.
-2. Add a card → modal opens on the Cards tab → pick a card → pane updates → click "Insert as …" → directive inserted at cursor and renders inline/block per the toggle.
-3. Switch tabs mid-session → verify the other tab's search query / W×H survive.
-4. Place the cursor inside the inserted ref → toolbar swaps to the Edit pencil.
-5. Click Edit → modal reopens preloaded with the current target + size. Change the format → CTA label flips to ACCEPT. Click ACCEPT → ref is replaced in place.
-6. Open Edit again → click Remove → ref disappears.
-
-## Critical reused utilities
-
-- `Deferred` (`packages/runtime-common/deferred.ts`) — same modal-resolution pattern as `card-chooser/modal.gts`.
-- `serializeBfmRef`, `serializeBfmSizeSpec`, `parseBfmSizeSpec` — `packages/runtime-common/bfm-card-references.ts` (last two on `main`, first on #5303 branch).
-- `MarkdownEmbedPreviewPane` — `packages/host/app/components/markdown-embed-chooser/pane.gts` (extended in CS-11676).
-- `MiniCardChooser`, `MiniFileChooser` — composed verbatim inside each tab.
-- CodeMirror selection-listener pattern at `packages/host/app/lib/codemirror-context.ts:1120–1146`; insert-at-cursor pattern at `packages/base/codemirror-editor.gts:580–594`.

From 6ea0c5e0b8285841d2b6db342491a4734ff8619c Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Mon, 29 Jun 2026 23:18:42 +0700
Subject: [PATCH 10/12] Address Copilot/Codex/Luke review on markdown embed
 chooser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lift the preview pane's format/placement/size state into a shared
EmbedFormatSelection model owned by the modal so the choice sticks when
switching between the Cards and Files tabs (Luke), and read its isDirty as a
getter — removing the render-phase {{this.reportDirty}} side effect (Copilot).

Also:
- Preserve placement when editing a size-less block directive by threading the
  directive's kind through editEmbed; a `::card[url]` round-trips as a block
  embed instead of collapsing to an inline atom (Codex).
- Clear the staged target at the start of each pick so a quick Insert during
  the load window can't serialize the previously-resolved URL (Codex).
- Cancel the debounced save in _replaceRange/_deleteRange so an edit/delete
  saves once, not twice (Copilot).
- Compare a directive's url/sizeSpec/kind in sameToolbarState so an in-place
  edit refreshes the ref the pencil acts on (Copilot).
- Drop the unfulfilled ARIA menu roles from the add-embed popover in favor of a
  plain disclosure (aria-expanded) (Copilot).
- Use the cn helper for conditional classes, replace a hardcoded color with a
  token, and correct the "byte range" comments to UTF-16 string offsets
  (Copilot).

Add coverage for tab-switch stickiness, size-less block round-trip, single
save on edit/delete, and in-place url refresh.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/base/codemirror-editor.gts           |  29 +-
 .../format-selection.ts                       | 336 ++++++++++++++++++
 .../markdown-embed-chooser/modal.gts          |  18 +-
 .../markdown-embed-chooser/pane-usage.gts     |   3 +
 .../markdown-embed-chooser/pane.gts           | 334 ++---------------
 .../markdown-embed-chooser/tab-panel.gts      | 107 ++----
 .../markdown-embed-chooser/tab-pills.gts      |  14 +-
 .../markdown-embed-chooser/tabs.gts           |  14 +-
 .../app/services/markdown-embed-chooser.ts    |   4 +
 .../codemirror-embed-toolbar-test.gts         | 133 ++++++-
 .../markdown-embed-chooser-modal-test.gts     | 119 +++++++
 .../markdown-embed-preview-pane-test.gts      |  23 ++
 .../runtime-common/bfm-card-references.ts     |  16 +-
 13 files changed, 748 insertions(+), 402 deletions(-)
 create mode 100644 packages/host/app/components/markdown-embed-chooser/format-selection.ts

diff --git a/packages/base/codemirror-editor.gts b/packages/base/codemirror-editor.gts
index f18bcff5f9..3930196dc2 100644
--- a/packages/base/codemirror-editor.gts
+++ b/packages/base/codemirror-editor.gts
@@ -205,7 +205,13 @@ function sameToolbarState(a: SelectionInfo, b: SelectionInfo): boolean {
     a.formats.strikethrough === b.formats.strikethrough &&
     a.formats.link === b.formats.link &&
     a.currentRef?.from === b.currentRef?.from &&
-    a.currentRef?.to === b.currentRef?.to
+    a.currentRef?.to === b.currentRef?.to &&
+    // Compare the directive's contents too — an in-place edit (URL/spec/kind
+    // change) can leave from/to unchanged but must still refresh the toolbar so
+    // the pencil edits the current ref, not a stale one.
+    a.currentRef?.url === b.currentRef?.url &&
+    a.currentRef?.sizeSpec === b.currentRef?.sizeSpec &&
+    a.currentRef?.kind === b.currentRef?.kind
   );
 }
 
@@ -684,6 +690,7 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
         refType: ref.refType as 'card' | 'file',
         url: ref.url,
         sizeSpec: ref.sizeSpec,
+        kind: ref.kind,
       });
     } catch (e) {
       console.warn('markdown-embed chooser unavailable', e);
@@ -736,6 +743,12 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
     view.focus();
     let onUpdate = this.args.onUpdate;
     if (onUpdate) {
+      // The dispatch above scheduled a debounced save via `onDocChange`; cancel
+      // it so the immediate save below isn't duplicated.
+      if (this.saveTimer) {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = null;
+      }
       onUpdate(view.state.doc.toString());
     }
   };
@@ -756,6 +769,11 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
     view.focus();
     let onUpdate = this.args.onUpdate;
     if (onUpdate) {
+      // Cancel the debounced save the dispatch scheduled so we don't save twice.
+      if (this.saveTimer) {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = null;
+      }
       onUpdate(view.state.doc.toString());
     }
   };
@@ -1100,20 +1118,14 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
                 type='button'
                 title='Add embed'
                 aria-label='Add embed'
-                aria-haspopup='menu'
                 aria-expanded={{if this._embedPopoverOpen 'true' 'false'}}
                 {{on 'mousedown' this._preventFocusLoss}}
                 {{on 'click' this._toggleEmbedPopover}}
               ><PlusIcon width='16' height='16' /></button>
               {{#if this._embedPopoverOpen}}
-                <div
-                  class='toolbar-embed-popover'
-                  role='menu'
-                  data-test-toolbar-embed-popover
-                >
+                <div class='toolbar-embed-popover' data-test-toolbar-embed-popover>
                   <button
                     type='button'
-                    role='menuitem'
                     class='toolbar-embed-popover__item'
                     data-test-toolbar-embed='card'
                     {{on 'mousedown' this._preventFocusLoss}}
@@ -1121,7 +1133,6 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
                   >Add a card</button>
                   <button
                     type='button'
-                    role='menuitem'
                     class='toolbar-embed-popover__item'
                     data-test-toolbar-embed='file'
                     {{on 'mousedown' this._preventFocusLoss}}
diff --git a/packages/host/app/components/markdown-embed-chooser/format-selection.ts b/packages/host/app/components/markdown-embed-chooser/format-selection.ts
new file mode 100644
index 0000000000..dcf4c8f979
--- /dev/null
+++ b/packages/host/app/components/markdown-embed-chooser/format-selection.ts
@@ -0,0 +1,336 @@
+import { tracked } from '@glimmer/tracking';
+
+import {
+  type FittedFormatId,
+  type FittedFormatSpec,
+  FITTED_FORMAT_SIZES,
+  fittedFormatById,
+} from '@cardstack/boxel-ui/helpers';
+
+import {
+  parseBfmSizeSpec,
+  serializeBfmSizeSpec,
+  type BfmSizeSpec,
+} from '@cardstack/runtime-common/bfm-card-references';
+
+export type EmbedFormat = 'atom' | 'embedded' | 'fitted' | 'isolated';
+type FormatCategory = 'atom' | 'embedded' | 'fitted' | 'isolated' | 'custom';
+export type OptionValue =
+  | 'atom'
+  | 'embedded'
+  | 'isolated'
+  | FittedFormatId
+  | 'custom';
+
+export interface FormatOption {
+  value: OptionValue;
+  formatLabel: string;
+  sizeLabel: string;
+  category: FormatCategory;
+  dividerAfter?: boolean;
+}
+
+// Flat dropdown list (no group headers): Atom, Embedded, Isolated, every
+// Fitted variant, then Custom — matching the designer's dropdown. `Custom`
+// is labelled `Fitted - Custom size` for grouping but is its own CTA
+// category. Every option works in both inline and block placement.
+export function buildFormatOptions(): FormatOption[] {
+  let options: FormatOption[] = [
+    {
+      value: 'atom',
+      formatLabel: 'Atom',
+      sizeLabel: 'Variable size',
+      category: 'atom',
+      dividerAfter: true,
+    },
+    {
+      value: 'embedded',
+      formatLabel: 'Embedded',
+      sizeLabel: 'Variable size',
+      category: 'embedded',
+      dividerAfter: true,
+    },
+    {
+      value: 'isolated',
+      formatLabel: 'Isolated',
+      sizeLabel: 'Variable size',
+      category: 'isolated',
+      dividerAfter: true,
+    },
+  ];
+  for (let spec of FITTED_FORMAT_SIZES) {
+    options.push({
+      value: spec.id,
+      formatLabel: 'Fitted',
+      sizeLabel: `${spec.title} (${spec.width}x${spec.height})`,
+      category: 'fitted',
+    });
+  }
+  options.push({
+    value: 'custom',
+    formatLabel: 'Fitted',
+    sizeLabel: 'Custom size',
+    category: 'custom',
+  });
+  return options;
+}
+
+export interface FormatSelectionSeeds {
+  format?: OptionValue;
+  width?: number | string;
+  height?: number;
+  kind?: 'inline' | 'block';
+}
+
+function normalizeSizeSpec(
+  input: BfmSizeSpec | string | undefined,
+): BfmSizeSpec | undefined {
+  if (!input) return undefined;
+  if (typeof input === 'string') {
+    return parseBfmSizeSpec(input) ?? undefined;
+  }
+  return input;
+}
+
+// Translates the BFM directive being edited (its size specifier + `::`/`:`
+// placement) into the seed state for a fresh `EmbedFormatSelection`. The
+// directive's explicit placement always wins over the format's default so the
+// edited embed round-trips its inline/block nature.
+export function deriveFormatSeeds(
+  sizeSpec: BfmSizeSpec | string | undefined,
+  kind?: 'inline' | 'block',
+): FormatSelectionSeeds {
+  let spec = normalizeSizeSpec(sizeSpec);
+  if (!spec) {
+    // Size-less directive. The renderer defaults a block embed to `embedded`
+    // and an inline embed to `atom`, so seed the format the directive actually
+    // renders as — this preserves `::card[url]` as a block embed instead of
+    // silently collapsing it to an inline atom.
+    if (kind === 'block') {
+      return { format: 'embedded', kind: 'block' };
+    }
+    return { kind: kind ?? 'inline' };
+  }
+  let seeds: FormatSelectionSeeds;
+  switch (spec.format) {
+    case 'atom':
+      seeds = { format: 'atom', kind: 'inline' };
+      break;
+    case 'embedded':
+      seeds = { format: 'embedded', kind: 'block' };
+      break;
+    case 'isolated':
+      seeds = { format: 'isolated', kind: 'block' };
+      break;
+    default:
+      // Fitted with optional W×H.
+      seeds = {
+        format: 'custom',
+        width: spec.width,
+        height: spec.height,
+        kind: 'block',
+      };
+  }
+  if (kind) {
+    seeds.kind = kind;
+  }
+  return seeds;
+}
+
+// The format/placement/size choice for a markdown embed, lifted out of the
+// preview pane so a single instance can be shared across the chooser's Cards
+// and Files tabs — switching tabs keeps the user's format selection (the pane
+// is per-tab and would otherwise reset to atom). The modal owns one instance
+// per chooser request; both tab panels' panes read and mutate it.
+export default class EmbedFormatSelection {
+  readonly formatOptions: FormatOption[] = buildFormatOptions();
+
+  // Atom is the default on first selection; atom is inline-only (see below).
+  @tracked selectedValue: OptionValue = 'atom';
+  @tracked kind: 'inline' | 'block' = 'inline';
+  // Raw input strings so a partially-typed value (e.g. while clearing) doesn't
+  // throw away the user's keystrokes. `%` widths are preserved verbatim.
+  @tracked widthInput = '';
+  @tracked heightInput = '';
+
+  // Frozen snapshot of the seeded state, captured once on construction from the
+  // edit-mode preload. `isDirty` compares against it so the parent can flip the
+  // CTA between DONE and ACCEPT.
+  private initialSelectedValue: OptionValue;
+  private initialKind: 'inline' | 'block';
+  private initialWidthInput: string;
+  private initialHeightInput: string;
+
+  constructor(seeds: FormatSelectionSeeds = {}) {
+    if (seeds.format !== undefined) {
+      this.selectedValue = seeds.format;
+    }
+    if (seeds.kind !== undefined) {
+      this.kind = seeds.kind;
+    } else if (seeds.format !== undefined) {
+      // Mirror `selectFormat`'s placement default (atom → inline, sized →
+      // block) when no explicit kind is supplied.
+      let cat = this.formatOptions.find(
+        (o) => o.value === seeds.format,
+      )?.category;
+      this.kind = cat === 'atom' ? 'inline' : 'block';
+    }
+    if (seeds.width !== undefined) {
+      this.widthInput = String(seeds.width);
+    }
+    if (seeds.height !== undefined) {
+      this.heightInput = String(seeds.height);
+    }
+    this.initialSelectedValue = this.selectedValue;
+    this.initialKind = this.kind;
+    this.initialWidthInput = this.widthInput;
+    this.initialHeightInput = this.heightInput;
+  }
+
+  get selectedOption(): FormatOption {
+    return (
+      this.formatOptions.find((o) => o.value === this.selectedValue) ??
+      this.formatOptions[0]
+    );
+  }
+
+  get category(): FormatCategory {
+    return this.selectedOption.category;
+  }
+
+  get showSizeInputs(): boolean {
+    return this.category === 'fitted' || this.category === 'custom';
+  }
+
+  // The preview renders the selected format in the chosen placement; format and
+  // inline/block are independent (every format works in both modes).
+  get previewFormat(): EmbedFormat {
+    switch (this.category) {
+      case 'atom':
+        return 'atom';
+      case 'embedded':
+        return 'embedded';
+      case 'isolated':
+        return 'isolated';
+      default:
+        return 'fitted';
+    }
+  }
+
+  // px number, `%` string, or undefined for an unparseable/empty input.
+  get width(): number | string | undefined {
+    let v = this.widthInput.trim();
+    if (/^\d+%$/.test(v)) return v;
+    if (/^\d+$/.test(v)) return parseInt(v, 10);
+    return undefined;
+  }
+
+  get height(): number | undefined {
+    let v = this.heightInput.trim();
+    return /^\d+$/.test(v) ? parseInt(v, 10) : undefined;
+  }
+
+  get sizeSpec(): BfmSizeSpec | undefined {
+    if (!this.showSizeInputs) {
+      return undefined;
+    }
+    return { format: 'fitted', width: this.width, height: this.height };
+  }
+
+  get categoryLabel(): string {
+    switch (this.category) {
+      case 'atom':
+        return 'Atom';
+      case 'embedded':
+        return 'Embedded';
+      case 'isolated':
+        return 'Isolated';
+      case 'custom':
+        return 'Custom';
+      case 'fitted':
+      default:
+        return 'Fitted';
+    }
+  }
+
+  // Size specifier for the chosen format. Atom is the default for inline
+  // placement, so an inline atom embed emits the size-less `:card[url]`;
+  // every other combination carries an explicit specifier so the rendered
+  // format matches the user's choice unambiguously.
+  get sizeSpecifier(): string | undefined {
+    switch (this.category) {
+      case 'atom':
+        return this.kind === 'inline' ? undefined : 'atom';
+      case 'embedded':
+        return 'embedded';
+      case 'isolated':
+        return 'isolated';
+      case 'fitted':
+        return this.selectedValue;
+      case 'custom':
+        return serializeBfmSizeSpec({
+          format: 'fitted',
+          width: this.width,
+          height: this.height,
+        });
+      default:
+        return undefined;
+    }
+  }
+
+  // True once any format/placement/size field has diverged from the seeded
+  // snapshot. Target identity (the user swapped in a different card/file) is
+  // tracked separately by the tab panel, which owns the resolved target.
+  get isDirty(): boolean {
+    return (
+      this.selectedValue !== this.initialSelectedValue ||
+      this.kind !== this.initialKind ||
+      this.widthInput !== this.initialWidthInput ||
+      this.heightInput !== this.initialHeightInput
+    );
+  }
+
+  selectFormat = (option: FormatOption) => {
+    this.selectedValue = option.value;
+    // Pick a sensible default placement for the format — atom reads as inline,
+    // sized formats as block — but the toggle stays free, so the user can flip
+    // either way afterward.
+    this.kind = option.category === 'atom' ? 'inline' : 'block';
+    if (option.category === 'fitted') {
+      let spec = fittedFormatById.get(option.value as FittedFormatId);
+      if (spec) {
+        this.widthInput = String(spec.width);
+        this.heightInput = String(spec.height);
+      }
+    }
+  };
+
+  // Bidirectional sync: editing either dimension re-points the dropdown to the
+  // matching named variant, or to Custom when nothing matches exactly.
+  private syncVariantFromSize() {
+    let w = this.width;
+    let h = this.height;
+    if (typeof w === 'number' && typeof h === 'number') {
+      let match = FITTED_FORMAT_SIZES.find(
+        (s: FittedFormatSpec) => s.width === w && s.height === h,
+      );
+      this.selectedValue = match ? match.id : 'custom';
+    } else {
+      this.selectedValue = 'custom';
+    }
+  }
+
+  setWidth = (value: string) => {
+    this.widthInput = value;
+    this.syncVariantFromSize();
+  };
+
+  setHeight = (value: string) => {
+    this.heightInput = value;
+    this.syncVariantFromSize();
+  };
+
+  setKind = (kind: 'inline' | 'block') => {
+    this.kind = kind;
+  };
+}
diff --git a/packages/host/app/components/markdown-embed-chooser/modal.gts b/packages/host/app/components/markdown-embed-chooser/modal.gts
index 57e219c6fa..39b99c2960 100644
--- a/packages/host/app/components/markdown-embed-chooser/modal.gts
+++ b/packages/host/app/components/markdown-embed-chooser/modal.gts
@@ -5,7 +5,7 @@ import { action } from '@ember/object';
 import type Owner from '@ember/owner';
 import { service } from '@ember/service';
 import Component from '@glimmer/component';
-import { tracked } from '@glimmer/tracking';
+import { cached, tracked } from '@glimmer/tracking';
 
 import focusTrap from 'ember-focus-trap/modifiers/focus-trap';
 
@@ -17,6 +17,7 @@ import type {
   MarkdownEmbedRefType,
 } from '@cardstack/host/services/markdown-embed-chooser';
 
+import EmbedFormatSelection, { deriveFormatSeeds } from './format-selection';
 import TabPanel from './tab-panel';
 import Tabs from './tabs';
 
@@ -61,6 +62,19 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
     return this.markdownEmbedChooser.currentRequest;
   }
 
+  // One format/placement/size selection shared by both tabs so the choice
+  // sticks across a tab switch. `@cached` keyed on the tracked `request`
+  // rebuilds it once per chooser invocation (seeded from the edited directive
+  // in edit mode) while returning the same instance across tab switches within
+  // the same open session.
+  @cached
+  get selection(): EmbedFormatSelection {
+    let it = this.request?.initialTarget;
+    return new EmbedFormatSelection(
+      it ? deriveFormatSeeds(it.sizeSpec, it.kind) : {},
+    );
+  }
+
   get activeTab(): MarkdownEmbedRefType {
     let req = this.request;
     if (
@@ -141,6 +155,7 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
                 @activeTab={{this.activeTab}}
                 @onTabChange={{this.setActiveTab}}
                 @onInsert={{this.handleInsertCard}}
+                @selection={{this.selection}}
                 @initialTarget={{this.cardInitialTarget}}
                 @onRemove={{this.handleRemove}}
               />
@@ -151,6 +166,7 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
                 @activeTab={{this.activeTab}}
                 @onTabChange={{this.setActiveTab}}
                 @onInsert={{this.handleInsertFile}}
+                @selection={{this.selection}}
                 @initialTarget={{this.fileInitialTarget}}
                 @onRemove={{this.handleRemove}}
               />
diff --git a/packages/host/app/components/markdown-embed-chooser/pane-usage.gts b/packages/host/app/components/markdown-embed-chooser/pane-usage.gts
index 276760d66d..ed3b81b327 100644
--- a/packages/host/app/components/markdown-embed-chooser/pane-usage.gts
+++ b/packages/host/app/components/markdown-embed-chooser/pane-usage.gts
@@ -13,6 +13,7 @@ import type StoreService from '@cardstack/host/services/store';
 
 import type { CardDef } from 'https://cardstack.com/base/card-api';
 
+import EmbedFormatSelection from './format-selection';
 import MarkdownEmbedPreviewPane from './pane';
 
 export default class MarkdownEmbedPreviewPaneUsage extends Component {
@@ -21,6 +22,7 @@ export default class MarkdownEmbedPreviewPaneUsage extends Component {
   @tracked private target: CardDef | undefined;
   @tracked private inserted: string | undefined;
   @tracked private refType: 'card' | 'file' = 'card';
+  private selection = new EmbedFormatSelection();
 
   @action private async onSelect(url: string) {
     let result = await this.store.get(url);
@@ -58,6 +60,7 @@ export default class MarkdownEmbedPreviewPaneUsage extends Component {
               <MarkdownEmbedPreviewPane
                 @target={{this.target}}
                 @refType={{this.refType}}
+                @selection={{this.selection}}
                 @onInsert={{this.onInsert}}
               />
             {{else}}
diff --git a/packages/host/app/components/markdown-embed-chooser/pane.gts b/packages/host/app/components/markdown-embed-chooser/pane.gts
index f3d3a84c11..2b308fbca1 100644
--- a/packages/host/app/components/markdown-embed-chooser/pane.gts
+++ b/packages/host/app/components/markdown-embed-chooser/pane.gts
@@ -1,95 +1,27 @@
 import { on } from '@ember/modifier';
 import { action } from '@ember/object';
-import type Owner from '@ember/owner';
 
 import Component from '@glimmer/component';
-import { tracked } from '@glimmer/tracking';
 
 import {
   BoxelInput,
   BoxelSelect,
   Button,
 } from '@cardstack/boxel-ui/components';
-import {
-  type FittedFormatId,
-  type FittedFormatSpec,
-  FITTED_FORMAT_SIZES,
-  fittedFormatById,
-} from '@cardstack/boxel-ui/helpers';
 import { IconX } from '@cardstack/boxel-ui/icons';
 
-import {
-  serializeBfmRef,
-  serializeBfmSizeSpec,
-  type BfmSizeSpec,
-} from '@cardstack/runtime-common/bfm-card-references';
+import { serializeBfmRef } from '@cardstack/runtime-common/bfm-card-references';
 
 import type { CardDef, FileDef } from 'https://cardstack.com/base/card-api';
 
 import PlacementToggle from './placement-toggle';
+
 import MarkdownEmbedPreview from './preview';
 
-type EmbedFormat = 'atom' | 'embedded' | 'fitted' | 'isolated';
-type FormatCategory = 'atom' | 'embedded' | 'fitted' | 'isolated' | 'custom';
-export type OptionValue =
-  | 'atom'
-  | 'embedded'
-  | 'isolated'
-  | FittedFormatId
-  | 'custom';
+import type EmbedFormatSelection from './format-selection';
+import type { FormatOption, OptionValue } from './format-selection';
 
-interface FormatOption {
-  value: OptionValue;
-  formatLabel: string;
-  sizeLabel: string;
-  category: FormatCategory;
-  dividerAfter?: boolean;
-}
-
-// Flat dropdown list (no group headers): Atom, Embedded, Isolated, every
-// Fitted variant, then Custom — matching the designer's dropdown. `Custom`
-// is labelled `Fitted - Custom size` for grouping but is its own CTA
-// category. Every option works in both inline and block placement.
-function buildFormatOptions(): FormatOption[] {
-  let options: FormatOption[] = [
-    {
-      value: 'atom',
-      formatLabel: 'Atom',
-      sizeLabel: 'Variable size',
-      category: 'atom',
-      dividerAfter: true,
-    },
-    {
-      value: 'embedded',
-      formatLabel: 'Embedded',
-      sizeLabel: 'Variable size',
-      category: 'embedded',
-      dividerAfter: true,
-    },
-    {
-      value: 'isolated',
-      formatLabel: 'Isolated',
-      sizeLabel: 'Variable size',
-      category: 'isolated',
-      dividerAfter: true,
-    },
-  ];
-  for (let spec of FITTED_FORMAT_SIZES) {
-    options.push({
-      value: spec.id,
-      formatLabel: 'Fitted',
-      sizeLabel: `${spec.title} (${spec.width}x${spec.height})`,
-      category: 'fitted',
-    });
-  }
-  options.push({
-    value: 'custom',
-    formatLabel: 'Fitted',
-    sizeLabel: 'Custom size',
-    category: 'custom',
-  });
-  return options;
-}
+export { type OptionValue };
 
 interface Signature {
   Element: HTMLElement;
@@ -100,26 +32,13 @@ interface Signature {
     target: CardDef | FileDef;
     // Which BFM keyword to emit: `:card[...]` vs `:file[...]`.
     refType: 'card' | 'file';
+    // The shared format/placement/size selection. Owned by the modal and shared
+    // across both tabs so the choice survives a tab switch; this pane is a pure
+    // view over it plus the resolved target.
+    selection: EmbedFormatSelection;
     // Receives the serialized BFM directive when the CTA is clicked. The host
-    // owns actual cursor insertion (a later ticket).
+    // owns actual cursor insertion.
     onInsert: (bfm: string) => void;
-    // Edit-mode preload: seed the format dropdown, W×H inputs, and placement
-    // toggle from the BFM directive the user is editing. Read once at
-    // construction; later updates are ignored so the pane is free to mutate
-    // its own state as the user edits.
-    initialFormat?: OptionValue;
-    initialWidth?: number | string;
-    initialHeight?: number;
-    initialKind?: 'inline' | 'block';
-    // URL of the placed target the user is editing. Distinct from
-    // `target.id` because the resolved instance arrives asynchronously —
-    // without this, the dirty check would briefly flip true as soon as the
-    // target loads.
-    initialTargetUrl?: string;
-    // Fired with `true` once the pane's state diverges from the initial
-    // preload (and back to `false` if it matches again). The parent uses this
-    // to flip the CTA label between 'DONE' and 'ACCEPT' in edit mode.
-    onDirtyChange?: (dirty: boolean) => void;
     // Overrides the dynamic "Insert as …" CTA label. Used in edit mode to
     // show 'DONE' (clean) or 'ACCEPT' (dirty) per the design spec.
     ctaLabelOverride?: string;
@@ -129,179 +48,14 @@ interface Signature {
 // Right-hand companion to the mini choosers: a live preview plus the controls
 // that decide how a card/file embeds — format dropdown, always-on W×H inputs
 // for Fitted (with smart variant matching), an Inline/Block toggle, and a
-// dynamic "Insert as …" CTA.
+// dynamic "Insert as …" CTA. All format state lives on the shared
+// `@selection`; this component only renders it and serializes the directive.
 export default class MarkdownEmbedPreviewPane extends Component<Signature> {
-  private formatOptions: FormatOption[] = buildFormatOptions();
-
-  // Atom is the default on first selection; atom is inline-only (see below).
-  @tracked private selectedValue: OptionValue = 'atom';
-  @tracked private kind: 'inline' | 'block' = 'inline';
-  // Raw input strings so a partially-typed value (e.g. while clearing) doesn't
-  // throw away the user's keystrokes. `%` widths are preserved verbatim.
-  @tracked private widthInput = '';
-  @tracked private heightInput = '';
-
-  // Frozen snapshot of the initial pane state, captured once on mount from the
-  // edit-mode preload args. Used by `dirty` to detect divergence so the parent
-  // can flip the CTA between DONE and ACCEPT.
-  private initialSelectedValue: OptionValue;
-  private initialKind: 'inline' | 'block';
-  private initialWidthInput: string;
-  private initialHeightInput: string;
-  private initialTargetUrl: string | undefined;
-
-  constructor(owner: Owner, args: Signature['Args']) {
-    super(owner, args);
-    if (args.initialFormat !== undefined) {
-      this.selectedValue = args.initialFormat;
-    }
-    if (args.initialKind !== undefined) {
-      this.kind = args.initialKind;
-    } else if (args.initialFormat !== undefined) {
-      // Mirror `selectFormat`'s placement default (atom → inline, sized →
-      // block) when no explicit initial kind is supplied.
-      let cat = this.formatOptions.find(
-        (o) => o.value === args.initialFormat,
-      )?.category;
-      this.kind = cat === 'atom' ? 'inline' : 'block';
-    }
-    if (args.initialWidth !== undefined) {
-      this.widthInput = String(args.initialWidth);
-    }
-    if (args.initialHeight !== undefined) {
-      this.heightInput = String(args.initialHeight);
-    }
-    this.initialSelectedValue = this.selectedValue;
-    this.initialKind = this.kind;
-    this.initialWidthInput = this.widthInput;
-    this.initialHeightInput = this.heightInput;
-    // `initialTargetUrl` arg wins over `args.target?.id` because the resolved
-    // instance is loaded asynchronously — at construction time the parent
-    // already knows the URL but the store has not yet returned the instance.
-    this.initialTargetUrl = args.initialTargetUrl ?? args.target.id;
-  }
-
-  private get selectedOption(): FormatOption {
-    return (
-      this.formatOptions.find((o) => o.value === this.selectedValue) ??
-      this.formatOptions[0]
-    );
-  }
-
-  private get category(): FormatCategory {
-    return this.selectedOption.category;
-  }
-
-  private get showSizeInputs(): boolean {
-    return this.category === 'fitted' || this.category === 'custom';
-  }
-
-  // The preview renders the selected format in the chosen placement; format and
-  // inline/block are independent (every format works in both modes).
-  private get previewFormat(): EmbedFormat {
-    switch (this.category) {
-      case 'atom':
-        return 'atom';
-      case 'embedded':
-        return 'embedded';
-      case 'isolated':
-        return 'isolated';
-      default:
-        return 'fitted';
-    }
-  }
-
-  // px number, `%` string, or undefined for an unparseable/empty input.
-  private get width(): number | string | undefined {
-    let v = this.widthInput.trim();
-    if (/^\d+%$/.test(v)) return v;
-    if (/^\d+$/.test(v)) return parseInt(v, 10);
-    return undefined;
-  }
-
-  private get height(): number | undefined {
-    let v = this.heightInput.trim();
-    return /^\d+$/.test(v) ? parseInt(v, 10) : undefined;
-  }
-
-  private get sizeSpec(): BfmSizeSpec | undefined {
-    if (!this.showSizeInputs) {
-      return undefined;
-    }
-    return { format: 'fitted', width: this.width, height: this.height };
-  }
-
-  private get categoryLabel(): string {
-    switch (this.category) {
-      case 'atom':
-        return 'Atom';
-      case 'embedded':
-        return 'Embedded';
-      case 'isolated':
-        return 'Isolated';
-      case 'custom':
-        return 'Custom';
-      case 'fitted':
-      default:
-        return 'Fitted';
-    }
-  }
-
   private get ctaLabel(): string {
     if (this.args.ctaLabelOverride !== undefined) {
       return this.args.ctaLabelOverride;
     }
-    return `Insert as ${this.categoryLabel}`;
-  }
-
-  // True once any tracked piece of state (format, placement, W×H, or the
-  // resolved target URL) has diverged from the constructor snapshot. The
-  // parent watches via `onDirtyChange` to drive its CTA label.
-  get isDirty(): boolean {
-    return (
-      this.selectedValue !== this.initialSelectedValue ||
-      this.kind !== this.initialKind ||
-      this.widthInput !== this.initialWidthInput ||
-      this.heightInput !== this.initialHeightInput ||
-      this.args.target.id !== this.initialTargetUrl
-    );
-  }
-
-  // Re-runs on every render. Auto-tracking re-evaluates `isDirty` whenever any
-  // of its dependencies changes; the equality guard keeps onDirtyChange from
-  // firing on every render in addition to genuine transitions.
-  private lastReportedDirty: boolean | undefined;
-  private reportDirty = () => {
-    let dirty = this.isDirty;
-    if (dirty !== this.lastReportedDirty) {
-      this.lastReportedDirty = dirty;
-      this.args.onDirtyChange?.(dirty);
-    }
-  };
-
-  // Size specifier for the chosen format. Atom is the default for inline
-  // placement, so an inline atom embed emits the size-less `:card[url]`;
-  // every other combination carries an explicit specifier so the rendered
-  // format matches the user's choice unambiguously.
-  private get sizeSpecifier(): string | undefined {
-    switch (this.category) {
-      case 'atom':
-        return this.kind === 'inline' ? undefined : 'atom';
-      case 'embedded':
-        return 'embedded';
-      case 'isolated':
-        return 'isolated';
-      case 'fitted':
-        return this.selectedValue;
-      case 'custom':
-        return serializeBfmSizeSpec({
-          format: 'fitted',
-          width: this.width,
-          height: this.height,
-        });
-      default:
-        return undefined;
-    }
+    return `Insert as ${this.args.selection.categoryLabel}`;
   }
 
   private get bfmString(): string {
@@ -310,57 +64,29 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
       return '';
     }
     return serializeBfmRef(this.args.refType, url, {
-      kind: this.kind,
-      size: this.sizeSpecifier,
+      kind: this.args.selection.kind,
+      size: this.args.selection.sizeSpecifier,
     });
   }
 
   @action
   private selectFormat(option: FormatOption) {
-    this.selectedValue = option.value;
-    // Pick a sensible default placement for the format — atom reads as inline,
-    // sized formats as block — but the toggle stays free, so the user can flip
-    // either way afterward.
-    this.kind = option.category === 'atom' ? 'inline' : 'block';
-    if (option.category === 'fitted') {
-      let spec = fittedFormatById.get(option.value as FittedFormatId);
-      if (spec) {
-        this.widthInput = String(spec.width);
-        this.heightInput = String(spec.height);
-      }
-    }
-  }
-
-  // Bidirectional sync: editing either dimension re-points the dropdown to the
-  // matching named variant, or to Custom when nothing matches exactly.
-  private syncVariantFromSize() {
-    let w = this.width;
-    let h = this.height;
-    if (typeof w === 'number' && typeof h === 'number') {
-      let match = FITTED_FORMAT_SIZES.find(
-        (s: FittedFormatSpec) => s.width === w && s.height === h,
-      );
-      this.selectedValue = match ? match.id : 'custom';
-    } else {
-      this.selectedValue = 'custom';
-    }
+    this.args.selection.selectFormat(option);
   }
 
   @action
   private setWidth(value: string) {
-    this.widthInput = value;
-    this.syncVariantFromSize();
+    this.args.selection.setWidth(value);
   }
 
   @action
   private setHeight(value: string) {
-    this.heightInput = value;
-    this.syncVariantFromSize();
+    this.args.selection.setHeight(value);
   }
 
   @action
   private setKind(kind: 'inline' | 'block') {
-    this.kind = kind;
+    this.args.selection.setKind(kind);
   }
 
   @action
@@ -371,7 +97,6 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
   }
 
   <template>
-    {{this.reportDirty}}
     <section
       class='markdown-embed-preview-pane'
       data-test-markdown-embed-preview-pane
@@ -381,8 +106,8 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
         <BoxelSelect
           class='markdown-embed-preview-pane__format-select'
           @dropdownClass='markdown-embed-preview-pane__format-dropdown'
-          @options={{this.formatOptions}}
-          @selected={{this.selectedOption}}
+          @options={{@selection.formatOptions}}
+          @selected={{@selection.selectedOption}}
           @onChange={{this.selectFormat}}
           @searchEnabled={{false}}
           @matchTriggerWidth={{true}}
@@ -406,24 +131,27 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
       <div class='markdown-embed-preview-pane__viewport'>
         <MarkdownEmbedPreview
           @target={{@target}}
-          @format={{this.previewFormat}}
-          @sizeSpec={{this.sizeSpec}}
-          @kind={{this.kind}}
+          @format={{@selection.previewFormat}}
+          @sizeSpec={{@selection.sizeSpec}}
+          @kind={{@selection.kind}}
           @showSurroundingText={{true}}
         />
       </div>
 
       <footer class='markdown-embed-preview-pane__footer'>
-        <PlacementToggle @selected={{this.kind}} @onChange={{this.setKind}} />
+        <PlacementToggle
+          @selected={{@selection.kind}}
+          @onChange={{this.setKind}}
+        />
 
-        {{#if this.showSizeInputs}}
+        {{#if @selection.showSizeInputs}}
           <div
             class='markdown-embed-preview-pane__size'
             data-test-markdown-embed-preview-size
           >
             <BoxelInput
               class='markdown-embed-preview-pane__size-input'
-              @value={{this.widthInput}}
+              @value={{@selection.widthInput}}
               @onInput={{this.setWidth}}
               aria-label='Width'
               data-test-markdown-embed-preview-width
@@ -434,7 +162,7 @@ export default class MarkdownEmbedPreviewPane extends Component<Signature> {
             />
             <BoxelInput
               class='markdown-embed-preview-pane__size-input'
-              @value={{this.heightInput}}
+              @value={{@selection.heightInput}}
               @onInput={{this.setHeight}}
               aria-label='Height'
               data-test-markdown-embed-preview-height
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
index d8fbad31e3..c47f1f666e 100644
--- a/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tab-panel.gts
@@ -12,11 +12,7 @@ import { eq } from '@cardstack/boxel-ui/helpers';
 
 import { isCardErrorJSONAPI } from '@cardstack/runtime-common';
 
-import {
-  type BfmSizeSpec,
-  fileNameFromUrl,
-  parseBfmSizeSpec,
-} from '@cardstack/runtime-common/bfm-card-references';
+import { fileNameFromUrl } from '@cardstack/runtime-common/bfm-card-references';
 
 import MiniCardChooser from '@cardstack/host/components/card-chooser/mini';
 import MiniFileChooser from '@cardstack/host/components/file-chooser/mini';
@@ -29,9 +25,11 @@ import type StoreService from '@cardstack/host/services/store';
 
 import type { CardDef, FileDef } from 'https://cardstack.com/base/card-api';
 
-import MarkdownEmbedPreviewPane, { type OptionValue } from './pane';
+import MarkdownEmbedPreviewPane from './pane';
 import TabPills from './tab-pills';
 
+import type EmbedFormatSelection from './format-selection';
+
 interface Signature {
   Element: HTMLDivElement;
   Args: {
@@ -44,9 +42,13 @@ interface Signature {
     activeTab: MarkdownEmbedRefType;
     onTabChange: (tab: MarkdownEmbedRefType) => void;
     onInsert: (bfm: string, url: string) => void;
+    // The shared format/placement/size selection, owned by the modal and
+    // passed to both tabs' panes so the choice sticks across a tab switch.
+    selection: EmbedFormatSelection;
     // Optional edit-mode preload for this tab. When set, the tab starts in
-    // `current` mode showing the placed target with Replace / Remove buttons;
-    // the pane is seeded with the matching size + placement.
+    // `current` mode showing the placed target with Replace / Remove buttons.
+    // (The pane's format seed comes from the shared `@selection`, which the
+    // modal seeds from this same target.)
     initialTarget?: MarkdownEmbedInitialTarget;
     // Fired when the user clicks "Remove" in `current` mode. The modal
     // resolves its deferred with `{ remove: true }`.
@@ -67,12 +69,6 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
   @tracked private selectedTarget: CardDef | FileDef | undefined;
   @tracked private selectedUrl: string | undefined;
   @tracked private mode: 'choose' | 'current' = 'choose';
-  @tracked private dirty = false;
-
-  private initialPaneFormat: OptionValue | undefined;
-  private initialPaneWidth: number | string | undefined;
-  private initialPaneHeight: number | undefined;
-  private initialPaneKind: 'inline' | 'block' | undefined;
 
   constructor(owner: Owner, args: Signature['Args']) {
     super(owner, args);
@@ -80,11 +76,6 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
     if (it) {
       this.mode = 'current';
       this.selectedUrl = it.url;
-      let derived = derivePaneSeeds(normalizeSizeSpec(it.sizeSpec));
-      this.initialPaneFormat = derived.format;
-      this.initialPaneWidth = derived.width;
-      this.initialPaneHeight = derived.height;
-      this.initialPaneKind = derived.kind;
       this.loadTarget.perform(it.url, it.refType);
     }
   }
@@ -93,12 +84,27 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
     return !!this.args.initialTarget;
   }
 
+  // URL currently staged for insertion: the resolved target wins, falling back
+  // to the picked URL while its instance is still loading.
+  private get currentUrl(): string | undefined {
+    return this.selectedTarget?.id ?? this.selectedUrl;
+  }
+
+  // In edit mode, the user has diverged once either the shared format selection
+  // changed or they swapped in a different target (Replace).
+  private get targetChanged(): boolean {
+    let initial = this.args.initialTarget?.url;
+    if (initial === undefined) return false;
+    return this.currentUrl !== initial;
+  }
+
   // 'DONE' until the user diverges from the initial preload, 'ACCEPT' once
   // they do — matches Zeplin 08B. Non-edit (choose) tabs keep the dynamic
   // "Insert as …" label.
   private get ctaLabelOverride(): string | undefined {
     if (!this.isEditMode) return undefined;
-    return this.dirty ? 'ACCEPT' : 'DONE';
+    let dirty = this.args.selection.isDirty || this.targetChanged;
+    return dirty ? 'ACCEPT' : 'DONE';
   }
 
   private get currentTargetLabel(): string {
@@ -121,9 +127,13 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
   }
 
   // Restart on every pick so a slow earlier load can't stomp the newer one.
+  // Clear `selectedTarget` up front so the pane unmounts to its placeholder
+  // while the new instance loads — otherwise a quick Insert during the load
+  // window would serialize the previously-resolved target's URL.
   private loadTarget = restartableTask(
     async (url: string, refType: MarkdownEmbedRefType) => {
       this.selectedUrl = url;
+      this.selectedTarget = undefined;
       let result =
         refType === 'card'
           ? await this.store.get(url)
@@ -138,16 +148,11 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
 
   @action
   private handleInsert(bfm: string) {
-    let url = this.selectedTarget?.id ?? this.selectedUrl;
+    let url = this.currentUrl;
     if (!url) return;
     this.args.onInsert(bfm, url);
   }
 
-  @action
-  private onPaneDirtyChange(dirty: boolean) {
-    this.dirty = dirty;
-  }
-
   @action
   private startReplace() {
     this.mode = 'choose';
@@ -225,14 +230,9 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
           <MarkdownEmbedPreviewPane
             @target={{this.selectedTarget}}
             @refType={{@refType}}
+            @selection={{@selection}}
             @onInsert={{this.handleInsert}}
-            @initialFormat={{this.initialPaneFormat}}
-            @initialWidth={{this.initialPaneWidth}}
-            @initialHeight={{this.initialPaneHeight}}
-            @initialKind={{this.initialPaneKind}}
-            @initialTargetUrl={{@initialTarget.url}}
             @ctaLabelOverride={{this.ctaLabelOverride}}
-            @onDirtyChange={{this.onPaneDirtyChange}}
           />
         {{else}}
           <p
@@ -295,8 +295,8 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
         flex-direction: column;
         min-height: 0;
         /* The preview column reads as an off-white surface, distinct from the
-           white chooser column on the left. */
-        background-color: #fbf8f8;
+           white chooser column on the left — same token as the inner viewport. */
+        background-color: var(--boxel-100);
       }
       /* Centered placeholder shown until a row is picked and its instance
          resolves; the pane mounts in its place once a target arrives. */
@@ -331,42 +331,3 @@ export default class MarkdownEmbedChooserTabPanel extends Component<Signature> {
     </style>
   </template>
 }
-
-function normalizeSizeSpec(
-  input: BfmSizeSpec | string | undefined,
-): BfmSizeSpec | undefined {
-  if (!input) return undefined;
-  if (typeof input === 'string') {
-    return parseBfmSizeSpec(input) ?? undefined;
-  }
-  return input;
-}
-
-interface PaneSeeds {
-  format?: OptionValue;
-  width?: number | string;
-  height?: number;
-  kind?: 'inline' | 'block';
-}
-
-function derivePaneSeeds(spec: BfmSizeSpec | undefined): PaneSeeds {
-  if (!spec) {
-    return {};
-  }
-  if (spec.format === 'atom') {
-    return { format: 'atom', kind: 'inline' };
-  }
-  if (spec.format === 'embedded') {
-    return { format: 'embedded', kind: 'block' };
-  }
-  if (spec.format === 'isolated') {
-    return { format: 'isolated', kind: 'block' };
-  }
-  // Fitted with optional W×H.
-  return {
-    format: 'custom',
-    width: spec.width,
-    height: spec.height,
-    kind: 'block',
-  };
-}
diff --git a/packages/host/app/components/markdown-embed-chooser/tab-pills.gts b/packages/host/app/components/markdown-embed-chooser/tab-pills.gts
index 4a6ec3cea6..6ed2d5aee1 100644
--- a/packages/host/app/components/markdown-embed-chooser/tab-pills.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tab-pills.gts
@@ -2,7 +2,7 @@ import type { TemplateOnlyComponent } from '@ember/component/template-only';
 import { fn } from '@ember/helper';
 import { on } from '@ember/modifier';
 
-import { eq } from '@cardstack/boxel-ui/helpers';
+import { cn, eq } from '@cardstack/boxel-ui/helpers';
 
 import type { MarkdownEmbedRefType } from '@cardstack/host/services/markdown-embed-chooser';
 
@@ -33,8 +33,10 @@ const MarkdownEmbedChooserTabPills: TemplateOnlyComponent<Signature> =
         aria-controls='markdown-embed-chooser-panel-cards'
         aria-selected={{if (eq @activeTab 'card') 'true' 'false'}}
         tabindex={{if (eq @activeTab 'card') '0' '-1'}}
-        class='markdown-embed-chooser-tab-pills__tab
-          {{if (eq @activeTab "card") "is-active"}}'
+        class={{cn
+          'markdown-embed-chooser-tab-pills__tab'
+          is-active=(eq @activeTab 'card')
+        }}
         data-test-markdown-embed-chooser-tab='card'
         {{on 'click' (fn @onTabChange 'card')}}
       >
@@ -47,8 +49,10 @@ const MarkdownEmbedChooserTabPills: TemplateOnlyComponent<Signature> =
         aria-controls='markdown-embed-chooser-panel-files'
         aria-selected={{if (eq @activeTab 'file') 'true' 'false'}}
         tabindex={{if (eq @activeTab 'file') '0' '-1'}}
-        class='markdown-embed-chooser-tab-pills__tab
-          {{if (eq @activeTab "file") "is-active"}}'
+        class={{cn
+          'markdown-embed-chooser-tab-pills__tab'
+          is-active=(eq @activeTab 'file')
+        }}
         data-test-markdown-embed-chooser-tab='file'
         {{on 'click' (fn @onTabChange 'file')}}
       >
diff --git a/packages/host/app/components/markdown-embed-chooser/tabs.gts b/packages/host/app/components/markdown-embed-chooser/tabs.gts
index e376d9434a..d42b9a14f0 100644
--- a/packages/host/app/components/markdown-embed-chooser/tabs.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tabs.gts
@@ -1,6 +1,6 @@
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
 
-import { eq } from '@cardstack/boxel-ui/helpers';
+import { cn, eq } from '@cardstack/boxel-ui/helpers';
 
 import type { MarkdownEmbedRefType } from '@cardstack/host/services/markdown-embed-chooser';
 
@@ -28,8 +28,10 @@ const MarkdownEmbedChooserTabs: TemplateOnlyComponent<Signature> = <template>
       role='tabpanel'
       id='markdown-embed-chooser-panel-cards'
       aria-labelledby='markdown-embed-chooser-tab-cards'
-      class='markdown-embed-chooser-tabs__panel
-        {{unless (eq @activeTab "card") "is-hidden"}}'
+      class={{cn
+        'markdown-embed-chooser-tabs__panel'
+        is-hidden=(unless (eq @activeTab 'card') true)
+      }}
       data-test-markdown-embed-chooser-panel='card'
     >
       {{yield to='cards'}}
@@ -38,8 +40,10 @@ const MarkdownEmbedChooserTabs: TemplateOnlyComponent<Signature> = <template>
       role='tabpanel'
       id='markdown-embed-chooser-panel-files'
       aria-labelledby='markdown-embed-chooser-tab-files'
-      class='markdown-embed-chooser-tabs__panel
-        {{unless (eq @activeTab "file") "is-hidden"}}'
+      class={{cn
+        'markdown-embed-chooser-tabs__panel'
+        is-hidden=(unless (eq @activeTab 'file') true)
+      }}
       data-test-markdown-embed-chooser-panel='file'
     >
       {{yield to='files'}}
diff --git a/packages/host/app/services/markdown-embed-chooser.ts b/packages/host/app/services/markdown-embed-chooser.ts
index fdb0b25409..aad2b79449 100644
--- a/packages/host/app/services/markdown-embed-chooser.ts
+++ b/packages/host/app/services/markdown-embed-chooser.ts
@@ -25,6 +25,10 @@ export interface MarkdownEmbedInitialTarget {
   // Either a pre-parsed `BfmSizeSpec` (from extractBfmRefRanges) or the raw
   // specifier text after `|`. The pane parses the string form itself.
   sizeSpec?: BfmSizeSpec | string;
+  // The directive's placement (`::` block vs `:` inline). Carried separately
+  // from `sizeSpec` so a size-less block directive (`::card[url]`) seeds block
+  // placement instead of collapsing to an inline atom.
+  kind?: 'inline' | 'block';
 }
 
 export interface MarkdownEmbedChooserRequest {
diff --git a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
index 3d8b736e2d..a136f299af 100644
--- a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
+++ b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
@@ -75,14 +75,25 @@ class HostContextProvider extends GlimmerComponent<{
 }
 
 // Tracked content harness so the editor's onUpdate updates the same
-// `@content` arg we read for assertions.
+// `@content` arg we read for assertions. `calls` counts onUpdate invocations
+// so a test can prove a single edit doesn't save twice.
 class ContentHarness {
   @tracked content = '';
+  calls = 0;
   set = (text: string) => {
+    this.calls += 1;
     this.content = text;
   };
 }
 
+// The editor debounces saves by SAVE_DEBOUNCE_MS (500ms); a raw setTimeout is
+// not tracked by `settled()`, so wait it out explicitly to catch a stray
+// debounced save firing after the immediate one.
+const SAVE_DEBOUNCE_MS = 500;
+function waitOutDebounce() {
+  return new Promise((resolve) => setTimeout(resolve, SAVE_DEBOUNCE_MS + 200));
+}
+
 async function loadCodeMirrorEditor() {
   let loader = (getService('loader-service') as LoaderService).loader;
   let mod = (await loader.import(
@@ -160,6 +171,9 @@ module('Integration | codemirror embed toolbar', function (hooks) {
   });
 
   const mango = `${testRealmURL}books/mango`;
+  // Same URL length as mango so an in-place swap leaves the directive's
+  // from/to unchanged — the exact case `sameToolbarState` must not dedupe away.
+  const manga = `${testRealmURL}books/manga`;
 
   hooks.beforeEach(async function (this: RenderingTestContext) {
     class Book extends CardDef {
@@ -172,6 +186,7 @@ module('Integration | codemirror embed toolbar', function (hooks) {
       contents: {
         'book.gts': { Book },
         'books/mango.json': new Book({ title: 'Mango' }),
+        'books/manga.json': new Book({ title: 'Manga' }),
       },
     });
     await getService('realm').login(testRealmURL);
@@ -280,4 +295,120 @@ module('Integration | codemirror embed toolbar', function (hooks) {
       'Remove deletes the directive from the source',
     );
   });
+
+  test('Remove saves exactly once (no duplicate debounced save)', async function (assert) {
+    let harness = new ContentHarness();
+    harness.content = `:card[${mango}]`;
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-codemirror-editor] .cm-content', {
+      timeout: 5000,
+    });
+    let editor = document.querySelector(
+      '[data-test-codemirror-editor] .cm-editor',
+    ) as HTMLElement | null;
+    let view = editor ? cmContext.EditorView.findFromDOM(editor) : null;
+    view?.focus();
+    view?.dispatch({ selection: { anchor: 3, head: 3 } });
+
+    await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
+    await click('[data-test-toolbar="edit-embed"]');
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+    await click('[data-test-markdown-embed-chooser-remove]');
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+    await settled();
+
+    assert.strictEqual(harness.calls, 1, 'the delete saved immediately, once');
+    await waitOutDebounce();
+    assert.strictEqual(
+      harness.calls,
+      1,
+      'no second save fires after the debounce window',
+    );
+  });
+
+  test('Accepting an edit saves exactly once (no duplicate debounced save)', async function (assert) {
+    let harness = new ContentHarness();
+    harness.content = `:card[${mango}]`;
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-codemirror-editor] .cm-content', {
+      timeout: 5000,
+    });
+    let editor = document.querySelector(
+      '[data-test-codemirror-editor] .cm-editor',
+    ) as HTMLElement | null;
+    let view = editor ? cmContext.EditorView.findFromDOM(editor) : null;
+    view?.focus();
+    view?.dispatch({ selection: { anchor: 3, head: 3 } });
+
+    await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
+    await click('[data-test-toolbar="edit-embed"]');
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Change the format so the CTA becomes ACCEPT, then accept the edit — this
+    // routes through `_replaceRange`, which must also cancel the debounce.
+    await click('[data-test-markdown-embed-preview-format-select]');
+    await waitFor('.ember-power-select-option', { timeout: 3000 });
+    await click('[data-test-format-option="embedded"]');
+    await click('[data-test-markdown-embed-preview-cta]');
+    await waitUntil(
+      () => !document.querySelector('[data-test-markdown-embed-chooser-modal]'),
+    );
+    await settled();
+
+    assert.strictEqual(
+      harness.content,
+      `::card[${mango} | embedded]`,
+      'the edit replaced the directive in place',
+    );
+    assert.strictEqual(harness.calls, 1, 'the replace saved immediately, once');
+    await waitOutDebounce();
+    assert.strictEqual(
+      harness.calls,
+      1,
+      'no second save fires after the debounce window',
+    );
+  });
+
+  test('an in-place URL edit refreshes the directive the pencil acts on', async function (assert) {
+    let content = `:card[${mango}]`;
+    let harness = new ContentHarness();
+    harness.content = content;
+    await renderEditorAndModal({ CodeMirrorEditor, harness });
+
+    await waitFor('[data-test-codemirror-editor] .cm-content', {
+      timeout: 5000,
+    });
+    let editor = document.querySelector(
+      '[data-test-codemirror-editor] .cm-editor',
+    ) as HTMLElement | null;
+    let view = editor ? cmContext.EditorView.findFromDOM(editor) : null;
+    view?.focus();
+    view?.dispatch({ selection: { anchor: 3, head: 3 } });
+    await waitFor('[data-test-toolbar="edit-embed"]', { timeout: 5000 });
+
+    // Rewrite the URL's last character in place (mango → manga) without moving
+    // the cursor. The directive keeps the same from/to, so a from/to-only
+    // comparison would keep targeting the stale URL.
+    let oPos = content.lastIndexOf('mango') + 'mango'.length - 1;
+    view?.dispatch({ changes: { from: oPos, to: oPos + 1, insert: 'a' } });
+    await settled();
+
+    await click('[data-test-toolbar="edit-embed"]');
+    await waitFor('[data-test-markdown-embed-chooser-current-label]', {
+      timeout: 5000,
+    });
+    assert
+      .dom('[data-test-markdown-embed-chooser-current-label]')
+      .hasText(
+        'Manga',
+        'the pencil edits the freshly-typed URL, not the stale one',
+      );
+
+    // (sanity) the edited document holds the new URL.
+    assert.strictEqual(harness.content, `:card[${manga}]`);
+  });
 });
diff --git a/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
index 8a8bad747d..f0f87cbc51 100644
--- a/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
+++ b/packages/host/tests/integration/components/markdown-embed-chooser-modal-test.gts
@@ -83,6 +83,18 @@ module('Integration | markdown-embed-chooser-modal', function (hooks) {
   });
 
   const mango = `${testRealmURL}books/mango`;
+  const readme = `${testRealmURL}readme.txt`;
+
+  // Open the format dropdown scoped to one tab-panel and pick an option. The
+  // dropdown renders in the power-select wormhole, so the option selector is
+  // global once the menu is open.
+  async function chooseFormatIn(tab: 'card' | 'file', value: string) {
+    await click(
+      `[data-test-markdown-embed-chooser-tab-panel="${tab}"] [data-test-markdown-embed-preview-format-select]`,
+    );
+    await waitFor('.ember-power-select-option', { timeout: 3000 });
+    await click(`[data-test-format-option="${value}"]`);
+  }
 
   hooks.beforeEach(async function (this: RenderingTestContext) {
     class Book extends CardDef {
@@ -97,6 +109,7 @@ module('Integration | markdown-embed-chooser-modal', function (hooks) {
         'books/mango.json': new Book({ title: 'Mango' }),
         'books/vincent.json': new Book({ title: 'Vincent' }),
         'notes/hello.txt': 'hello',
+        'readme.txt': 'readme',
       },
     });
     await getService('realm').login(testRealmURL);
@@ -350,4 +363,110 @@ module('Integration | markdown-embed-chooser-modal', function (hooks) {
       'resolves with the serialized BFM directive for the picked card',
     );
   });
+
+  test('the chosen format sticks when switching from the cards tab to the files tab', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    let pending = svc.chooseCardOrFile({ defaultTab: 'card' });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Pick a card and switch its format away from the default atom.
+    await fillIn(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-search-field]',
+      'Mango',
+    );
+    await waitFor(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mango}"]`,
+      { timeout: 5000 },
+    );
+    await click(
+      `[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-item-button="${mango}"]`,
+    );
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    await chooseFormatIn('card', 'embedded');
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview-cta]',
+      )
+      .hasText('Insert as Embedded');
+
+    // Switch to the files tab and pick a file: the preview format carries over
+    // rather than resetting to atom (the two tabs share one format selection).
+    await click('[data-test-markdown-embed-chooser-tab="file"]');
+    await waitFor(
+      '[data-test-mini-file-chooser] [data-test-file="readme.txt"]',
+      {
+        timeout: 5000,
+      },
+    );
+    await click('[data-test-mini-file-chooser] [data-test-file="readme.txt"]');
+    await waitFor(
+      '[data-test-markdown-embed-chooser-tab-panel="file"] [data-test-markdown-embed-preview-cta]:not([disabled])',
+      { timeout: 5000 },
+    );
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="file"] [data-test-markdown-embed-preview-cta]',
+      )
+      .hasText('Insert as Embedded', 'the format stuck across the tab switch');
+
+    await click(
+      '[data-test-markdown-embed-chooser-tab-panel="file"] [data-test-markdown-embed-preview-cta]',
+    );
+    let result = await pending;
+    assert.deepEqual(
+      result,
+      { refType: 'file', url: readme, bfm: `::file[${readme} | embedded]` },
+      'the file directive carries the format chosen on the cards tab',
+    );
+  });
+
+  test('editing a size-less block directive preserves block placement', async function (assert) {
+    await render(
+      <template>
+        <HostContextProvider>
+          <MarkdownEmbedChooserModal />
+        </HostContextProvider>
+      </template>,
+    );
+
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    // `::card[url]` — block placement, no size specifier.
+    let pending = svc.editEmbed({ refType: 'card', url: mango, kind: 'block' });
+    await waitFor('[data-test-markdown-embed-chooser-modal]');
+
+    // Clean preload, so the CTA reads DONE; the seeded format reflects what a
+    // size-less block embed actually renders as (embedded), not inline atom.
+    await waitFor('[data-test-markdown-embed-preview-cta]:not([disabled])', {
+      timeout: 5000,
+    });
+    assert
+      .dom(
+        '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview-cta]',
+      )
+      .hasText('DONE', 'a clean edit keeps the DONE label');
+
+    await click(
+      '[data-test-markdown-embed-chooser-tab-panel="card"] [data-test-markdown-embed-preview-cta]',
+    );
+    let result = await pending;
+    assert.deepEqual(
+      result,
+      { refType: 'card', url: mango, bfm: `::card[${mango} | embedded]` },
+      'DONE re-serializes a block directive — not a collapsed inline atom',
+    );
+  });
 });
diff --git a/packages/host/tests/integration/components/markdown-embed-preview-pane-test.gts b/packages/host/tests/integration/components/markdown-embed-preview-pane-test.gts
index 5d2f341ffa..36807c37e0 100644
--- a/packages/host/tests/integration/components/markdown-embed-preview-pane-test.gts
+++ b/packages/host/tests/integration/components/markdown-embed-preview-pane-test.gts
@@ -22,6 +22,7 @@ import {
   GetCardsContextName,
 } from '@cardstack/runtime-common';
 
+import EmbedFormatSelection from '@cardstack/host/components/markdown-embed-chooser/format-selection';
 import MarkdownEmbedPreviewPane from '@cardstack/host/components/markdown-embed-chooser/pane';
 import { getCardCollection } from '@cardstack/host/resources/card-collection';
 import { getCard } from '@cardstack/host/resources/card-resource';
@@ -143,6 +144,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('atom is the default; both placements are available', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -150,6 +152,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -188,6 +191,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('embedded emits a block directive with the embedded keyword', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -195,6 +199,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -217,6 +222,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('the preview tracks the selected format in either placement', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -224,6 +230,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -255,6 +262,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('fitted variant prefills W/H and emits the variant id in both placements', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -262,6 +270,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -301,6 +310,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('editing W/H to unknown dims switches to Custom and emits w:/h:', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -308,6 +318,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -330,6 +341,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('editing W/H to a known variant follows the dropdown to that variant', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -337,6 +349,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -367,6 +380,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('isolated emits in both placements', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -374,6 +388,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -412,6 +427,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('inline + embedded emits the explicit specifier on CTA', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -419,6 +435,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -439,6 +456,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('inline + custom dimensions emit w:/h: in the inline directive', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -446,6 +464,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -468,6 +487,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('refType drives the keyword (file)', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -475,6 +495,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='file'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
@@ -497,6 +518,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
   test('atom, embedded, isolated carry the has-divider modifier; fitted/custom do not', async function (assert) {
     let card = await loadCard();
     let harness = new InsertHarness();
+    let selection = new EmbedFormatSelection();
     await render(
       <template>
         <PaneBox>
@@ -504,6 +526,7 @@ module('Integration | markdown-embed-preview-pane', function (hooks) {
             <MarkdownEmbedPreviewPane
               @target={{card}}
               @refType='card'
+              @selection={{selection}}
               @onInsert={{harness.onInsert}}
             />
           </HostContextProvider>
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
index 20b1df4894..4e213936f1 100644
--- a/packages/runtime-common/bfm-card-references.ts
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -352,6 +352,10 @@ export interface MarkdownEmbedInitialTarget {
   url: string;
   // Either a pre-parsed `BfmSizeSpec` or the raw specifier text after `|`.
   sizeSpec?: BfmSizeSpec | string;
+  // The directive's placement (`::` block vs `:` inline), carried separately
+  // from `sizeSpec` so a size-less block directive seeds block placement
+  // instead of collapsing to an inline atom.
+  kind?: 'inline' | 'block';
 }
 
 export interface MarkdownEmbedChooser {
@@ -395,9 +399,10 @@ export async function editMarkdownEmbed(
 
 export interface BfmRefRange {
   kind: 'inline' | 'block';
-  // Half-open byte range into the original markdown string: `markdown.slice(
-  // from, to)` reproduces the directive verbatim. Suitable for a CodeMirror
-  // dispatch that replaces or deletes the directive in place.
+  // Half-open range into the original markdown string as UTF-16 code-unit
+  // offsets (i.e. JS string indices, the same units CodeMirror positions use):
+  // `markdown.slice(from, to)` reproduces the directive verbatim. Suitable for
+  // a CodeMirror dispatch that replaces or deletes the directive in place.
   from: number;
   to: number;
   refType: string;
@@ -410,8 +415,9 @@ export interface BfmRefRange {
 }
 
 /**
- * Locates every BFM reference site in `markdown` and returns its source-byte
- * range, refType, URL, and size specifier (verbatim — no URL resolution).
+ * Locates every BFM reference site in `markdown` and returns its source
+ * character range (UTF-16 code-unit offsets), refType, URL, and size specifier
+ * (verbatim — no URL resolution).
  *
  * Differs from `extractBfmReferences` in two ways: indices are into the
  * ORIGINAL markdown (not a code-stripped copy), and matches are not

From 047c8c05a0878b228438269aa593f77ff93d320e Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Tue, 30 Jun 2026 09:29:32 +0700
Subject: [PATCH 11/12] Fix shared format selection losing state across renders
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The modal exposed the shared EmbedFormatSelection via an `@cached` getter, but
the model's constructor reads its own tracked fields to snapshot the initial
state — so the cached getter took a dependency on those fields and invalidated
itself the moment the user changed the format, handing back a fresh atom
instance and discarding the choice. This broke format stickiness in the app,
not just the tests.

Own the selection in the Tabs component instead, which lives inside the modal's
`{{#if request}}` block: it's created once per chooser invocation (seeded from
the edited directive) and torn down on close, giving both tab panels a stable
shared instance. Tabs yields it to each tab block.

Also fix the in-place-edit test to assert on the chooser request's target URL
rather than the rendered card title (the fixture cards render the same
placeholder title, so the label couldn't distinguish them).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../markdown-embed-chooser/modal.gts          |  35 +++---
 .../markdown-embed-chooser/tabs.gts           | 118 ++++++++++--------
 .../codemirror-embed-toolbar-test.gts         |  28 +++--
 3 files changed, 103 insertions(+), 78 deletions(-)

diff --git a/packages/host/app/components/markdown-embed-chooser/modal.gts b/packages/host/app/components/markdown-embed-chooser/modal.gts
index 39b99c2960..fe8e1825f6 100644
--- a/packages/host/app/components/markdown-embed-chooser/modal.gts
+++ b/packages/host/app/components/markdown-embed-chooser/modal.gts
@@ -5,7 +5,7 @@ import { action } from '@ember/object';
 import type Owner from '@ember/owner';
 import { service } from '@ember/service';
 import Component from '@glimmer/component';
-import { cached, tracked } from '@glimmer/tracking';
+import { tracked } from '@glimmer/tracking';
 
 import focusTrap from 'ember-focus-trap/modifiers/focus-trap';
 
@@ -17,7 +17,10 @@ import type {
   MarkdownEmbedRefType,
 } from '@cardstack/host/services/markdown-embed-chooser';
 
-import EmbedFormatSelection, { deriveFormatSeeds } from './format-selection';
+import {
+  deriveFormatSeeds,
+  type FormatSelectionSeeds,
+} from './format-selection';
 import TabPanel from './tab-panel';
 import Tabs from './tabs';
 
@@ -62,17 +65,15 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
     return this.markdownEmbedChooser.currentRequest;
   }
 
-  // One format/placement/size selection shared by both tabs so the choice
-  // sticks across a tab switch. `@cached` keyed on the tracked `request`
-  // rebuilds it once per chooser invocation (seeded from the edited directive
-  // in edit mode) while returning the same instance across tab switches within
-  // the same open session.
-  @cached
-  get selection(): EmbedFormatSelection {
+  // Seeds for the shared format selection. `Tabs` owns the actual
+  // `EmbedFormatSelection` instance — it lives inside the `{{#if this.request}}`
+  // block, so it's created once per chooser invocation (seeded here from the
+  // edited directive in edit mode) and torn down on close. Owning it there,
+  // rather than in a getter on this persistent component, keeps the instance
+  // stable across re-renders so the user's choice actually sticks.
+  get formatSeeds(): FormatSelectionSeeds {
     let it = this.request?.initialTarget;
-    return new EmbedFormatSelection(
-      it ? deriveFormatSeeds(it.sizeSpec, it.kind) : {},
-    );
+    return it ? deriveFormatSeeds(it.sizeSpec, it.kind) : {};
   }
 
   get activeTab(): MarkdownEmbedRefType {
@@ -148,25 +149,25 @@ export default class MarkdownEmbedChooserModal extends Component<Signature> {
         data-test-markdown-embed-chooser-modal
       >
         <:content>
-          <Tabs @activeTab={{this.activeTab}}>
-            <:cards>
+          <Tabs @activeTab={{this.activeTab}} @seeds={{this.formatSeeds}}>
+            <:cards as |selection|>
               <TabPanel
                 @refType='card'
                 @activeTab={{this.activeTab}}
                 @onTabChange={{this.setActiveTab}}
                 @onInsert={{this.handleInsertCard}}
-                @selection={{this.selection}}
+                @selection={{selection}}
                 @initialTarget={{this.cardInitialTarget}}
                 @onRemove={{this.handleRemove}}
               />
             </:cards>
-            <:files>
+            <:files as |selection|>
               <TabPanel
                 @refType='file'
                 @activeTab={{this.activeTab}}
                 @onTabChange={{this.setActiveTab}}
                 @onInsert={{this.handleInsertFile}}
-                @selection={{this.selection}}
+                @selection={{selection}}
                 @initialTarget={{this.fileInitialTarget}}
                 @onRemove={{this.handleRemove}}
               />
diff --git a/packages/host/app/components/markdown-embed-chooser/tabs.gts b/packages/host/app/components/markdown-embed-chooser/tabs.gts
index d42b9a14f0..dc8ad76905 100644
--- a/packages/host/app/components/markdown-embed-chooser/tabs.gts
+++ b/packages/host/app/components/markdown-embed-chooser/tabs.gts
@@ -1,70 +1,84 @@
-import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import Component from '@glimmer/component';
 
 import { cn, eq } from '@cardstack/boxel-ui/helpers';
 
 import type { MarkdownEmbedRefType } from '@cardstack/host/services/markdown-embed-chooser';
 
+import EmbedFormatSelection, {
+  type FormatSelectionSeeds,
+} from './format-selection';
+
 interface Signature {
   Element: HTMLDivElement;
   Args: {
     activeTab: MarkdownEmbedRefType;
+    // Initial format/placement/size for the shared selection (edit-mode preload
+    // in the modal; empty in choose mode).
+    seeds: FormatSelectionSeeds;
   };
   Blocks: {
-    cards: [];
-    files: [];
+    cards: [EmbedFormatSelection];
+    files: [EmbedFormatSelection];
   };
 }
 
 // The two tabpanels for the combined chooser. The matching segmented pill
 // control sits at the top of each panel's left search column (see
 // `tab-pills.gts`); each panel's `aria-labelledby` points back to its pill
-// button by id. Both panels stay
-// mounted — the inactive one is `display: none` rather than `{{#if}}`'d out —
-// so each tab's mini-chooser keeps its search query, highlighted row, scroll
-// position, and the pane's W×H / format selection across a switch.
-const MarkdownEmbedChooserTabs: TemplateOnlyComponent<Signature> = <template>
-  <div class='markdown-embed-chooser-tabs' ...attributes>
-    <div
-      role='tabpanel'
-      id='markdown-embed-chooser-panel-cards'
-      aria-labelledby='markdown-embed-chooser-tab-cards'
-      class={{cn
-        'markdown-embed-chooser-tabs__panel'
-        is-hidden=(unless (eq @activeTab 'card') true)
-      }}
-      data-test-markdown-embed-chooser-panel='card'
-    >
-      {{yield to='cards'}}
-    </div>
-    <div
-      role='tabpanel'
-      id='markdown-embed-chooser-panel-files'
-      aria-labelledby='markdown-embed-chooser-tab-files'
-      class={{cn
-        'markdown-embed-chooser-tabs__panel'
-        is-hidden=(unless (eq @activeTab 'file') true)
-      }}
-      data-test-markdown-embed-chooser-panel='file'
-    >
-      {{yield to='files'}}
-    </div>
-  </div>
-  <style scoped>
-    .markdown-embed-chooser-tabs {
-      display: flex;
-      flex-direction: column;
-      width: 100%;
-      height: 100%;
-      min-height: 0;
-    }
-    .markdown-embed-chooser-tabs__panel {
-      flex: 1 1 auto;
-      min-height: 0;
-    }
-    .markdown-embed-chooser-tabs__panel.is-hidden {
-      display: none;
-    }
-  </style>
-</template>;
+// button by id. Both panels stay mounted — the inactive one is `display: none`
+// rather than `{{#if}}`'d out — so each tab's mini-chooser keeps its search
+// query, highlighted row, scroll position, and the pane's W×H / format
+// selection across a switch.
+export default class MarkdownEmbedChooserTabs extends Component<Signature> {
+  // Created once per modal-open: this component lives inside the modal's
+  // `{{#if request}}` block, so it (and the selection) is torn down on close
+  // and rebuilt on the next chooser invocation — seeded from the edited
+  // directive in edit mode. Yielded to both tab blocks so the format choice
+  // is shared and survives a tab switch.
+  private selection = new EmbedFormatSelection(this.args.seeds);
 
-export default MarkdownEmbedChooserTabs;
+  <template>
+    <div class='markdown-embed-chooser-tabs' ...attributes>
+      <div
+        role='tabpanel'
+        id='markdown-embed-chooser-panel-cards'
+        aria-labelledby='markdown-embed-chooser-tab-cards'
+        class={{cn
+          'markdown-embed-chooser-tabs__panel'
+          is-hidden=(unless (eq @activeTab 'card') true)
+        }}
+        data-test-markdown-embed-chooser-panel='card'
+      >
+        {{yield this.selection to='cards'}}
+      </div>
+      <div
+        role='tabpanel'
+        id='markdown-embed-chooser-panel-files'
+        aria-labelledby='markdown-embed-chooser-tab-files'
+        class={{cn
+          'markdown-embed-chooser-tabs__panel'
+          is-hidden=(unless (eq @activeTab 'file') true)
+        }}
+        data-test-markdown-embed-chooser-panel='file'
+      >
+        {{yield this.selection to='files'}}
+      </div>
+    </div>
+    <style scoped>
+      .markdown-embed-chooser-tabs {
+        display: flex;
+        flex-direction: column;
+        width: 100%;
+        height: 100%;
+        min-height: 0;
+      }
+      .markdown-embed-chooser-tabs__panel {
+        flex: 1 1 auto;
+        min-height: 0;
+      }
+      .markdown-embed-chooser-tabs__panel.is-hidden {
+        display: none;
+      }
+    </style>
+  </template>
+}
diff --git a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
index a136f299af..e11088217d 100644
--- a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
+++ b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
@@ -30,6 +30,7 @@ import cmContext from '@cardstack/host/lib/codemirror-context';
 import { getCardCollection } from '@cardstack/host/resources/card-collection';
 import { getCard } from '@cardstack/host/resources/card-resource';
 import type LoaderService from '@cardstack/host/services/loader-service';
+import type MarkdownEmbedChooserService from '@cardstack/host/services/markdown-embed-chooser';
 import type StoreService from '@cardstack/host/services/store';
 
 import {
@@ -397,18 +398,27 @@ module('Integration | codemirror embed toolbar', function (hooks) {
     view?.dispatch({ changes: { from: oPos, to: oPos + 1, insert: 'a' } });
     await settled();
 
+    // (sanity) the edited document holds the new URL.
+    assert.strictEqual(harness.content, `:card[${manga}]`);
+
     await click('[data-test-toolbar="edit-embed"]');
-    await waitFor('[data-test-markdown-embed-chooser-current-label]', {
+    await waitFor('[data-test-markdown-embed-chooser-modal]', {
       timeout: 5000,
     });
-    assert
-      .dom('[data-test-markdown-embed-chooser-current-label]')
-      .hasText(
-        'Manga',
-        'the pencil edits the freshly-typed URL, not the stale one',
-      );
 
-    // (sanity) the edited document holds the new URL.
-    assert.strictEqual(harness.content, `:card[${manga}]`);
+    // The pencil opens the chooser against the URL currently under the cursor.
+    // Asserting on the request (rather than the rendered title, which is the
+    // same placeholder for both fixture cards) isolates the toolbar-state
+    // refresh: before the fix it would still target the stale `mango`.
+    let svc = getService(
+      'markdown-embed-chooser',
+    ) as MarkdownEmbedChooserService;
+    assert.strictEqual(
+      svc.currentRequest?.initialTarget?.url,
+      manga,
+      'the pencil edits the freshly-typed URL, not the stale one',
+    );
+    svc.resolve(undefined);
+    await settled();
   });
 });

From 8328157229d35a135ede65c97fda196f647217d4 Mon Sep 17 00:00:00 2001
From: Fadhlan Ridhwanallah <fridhwanallah@gmail.com>
Date: Tue, 30 Jun 2026 10:31:30 +0700
Subject: [PATCH 12/12] Fix in-place-edit test reading debounced mirror instead
 of editor doc

The sanity assertion compared `harness.content` (updated only on the editor's
500ms-debounced onUpdate) right after dispatching the in-place edit, so it saw
the pre-edit text. Read the live CodeMirror document instead; the real
assertion (the chooser request targets the freshly-typed URL) is unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../components/codemirror-embed-toolbar-test.gts            | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
index e11088217d..847392d266 100644
--- a/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
+++ b/packages/host/tests/integration/components/codemirror-embed-toolbar-test.gts
@@ -398,8 +398,10 @@ module('Integration | codemirror embed toolbar', function (hooks) {
     view?.dispatch({ changes: { from: oPos, to: oPos + 1, insert: 'a' } });
     await settled();
 
-    // (sanity) the edited document holds the new URL.
-    assert.strictEqual(harness.content, `:card[${manga}]`);
+    // (sanity) the editor's live document holds the new URL. Read the view
+    // directly rather than `harness.content`, which only updates on the
+    // debounced onUpdate that hasn't fired yet.
+    assert.strictEqual(view?.state.doc.toString(), `:card[${manga}]`);
 
     await click('[data-test-toolbar="edit-embed"]');
     await waitFor('[data-test-markdown-embed-chooser-modal]', {