From 1420822cbc1f1b88121354e23ff749da0f3891b1 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 09:16:36 -0400
Subject: [PATCH 01/50] Add BFM card references for MarkdownDef (CS-10570)

Support `:card[URL]` (inline) and `::card[URL]` (block) Boxel Flavored
Markdown syntax in MarkdownDef files. Inline references render as atom-format
cards, block references as embedded-format. The parsing utility is keyword-
generic to support future `:file` syntax (CS-10583).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  | 106 ++++++-
 packages/base/markdown-file-def.gts           |  37 ++-
 .../acceptance/markdown-file-def-test.gts     | 129 ++++++++-
 .../tests/unit/bfm-card-references-test.ts    | 260 ++++++++++++++++++
 .../runtime-common/bfm-card-references.ts     | 176 ++++++++++++
 packages/runtime-common/index.ts              |   1 +
 packages/runtime-common/marked-sync.ts        |   5 +
 7 files changed, 708 insertions(+), 6 deletions(-)
 create mode 100644 packages/host/tests/unit/bfm-card-references-test.ts
 create mode 100644 packages/runtime-common/bfm-card-references.ts

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 8f97aa38790..8d53511f171 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -2,12 +2,15 @@ import { task } from 'ember-concurrency';
 import GlimmerComponent from '@glimmer/component';
 import { cached, tracked } from '@glimmer/tracking';
 import { htmlSafe } from '@ember/template';
+import { modifier } from 'ember-modifier';
 
 import {
   hasCodeBlocks,
   markdownToHtml,
   preloadMarkdownLanguages,
+  resolveCardReference,
 } from '@cardstack/runtime-common';
+import { type CardDef, getComponent } from '../card-api';
 function wrapTablesHtml(html: string | null | undefined): string {
   if (!html) return '';
   // Fast path when there are no tables to wrap.
@@ -25,10 +28,29 @@ function wrapTablesHtml(html: string | null | undefined): string {
   return doc.body.innerHTML;
 }
 
+interface CardSlot {
+  element: HTMLElement;
+  card: CardDef;
+  format: 'atom' | 'embedded';
+}
+
+function resolveUrl(raw: string, baseUrl: string | null | undefined): string {
+  try {
+    return resolveCardReference(raw, baseUrl || undefined);
+  } catch {
+    return raw;
+  }
+}
+
 export default class MarkDownTemplate extends GlimmerComponent<{
-  Args: { content: string | null };
+  Args: {
+    content: string | null;
+    linkedCards?: BaseDef[] | null;
+    cardReferenceBaseUrl?: string | null;
+  };
 }> {
   @tracked monacoContextInternal: any = undefined;
+  @tracked cardSlots: CardSlot[] = [];
   get isPrerenderContext() {
     return Boolean((globalThis as any).__boxelRenderContext);
   }
@@ -73,8 +95,75 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     return htmlSafe(wrapTablesHtml(html));
   }
 
+  captureCardSlots = modifier(
+    (element: HTMLElement, _positional: unknown[]) => {
+      let linkedCards = this.args.linkedCards;
+      let baseUrl = this.args.cardReferenceBaseUrl;
+
+      if (!linkedCards?.length) {
+        if (this.cardSlots.length > 0) {
+          this.cardSlots = [];
+        }
+        return;
+      }
+
+      let cardsByUrl = new Map<string, BaseDef>();
+      for (let card of linkedCards) {
+        if (card?.id) {
+          cardsByUrl.set(card.id, card);
+        }
+      }
+
+      let slots: CardSlot[] = [];
+
+      for (let el of element.querySelectorAll<HTMLElement>(
+        '[data-boxel-bfm-inline-ref][data-boxel-bfm-type="card"]',
+      )) {
+        let rawUrl = el.dataset.boxelBfmInlineRef;
+        if (!rawUrl) continue;
+        let resolved = resolveUrl(rawUrl, baseUrl);
+        let card = cardsByUrl.get(resolved);
+        if (card) {
+          slots.push({ element: el, card, format: 'atom' });
+        } else {
+          el.textContent = rawUrl;
+        }
+      }
+
+      for (let el of element.querySelectorAll<HTMLElement>(
+        '[data-boxel-bfm-block-ref][data-boxel-bfm-type="card"]',
+      )) {
+        let rawUrl = el.dataset.boxelBfmBlockRef;
+        if (!rawUrl) continue;
+        let resolved = resolveUrl(rawUrl, baseUrl);
+        let card = cardsByUrl.get(resolved);
+        if (card) {
+          slots.push({ element: el, card, format: 'embedded' });
+        } else {
+          el.textContent = rawUrl;
+        }
+      }
+
+      this.cardSlots = slots;
+    },
+  );
+
+  getCardComponent = (card: BaseDef) => getComponent(card);
+
   <template>
-    <div class='markdown-content'>{{this.renderedHtml}}</div>
+    <div
+      class='markdown-content'
+      {{this.captureCardSlots this.renderedHtml @linkedCards}}
+    >
+      {{this.renderedHtml}}
+    </div>
+    {{#each this.cardSlots as |slot|}}
+      {{#in-element slot.element insertBefore=null}}
+        {{#let (this.getCardComponent slot.card) as |CardComponent|}}
+          <CardComponent @format={{slot.format}} />
+        {{/let}}
+      {{/in-element}}
+    {{/each}}
     <style scoped>
       @layer baseComponent {
         .markdown-content {
@@ -321,6 +410,19 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         .markdown-content :deep(tr:not(:last-child) td) {
           border-bottom: 1px solid var(--md-border);
         }
+
+        /* BFM references (card, file, etc.) */
+        .markdown-content :deep([data-boxel-bfm-inline-ref]) {
+          display: inline;
+        }
+
+        .markdown-content :deep([data-boxel-bfm-block-ref]) {
+          display: block;
+          margin: var(--boxel-sp) 0;
+          border: 1px solid var(--boxel-200);
+          border-radius: var(--boxel-border-radius);
+          overflow: hidden;
+        }
       }
     </style>
   </template>
diff --git a/packages/base/markdown-file-def.gts b/packages/base/markdown-file-def.gts
index e142814176a..7c2ace68fea 100644
--- a/packages/base/markdown-file-def.gts
+++ b/packages/base/markdown-file-def.gts
@@ -1,11 +1,17 @@
-import { byteStreamToUint8Array } from '@cardstack/runtime-common';
+import {
+  byteStreamToUint8Array,
+  extractCardReferenceUrls,
+} from '@cardstack/runtime-common';
 import MarkdownIcon from '@cardstack/boxel-icons/align-box-left-middle';
 import {
   BaseDefComponent,
+  CardDef,
   Component,
   StringField,
   contains,
+  containsMany,
   field,
+  linksToMany,
 } from './card-api';
 import MarkdownTemplate from './default-templates/markdown';
 import {
@@ -125,7 +131,11 @@ class Isolated extends Component<typeof MarkdownDef> {
   <template>
     <article class='markdown-isolated' data-test-markdown-isolated>
       {{#if this.hasContent}}
-        <MarkdownTemplate @content={{this.content}} />
+        <MarkdownTemplate
+          @content={{this.content}}
+          @linkedCards={{@model.linkedCards}}
+          @cardReferenceBaseUrl={{@model.id}}
+        />
       {{else}}
         <header class='markdown-isolated__title'>{{this.title}}</header>
       {{/if}}
@@ -183,7 +193,11 @@ class Embedded extends Component<typeof MarkdownDef> {
         <header class='markdown-embedded__title'>{{this.title}}</header>
       {{/unless}}
       <div class='markdown-embedded__content'>
-        <MarkdownTemplate @content={{this.content}} />
+        <MarkdownTemplate
+          @content={{this.content}}
+          @linkedCards={{@model.linkedCards}}
+          @cardReferenceBaseUrl={{@model.id}}
+        />
       </div>
     </article>
     <style scoped>
@@ -430,6 +444,23 @@ export class MarkdownDef extends FileDef {
   @field excerpt = contains(StringField);
   @field content = contains(StringField);
 
+  @field cardReferenceUrls = containsMany(StringField, {
+    computeVia: function (this: MarkdownDef) {
+      if (!this.content) {
+        return [];
+      }
+      return extractCardReferenceUrls(this.content, this.id ?? '');
+    },
+  });
+
+  @field linkedCards = linksToMany(CardDef, {
+    query: {
+      filter: {
+        in: { id: '$this.cardReferenceUrls' },
+      },
+    },
+  });
+
   static isolated: BaseDefComponent = Isolated;
   static embedded: BaseDefComponent = Embedded;
   static fitted: BaseDefComponent = Fitted;
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 3a15850f788..e28023699fd 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -1,4 +1,4 @@
-import { visit, waitUntil } from '@ember/test-helpers';
+import { visit, waitFor, waitUntil } from '@ember/test-helpers';
 
 import { getService } from '@universal-ember/test-support';
 
@@ -19,6 +19,8 @@ import {
   setupLocalIndexing,
   setupOnSave,
   setupRealmCacheTeardown,
+  setupAuthEndpoints,
+  setupUserSubscription,
   testRealmURL,
   setupAcceptanceTestRealm,
   SYSTEM_CARD_FIXTURE_CONTENTS,
@@ -26,6 +28,7 @@ import {
 } from '../helpers';
 import { setupMockMatrix } from '../helpers/mock-matrix';
 import { setupApplicationTest } from '../helpers/setup';
+import visitOperatorMode from '../helpers/visit-operator-mode';
 
 module('Acceptance | markdown file def', function (hooks) {
   setupApplicationTest(hooks);
@@ -212,3 +215,127 @@ Another paragraph follows.`,
     );
   });
 });
+
+module('Acceptance | markdown BFM card references', function (hooks) {
+  setupApplicationTest(hooks);
+  setupLocalIndexing(hooks);
+  setupOnSave(hooks);
+  setupRealmCacheTeardown(hooks);
+
+  let mockMatrixUtils = setupMockMatrix(hooks, {
+    loggedInAs: '@testuser:localhost',
+    activeRealms: [testRealmURL],
+  });
+
+  hooks.beforeEach(async function () {
+    let { createAndJoinRoom } = mockMatrixUtils;
+    createAndJoinRoom({
+      sender: '@testuser:localhost',
+      name: 'room-test',
+    });
+    setupUserSubscription();
+    setupAuthEndpoints();
+
+    await withCachedRealmSetup(async () =>
+      setupAcceptanceTestRealm({
+        mockMatrixUtils,
+        contents: {
+          ...SYSTEM_CARD_FIXTURE_CONTENTS,
+          '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 embedded = class Embedded extends Component {
+                <template>
+                  <div data-test-pet-embedded>
+                    <@fields.name />
+                  </div>
+                </template>
+              };
+              static atom = class Atom extends Component {
+                <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' },
+              },
+            },
+          },
+          'Pet/jackie.json': {
+            data: {
+              attributes: { name: 'Jackie', cardTitle: 'Jackie' },
+              meta: {
+                adoptsFrom: { module: '../pet', name: 'Pet' },
+              },
+            },
+          },
+          'bfm-test.md': [
+            '# BFM Test',
+            '',
+            `Inline reference: :card[${testRealmURL}Pet/mango]`,
+            '',
+            `::card[${testRealmURL}Pet/jackie]`,
+            '',
+            'End of document.',
+          ].join('\n'),
+          'bfm-fallback.md': [
+            '# Fallback Test',
+            '',
+            ':card[https://nonexistent.example/Card/missing]',
+          ].join('\n'),
+        },
+      }),
+    );
+  });
+
+  test('renders inline card reference in atom format and block card reference in embedded format', async function (assert) {
+    await visitOperatorMode({
+      stacks: [
+        [{ id: `${testRealmURL}bfm-test.md`, format: 'isolated' }],
+      ],
+    });
+
+    await waitFor('[data-test-pet-atom]', { timeout: 10000 });
+
+    assert
+      .dom('[data-test-pet-atom]')
+      .exists('inline card reference renders in atom format');
+    assert
+      .dom('[data-test-pet-atom]')
+      .hasText('Mango', 'inline atom shows correct card');
+
+    assert
+      .dom('[data-test-pet-embedded]')
+      .exists('block card reference renders in embedded format');
+    assert.dom('[data-test-pet-embedded]').hasText('Jackie');
+  });
+
+  test('shows fallback text for unresolvable card references', async function (assert) {
+    await visitOperatorMode({
+      stacks: [
+        [{ id: `${testRealmURL}bfm-fallback.md`, format: 'isolated' }],
+      ],
+    });
+
+    await waitFor('[data-test-markdown-isolated]', { timeout: 10000 });
+
+    assert
+      .dom('[data-boxel-bfm-inline-ref]')
+      .hasText(
+        'https://nonexistent.example/Card/missing',
+        'unresolvable reference shows URL as fallback text',
+      );
+  });
+});
diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
new file mode 100644
index 00000000000..75dad3c08de
--- /dev/null
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -0,0 +1,260 @@
+import { module, test } from 'qunit';
+
+import {
+  extractCardReferenceUrls,
+  extractBfmReferences,
+  bfmCardReferenceExtensions,
+  bfmExtensionsForKeyword,
+} from '@cardstack/runtime-common/bfm-card-references';
+import { markdownToHtml } from '@cardstack/runtime-common/marked-sync';
+
+module('Unit | bfm-card-references', function () {
+  module('extractCardReferenceUrls', function () {
+    test('extracts inline card references', function (assert) {
+      let markdown = 'See :card[https://example.com/cards/1] for details.';
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, ['https://example.com/cards/1']);
+    });
+
+    test('extracts block card references', function (assert) {
+      let markdown = '::card[https://example.com/cards/1]\n';
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, ['https://example.com/cards/1']);
+    });
+
+    test('extracts both inline and block references', function (assert) {
+      let markdown = [
+        '::card[https://example.com/cards/1]',
+        '',
+        'Text with :card[https://example.com/cards/2] inline.',
+      ].join('\n');
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, [
+        'https://example.com/cards/1',
+        'https://example.com/cards/2',
+      ]);
+    });
+
+    test('resolves relative URLs against base', function (assert) {
+      let markdown = ':card[./my-card]';
+      let urls = extractCardReferenceUrls(
+        markdown,
+        'https://realm.example/docs/file.md',
+      );
+      assert.deepEqual(urls, ['https://realm.example/docs/my-card']);
+    });
+
+    test('deduplicates URLs', function (assert) {
+      let markdown = [
+        ':card[https://example.com/cards/1]',
+        ':card[https://example.com/cards/1]',
+      ].join('\n');
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, ['https://example.com/cards/1']);
+    });
+
+    test('ignores references inside fenced code blocks', function (assert) {
+      let markdown = [
+        '```',
+        ':card[https://example.com/cards/1]',
+        '```',
+      ].join('\n');
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, []);
+    });
+
+    test('ignores references inside inline code', function (assert) {
+      let markdown = 'Use `:card[url]` syntax.';
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, []);
+    });
+
+    test('skips malformed URLs with empty base', function (assert) {
+      let markdown = ':card[not a valid url at all]';
+      let urls = extractCardReferenceUrls(markdown, '');
+      assert.deepEqual(urls, []);
+    });
+
+    test('returns empty array for markdown without references', function (assert) {
+      let markdown = '# Hello World\n\nNo card references here.';
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, []);
+    });
+
+    test('returns empty array for empty markdown', function (assert) {
+      let urls = extractCardReferenceUrls('', 'https://base.com/');
+      assert.deepEqual(urls, []);
+    });
+  });
+
+  module('extractBfmReferences', function () {
+    test('extracts references for multiple keywords', function (assert) {
+      let markdown = [
+        ':card[https://example.com/cards/1]',
+        ':file[https://example.com/files/1]',
+      ].join('\n');
+      let refs = extractBfmReferences(markdown, 'https://base.com/', [
+        'card',
+        'file',
+      ]);
+      assert.deepEqual(refs, [
+        { url: 'https://example.com/cards/1', keyword: 'card' },
+        { url: 'https://example.com/files/1', keyword: 'file' },
+      ]);
+    });
+
+    test('deduplicates across keywords by URL', function (assert) {
+      let markdown = [
+        ':card[https://example.com/thing]',
+        ':file[https://example.com/thing]',
+      ].join('\n');
+      let refs = extractBfmReferences(markdown, 'https://base.com/', [
+        'card',
+        'file',
+      ]);
+      assert.strictEqual(refs.length, 1);
+      assert.strictEqual(refs[0].url, 'https://example.com/thing');
+    });
+  });
+
+  module('bfmCardReferenceExtensions', function () {
+    test('returns two extensions for card keyword', function (assert) {
+      let extensions = bfmCardReferenceExtensions();
+      assert.strictEqual(extensions.length, 2);
+      assert.strictEqual((extensions[0] as any).name, 'bfmCardBlock');
+      assert.strictEqual((extensions[1] as any).name, 'bfmCardInline');
+    });
+  });
+
+  module('bfmExtensionsForKeyword', function () {
+    test('generates extensions with keyword-specific names', function (assert) {
+      let extensions = bfmExtensionsForKeyword('file');
+      assert.strictEqual(extensions.length, 2);
+      assert.strictEqual((extensions[0] as any).name, 'bfmFileBlock');
+      assert.strictEqual((extensions[1] as any).name, 'bfmFileInline');
+    });
+  });
+
+  module('markdownToHtml with BFM syntax', function () {
+    test('inline card ref produces span placeholder with bfm attributes', function (assert) {
+      let markdown = 'See :card[https://example.com/cards/1] here.';
+      let html = markdownToHtml(markdown);
+      assert.true(
+        html.includes(
+          'data-boxel-bfm-inline-ref="https://example.com/cards/1"',
+        ),
+        'inline placeholder has ref data attribute',
+      );
+      assert.true(
+        html.includes('data-boxel-bfm-type="card"'),
+        'inline placeholder has type data attribute',
+      );
+      assert.true(
+        html.includes('<span data-boxel-bfm-inline-ref='),
+        'inline placeholder is a span element',
+      );
+    });
+
+    test('block card ref produces div placeholder with bfm attributes', function (assert) {
+      let markdown = '::card[https://example.com/cards/1]\n';
+      let html = markdownToHtml(markdown);
+      assert.true(
+        html.includes(
+          'data-boxel-bfm-block-ref="https://example.com/cards/1"',
+        ),
+        'block placeholder has ref data attribute',
+      );
+      assert.true(
+        html.includes('data-boxel-bfm-type="card"'),
+        'block placeholder has type data attribute',
+      );
+      assert.true(
+        html.includes('<div data-boxel-bfm-block-ref='),
+        'block placeholder is a div element',
+      );
+    });
+
+    test('card refs inside code blocks are not processed', function (assert) {
+      let markdown = [
+        '```',
+        ':card[https://example.com/cards/1]',
+        '```',
+      ].join('\n');
+      let html = markdownToHtml(markdown);
+      assert.false(
+        html.includes('data-boxel-bfm-inline-ref'),
+        'no card ref placeholder inside code block',
+      );
+    });
+
+    test('inline card ref inside inline code is not processed', function (assert) {
+      let markdown = 'Use `:card[url]` syntax.';
+      let html = markdownToHtml(markdown);
+      assert.false(
+        html.includes('data-boxel-bfm-inline-ref'),
+        'no card ref placeholder inside inline code',
+      );
+    });
+
+    test('DOMPurify preserves BFM placeholders', function (assert) {
+      let markdown =
+        'Text :card[https://example.com/cards/1] and more.\n\n::card[https://example.com/cards/2]\n';
+      let html = markdownToHtml(markdown, { sanitize: true });
+      assert.true(
+        html.includes(
+          'data-boxel-bfm-inline-ref="https://example.com/cards/1"',
+        ),
+        'inline ref survives sanitization',
+      );
+      assert.true(
+        html.includes(
+          'data-boxel-bfm-block-ref="https://example.com/cards/2"',
+        ),
+        'block ref survives sanitization',
+      );
+    });
+
+    test('markdown without card refs is unaffected', function (assert) {
+      let markdown = '# Hello\n\nSome **bold** text.';
+      let withBfm = markdownToHtml(markdown);
+      assert.true(withBfm.includes('<h1>Hello</h1>'));
+      assert.true(withBfm.includes('<strong>bold</strong>'));
+      assert.false(withBfm.includes('data-boxel-bfm'));
+    });
+
+    test('HTML special chars in URLs are escaped in placeholders', function (assert) {
+      let markdown = ':card[https://example.com/cards/1&foo=<bar>]';
+      let html = markdownToHtml(markdown, { sanitize: false });
+      assert.true(
+        html.includes('&amp;foo=&lt;bar&gt;'),
+        'URL special chars are escaped',
+      );
+    });
+
+    test('mixed inline and block refs in a document', function (assert) {
+      let markdown = [
+        '# Title',
+        '',
+        'Intro text with :card[https://example.com/cards/inline] reference.',
+        '',
+        '::card[https://example.com/cards/block]',
+        '',
+        'More text.',
+      ].join('\n');
+      let html = markdownToHtml(markdown);
+      assert.true(
+        html.includes(
+          'data-boxel-bfm-inline-ref="https://example.com/cards/inline"',
+        ),
+        'has inline ref',
+      );
+      assert.true(
+        html.includes(
+          'data-boxel-bfm-block-ref="https://example.com/cards/block"',
+        ),
+        'has block ref',
+      );
+      assert.true(html.includes('<h1>Title</h1>'), 'heading preserved');
+    });
+  });
+});
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
new file mode 100644
index 00000000000..97a665a97ad
--- /dev/null
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -0,0 +1,176 @@
+import { escapeHtml } from './helpers/html';
+import { resolveCardReference } from './card-reference-resolver';
+import type { TokenizerAndRendererExtension } from 'marked';
+
+// Regex patterns for stripping code before extraction.
+// These avoid backtick-in-regex issues that break content-tag in .gts files.
+const FENCED_CODE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`([^`]+)`/g;
+
+function resolveUrl(
+  ref: string,
+  baseUrl: string | undefined,
+): string | null {
+  try {
+    return resolveCardReference(ref, baseUrl || undefined);
+  } catch {
+    return null;
+  }
+}
+
+export interface BfmReference {
+  url: string;
+  keyword: string;
+}
+
+/**
+ * Extracts and deduplicates BFM reference URLs from markdown content for the
+ * given keywords (e.g. 'card', 'file'). Supports `:keyword[URL]` (inline) and
+ * `::keyword[URL]` (block) syntax. References inside fenced code blocks and
+ * inline code are ignored. Returns resolved absolute URLs in document order.
+ */
+export function extractBfmReferences(
+  markdown: string,
+  baseUrl: string,
+  keywords: string[],
+): BfmReference[] {
+  // Strip code blocks so references inside them are not extracted
+  let stripped = markdown
+    .replace(FENCED_CODE_RE, '')
+    .replace(INLINE_CODE_RE, '');
+
+  let seen = new Set<string>();
+  let refs: BfmReference[] = [];
+
+  for (let keyword of keywords) {
+    let blockRe = new RegExp(`^::${keyword}\\[([^\\]]+)\\]`, 'gm');
+    // Negative lookbehind excludes ::keyword[ (block syntax) from inline matches
+    let inlineRe = new RegExp(`(?<!:):${keyword}\\[([^\\]]+)\\]`, 'g');
+
+    for (let match of stripped.matchAll(blockRe)) {
+      let resolved = resolveUrl(match[1], baseUrl);
+      if (resolved && !seen.has(resolved)) {
+        seen.add(resolved);
+        refs.push({ url: resolved, keyword });
+      }
+    }
+    for (let match of stripped.matchAll(inlineRe)) {
+      let resolved = resolveUrl(match[1], baseUrl);
+      if (resolved && !seen.has(resolved)) {
+        seen.add(resolved);
+        refs.push({ url: resolved, keyword });
+      }
+    }
+  }
+
+  return refs;
+}
+
+/**
+ * Convenience wrapper that extracts only `:card[URL]` / `::card[URL]`
+ * references and returns just the resolved URL strings.
+ */
+export function extractCardReferenceUrls(
+  markdown: string,
+  baseUrl: string,
+): string[] {
+  return extractBfmReferences(markdown, baseUrl, ['card']).map((r) => r.url);
+}
+
+/**
+ * Creates marked v12 extensions for a given BFM keyword.
+ *
+ * Block: `::keyword[URL]` → `<div data-boxel-bfm-block-ref="URL" data-boxel-bfm-type="keyword"></div>`
+ * Inline: `:keyword[URL]` → `<span data-boxel-bfm-inline-ref="URL" data-boxel-bfm-type="keyword"></span>`
+ *
+ * URLs are emitted as-is (unresolved). The consumer is responsible for
+ * resolving them against a base URL before matching to instance IDs.
+ */
+export function bfmExtensionsForKeyword(
+  keyword: string,
+): TokenizerAndRendererExtension[] {
+  let blockType = `bfm${capitalize(keyword)}Block`;
+  let inlineType = `bfm${capitalize(keyword)}Inline`;
+  let colonKeyword = `:${keyword}[`;
+  let doubleColonKeyword = `::${keyword}[`;
+
+  return [
+    {
+      name: blockType,
+      level: 'block',
+      start(src: string) {
+        let re = new RegExp(`^${escapeRegExp(doubleColonKeyword)}`, 'm');
+        let match = src.match(re);
+        return match?.index;
+      },
+      tokenizer(src: string) {
+        let re = new RegExp(
+          `^::${escapeRegExp(keyword)}\\[([^\\]]+)\\]\\s*(?:\\n|$)`,
+        );
+        let match = src.match(re);
+        if (match) {
+          return {
+            type: blockType,
+            raw: match[0],
+            url: match[1],
+          };
+        }
+        return undefined;
+      },
+      renderer(token) {
+        let url = escapeHtml((token as any).url);
+        return `<div data-boxel-bfm-block-ref="${url}" data-boxel-bfm-type="${keyword}"></div>\n`;
+      },
+    },
+    {
+      name: inlineType,
+      level: 'inline',
+      start(src: string) {
+        let idx = 0;
+        while (idx < src.length) {
+          let pos = src.indexOf(colonKeyword, idx);
+          if (pos === -1) return undefined;
+          // Skip if preceded by ':' (block syntax ::keyword[)
+          if (pos > 0 && src[pos - 1] === ':') {
+            idx = pos + 1;
+            continue;
+          }
+          return pos;
+        }
+        return undefined;
+      },
+      tokenizer(src: string) {
+        let re = new RegExp(`^:${escapeRegExp(keyword)}\\[([^\\]]+)\\]`);
+        let match = src.match(re);
+        if (match) {
+          return {
+            type: inlineType,
+            raw: match[0],
+            url: match[1],
+          };
+        }
+        return undefined;
+      },
+      renderer(token) {
+        let url = escapeHtml((token as any).url);
+        return `<span data-boxel-bfm-inline-ref="${url}" data-boxel-bfm-type="${keyword}"></span>`;
+      },
+    },
+  ];
+}
+
+/**
+ * Returns marked extensions for the default set of BFM keywords.
+ * Currently registers 'card'. Add new keywords here as they are introduced.
+ */
+export function bfmCardReferenceExtensions(): TokenizerAndRendererExtension[] {
+  return bfmExtensionsForKeyword('card');
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
diff --git a/packages/runtime-common/index.ts b/packages/runtime-common/index.ts
index b816b45f85a..8a8a30c5c5a 100644
--- a/packages/runtime-common/index.ts
+++ b/packages/runtime-common/index.ts
@@ -242,6 +242,7 @@ export * from './definitions';
 export * from './catalog';
 export * from './commands';
 export * from './card-reference-resolver';
+export * from './bfm-card-references';
 export * from './constants';
 export * from './helpers/const';
 export * from './document';
diff --git a/packages/runtime-common/marked-sync.ts b/packages/runtime-common/marked-sync.ts
index 3364ecc0d4c..e94fc1bd9b9 100644
--- a/packages/runtime-common/marked-sync.ts
+++ b/packages/runtime-common/marked-sync.ts
@@ -1,9 +1,14 @@
 import { marked } from 'marked';
 import { sanitizeHtml } from './dompurify-runtime';
 import { escapeHtml } from './helpers/html';
+import { bfmCardReferenceExtensions } from './bfm-card-references';
 import type * as _MonacoSDK from 'monaco-editor';
 type MonacoSDK = typeof _MonacoSDK;
 
+// Register BFM card reference extensions globally. This is additive and does
+// not conflict with the per-call renderer override in markedSync().
+marked.use({ extensions: bfmCardReferenceExtensions() });
+
 const DECORATIVE_BULLET_PATTERN =
   // eslint-disable-next-line no-misleading-character-class -- match pictographic symbols plus a few geometric glyphs not covered by the Unicode class
   /(^|\n)(\s*)([\p{Extended_Pictographic}★•▪●❖✦✧◉◦◾◽⬢⬡☑✔☑️➤➔➜➡→])(\s+)/gu;

From dd555c16dadfdb8db33ad47a2a2a414ed9856466 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 10:01:51 -0400
Subject: [PATCH 02/50] Fix lint errors and acceptance test approach

- Import BaseDef instead of missing CardDef in markdown.gts
- Wrap querySelectorAll with Array.from() for NodeListOf iteration
- Use code submode (not card stack) to render file defs in tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts       | 14 +++++++++-----
 .../tests/acceptance/markdown-file-def-test.gts    | 10 ++++------
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 8d53511f171..b7d750923a2 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -10,7 +10,7 @@ import {
   preloadMarkdownLanguages,
   resolveCardReference,
 } from '@cardstack/runtime-common';
-import { type CardDef, getComponent } from '../card-api';
+import { type BaseDef, getComponent } from '../card-api';
 function wrapTablesHtml(html: string | null | undefined): string {
   if (!html) return '';
   // Fast path when there are no tables to wrap.
@@ -116,8 +116,10 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 
       let slots: CardSlot[] = [];
 
-      for (let el of element.querySelectorAll<HTMLElement>(
-        '[data-boxel-bfm-inline-ref][data-boxel-bfm-type="card"]',
+      for (let el of Array.from(
+        element.querySelectorAll<HTMLElement>(
+          '[data-boxel-bfm-inline-ref][data-boxel-bfm-type="card"]',
+        ),
       )) {
         let rawUrl = el.dataset.boxelBfmInlineRef;
         if (!rawUrl) continue;
@@ -130,8 +132,10 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         }
       }
 
-      for (let el of element.querySelectorAll<HTMLElement>(
-        '[data-boxel-bfm-block-ref][data-boxel-bfm-type="card"]',
+      for (let el of Array.from(
+        element.querySelectorAll<HTMLElement>(
+          '[data-boxel-bfm-block-ref][data-boxel-bfm-type="card"]',
+        ),
       )) {
         let rawUrl = el.dataset.boxelBfmBlockRef;
         if (!rawUrl) continue;
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index e28023699fd..a22df04072b 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -302,9 +302,8 @@ module('Acceptance | markdown BFM card references', function (hooks) {
 
   test('renders inline card reference in atom format and block card reference in embedded format', async function (assert) {
     await visitOperatorMode({
-      stacks: [
-        [{ id: `${testRealmURL}bfm-test.md`, format: 'isolated' }],
-      ],
+      submode: 'code',
+      codePath: `${testRealmURL}bfm-test.md`,
     });
 
     await waitFor('[data-test-pet-atom]', { timeout: 10000 });
@@ -324,9 +323,8 @@ module('Acceptance | markdown BFM card references', function (hooks) {
 
   test('shows fallback text for unresolvable card references', async function (assert) {
     await visitOperatorMode({
-      stacks: [
-        [{ id: `${testRealmURL}bfm-fallback.md`, format: 'isolated' }],
-      ],
+      submode: 'code',
+      codePath: `${testRealmURL}bfm-fallback.md`,
     });
 
     await waitFor('[data-test-markdown-isolated]', { timeout: 10000 });

From 1e31fcebe5efb67ac56155b101baeffd61b33287 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 10:35:22 -0400
Subject: [PATCH 03/50] Fix lint: import CardDef, fix modifier early-return for
 fallback

- Import both BaseDef and CardDef from card-api (CardDef has .id)
- Remove early-return in captureCardSlots when linkedCards is empty,
  so fallback text is still set on unresolvable BFM placeholders

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts | 21 ++++++++------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index b7d750923a2..371fccc10ca 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -10,7 +10,7 @@ import {
   preloadMarkdownLanguages,
   resolveCardReference,
 } from '@cardstack/runtime-common';
-import { type BaseDef, getComponent } from '../card-api';
+import { type BaseDef, type CardDef, getComponent } from '../card-api';
 function wrapTablesHtml(html: string | null | undefined): string {
   if (!html) return '';
   // Fast path when there are no tables to wrap.
@@ -45,7 +45,7 @@ function resolveUrl(raw: string, baseUrl: string | null | undefined): string {
 export default class MarkDownTemplate extends GlimmerComponent<{
   Args: {
     content: string | null;
-    linkedCards?: BaseDef[] | null;
+    linkedCards?: CardDef[] | null;
     cardReferenceBaseUrl?: string | null;
   };
 }> {
@@ -100,17 +100,12 @@ export default class MarkDownTemplate extends GlimmerComponent<{
       let linkedCards = this.args.linkedCards;
       let baseUrl = this.args.cardReferenceBaseUrl;
 
-      if (!linkedCards?.length) {
-        if (this.cardSlots.length > 0) {
-          this.cardSlots = [];
-        }
-        return;
-      }
-
-      let cardsByUrl = new Map<string, BaseDef>();
-      for (let card of linkedCards) {
-        if (card?.id) {
-          cardsByUrl.set(card.id, card);
+      let cardsByUrl = new Map<string, CardDef>();
+      if (linkedCards?.length) {
+        for (let card of linkedCards) {
+          if (card?.id) {
+            cardsByUrl.set(card.id, card);
+          }
         }
       }
 

From 817e7232b640aaa122426aa3e36a073f659250d5 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 11:14:32 -0400
Subject: [PATCH 04/50] Fix BFM fallback text: bake URL into HTML instead of
 modifier DOM writes

The modifier was setting el.textContent for unresolved BFM references,
but Glimmer re-renders would wipe the text. Now the marked extensions
include the URL as text content in the placeholder elements, so fallback
text is part of the initial HTML and survives re-renders.

Also fixes prettier formatting in bfm-card-references.ts and unit tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  |  4 ----
 .../tests/unit/bfm-card-references-test.ts    | 24 +++++++------------
 .../runtime-common/bfm-card-references.ts     |  9 +++----
 3 files changed, 11 insertions(+), 26 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 371fccc10ca..83b037ffd4f 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -122,8 +122,6 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         let card = cardsByUrl.get(resolved);
         if (card) {
           slots.push({ element: el, card, format: 'atom' });
-        } else {
-          el.textContent = rawUrl;
         }
       }
 
@@ -138,8 +136,6 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         let card = cardsByUrl.get(resolved);
         if (card) {
           slots.push({ element: el, card, format: 'embedded' });
-        } else {
-          el.textContent = rawUrl;
         }
       }
 
diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 75dad3c08de..3ca10a62f5e 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -54,11 +54,9 @@ module('Unit | bfm-card-references', function () {
     });
 
     test('ignores references inside fenced code blocks', function (assert) {
-      let markdown = [
-        '```',
-        ':card[https://example.com/cards/1]',
-        '```',
-      ].join('\n');
+      let markdown = ['```', ':card[https://example.com/cards/1]', '```'].join(
+        '\n',
+      );
       let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
       assert.deepEqual(urls, []);
     });
@@ -159,9 +157,7 @@ module('Unit | bfm-card-references', function () {
       let markdown = '::card[https://example.com/cards/1]\n';
       let html = markdownToHtml(markdown);
       assert.true(
-        html.includes(
-          'data-boxel-bfm-block-ref="https://example.com/cards/1"',
-        ),
+        html.includes('data-boxel-bfm-block-ref="https://example.com/cards/1"'),
         'block placeholder has ref data attribute',
       );
       assert.true(
@@ -175,11 +171,9 @@ module('Unit | bfm-card-references', function () {
     });
 
     test('card refs inside code blocks are not processed', function (assert) {
-      let markdown = [
-        '```',
-        ':card[https://example.com/cards/1]',
-        '```',
-      ].join('\n');
+      let markdown = ['```', ':card[https://example.com/cards/1]', '```'].join(
+        '\n',
+      );
       let html = markdownToHtml(markdown);
       assert.false(
         html.includes('data-boxel-bfm-inline-ref'),
@@ -207,9 +201,7 @@ module('Unit | bfm-card-references', function () {
         'inline ref survives sanitization',
       );
       assert.true(
-        html.includes(
-          'data-boxel-bfm-block-ref="https://example.com/cards/2"',
-        ),
+        html.includes('data-boxel-bfm-block-ref="https://example.com/cards/2"'),
         'block ref survives sanitization',
       );
     });
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
index 97a665a97ad..b029117452b 100644
--- a/packages/runtime-common/bfm-card-references.ts
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -7,10 +7,7 @@ import type { TokenizerAndRendererExtension } from 'marked';
 const FENCED_CODE_RE = /```[\s\S]*?```/g;
 const INLINE_CODE_RE = /`([^`]+)`/g;
 
-function resolveUrl(
-  ref: string,
-  baseUrl: string | undefined,
-): string | null {
+function resolveUrl(ref: string, baseUrl: string | undefined): string | null {
   try {
     return resolveCardReference(ref, baseUrl || undefined);
   } catch {
@@ -119,7 +116,7 @@ export function bfmExtensionsForKeyword(
       },
       renderer(token) {
         let url = escapeHtml((token as any).url);
-        return `<div data-boxel-bfm-block-ref="${url}" data-boxel-bfm-type="${keyword}"></div>\n`;
+        return `<div data-boxel-bfm-block-ref="${url}" data-boxel-bfm-type="${keyword}">${url}</div>\n`;
       },
     },
     {
@@ -153,7 +150,7 @@ export function bfmExtensionsForKeyword(
       },
       renderer(token) {
         let url = escapeHtml((token as any).url);
-        return `<span data-boxel-bfm-inline-ref="${url}" data-boxel-bfm-type="${keyword}"></span>`;
+        return `<span data-boxel-bfm-inline-ref="${url}" data-boxel-bfm-type="${keyword}">${url}</span>`;
       },
     },
   ];

From e119521eed51d6c33aa3cc6daaa37c59651e85b3 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 12:42:46 -0400
Subject: [PATCH 05/50] Fix markdown file query field realm context

---
 packages/base/card-api.gts | 2 +-
 packages/base/file-api.gts | 7 +++++++
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
index 2fab222c7ab..00372ac4117 100644
--- a/packages/base/card-api.gts
+++ b/packages/base/card-api.gts
@@ -3548,7 +3548,7 @@ async function _updateFromSerialized<T extends BaseDefConstructor>({
     }
 
     // assign the realm meta before we compute as computeds may be relying on this
-    if (isCardInstance(instance) && resource.id != null) {
+    if (!isFieldInstance(instance) && resource.id != null) {
       (instance as any)[meta] = resource.meta;
     }
     if (realmURLString && isFieldInstance(instance)) {
diff --git a/packages/base/file-api.gts b/packages/base/file-api.gts
index e7ceaef1e66..aab737ad92a 100644
--- a/packages/base/file-api.gts
+++ b/packages/base/file-api.gts
@@ -17,7 +17,9 @@ import {
   StringField,
   contains,
   field,
+  getCardMeta,
   getDataBucket,
+  realmURL,
 } from './card-api';
 import NumberField from './number';
 import ArrowLeft from '@cardstack/boxel-icons/arrow-left';
@@ -79,6 +81,11 @@ export class FileDef extends BaseDef {
   static icon = FileIcon;
   [isSavedInstance] = true;
 
+  get [realmURL](): URL | undefined {
+    let realmURLString = getCardMeta(this, 'realmURL');
+    return realmURLString ? new URL(realmURLString) : undefined;
+  }
+
   static assignInitialFieldValue(
     instance: BaseDef,
     fieldName: string,

From 0019f44574b5c55e23a7a882ecc2fd95a82e57f8 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 13:10:35 -0400
Subject: [PATCH 06/50] Hide resolved markdown card reference paths

---
 packages/base/default-templates/markdown.gts         |  2 ++
 .../host/tests/acceptance/markdown-file-def-test.gts | 12 ++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 83b037ffd4f..2ec84e9af2f 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -121,6 +121,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         let resolved = resolveUrl(rawUrl, baseUrl);
         let card = cardsByUrl.get(resolved);
         if (card) {
+          el.textContent = '';
           slots.push({ element: el, card, format: 'atom' });
         }
       }
@@ -135,6 +136,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         let resolved = resolveUrl(rawUrl, baseUrl);
         let card = cardsByUrl.get(resolved);
         if (card) {
+          el.textContent = '';
           slots.push({ element: el, card, format: 'embedded' });
         }
       }
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index a22df04072b..e2c35f24829 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -314,11 +314,23 @@ module('Acceptance | markdown BFM card references', function (hooks) {
     assert
       .dom('[data-test-pet-atom]')
       .hasText('Mango', 'inline atom shows correct card');
+    assert
+      .dom('[data-boxel-bfm-inline-ref]')
+      .doesNotIncludeText(
+        `${testRealmURL}Pet/mango`,
+        'inline fallback path is hidden after the card resolves',
+      );
 
     assert
       .dom('[data-test-pet-embedded]')
       .exists('block card reference renders in embedded format');
     assert.dom('[data-test-pet-embedded]').hasText('Jackie');
+    assert
+      .dom('[data-boxel-bfm-block-ref]')
+      .doesNotIncludeText(
+        `${testRealmURL}Pet/jackie`,
+        'block fallback path is hidden after the card resolves',
+      );
   });
 
   test('shows fallback text for unresolvable card references', async function (assert) {

From f45da047924228a0c4aeb2d100e0dc35bf52f4ae Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 13:37:06 -0400
Subject: [PATCH 07/50] Add navigation overlays to markdown card references

---
 packages/base/default-templates/markdown.gts  |  69 +++++++++--
 .../code-submode/module-inspector.gts         |   1 +
 .../app/components/operator-mode/overlays.gts |   4 +-
 .../operator-mode/preview-panel/index.gts     |   6 +-
 .../acceptance/markdown-file-def-test.gts     | 112 +++++++++++++++++-
 5 files changed, 181 insertions(+), 11 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 2ec84e9af2f..e90b13e14bd 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -4,6 +4,8 @@ import { cached, tracked } from '@glimmer/tracking';
 import { htmlSafe } from '@ember/template';
 import { modifier } from 'ember-modifier';
 
+import { eq } from '@cardstack/boxel-ui/helpers';
+
 import {
   hasCodeBlocks,
   markdownToHtml,
@@ -11,6 +13,7 @@ import {
   resolveCardReference,
 } from '@cardstack/runtime-common';
 import { type BaseDef, type CardDef, getComponent } from '../card-api';
+import { CardContextConsumer } from '../field-component';
 function wrapTablesHtml(html: string | null | undefined): string {
   if (!html) return '';
   // Fast path when there are no tables to wrap.
@@ -32,6 +35,7 @@ interface CardSlot {
   element: HTMLElement;
   card: CardDef;
   format: 'atom' | 'embedded';
+  kind: 'inline' | 'block';
 }
 
 function resolveUrl(raw: string, baseUrl: string | null | undefined): string {
@@ -122,7 +126,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         let card = cardsByUrl.get(resolved);
         if (card) {
           el.textContent = '';
-          slots.push({ element: el, card, format: 'atom' });
+          slots.push({ element: el, card, format: 'atom', kind: 'inline' });
         }
       }
 
@@ -137,7 +141,12 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         let card = cardsByUrl.get(resolved);
         if (card) {
           el.textContent = '';
-          slots.push({ element: el, card, format: 'embedded' });
+          slots.push({
+            element: el,
+            card,
+            format: 'embedded',
+            kind: 'block',
+          });
         }
       }
 
@@ -156,9 +165,43 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     </div>
     {{#each this.cardSlots as |slot|}}
       {{#in-element slot.element insertBefore=null}}
-        {{#let (this.getCardComponent slot.card) as |CardComponent|}}
-          <CardComponent @format={{slot.format}} />
-        {{/let}}
+        <CardContextConsumer as |context|>
+          {{#let (this.getCardComponent slot.card) as |CardComponent|}}
+            {{#if (eq slot.kind 'inline')}}
+              <span
+                class='markdown-bfm-card-slot markdown-bfm-card-slot--inline'
+                data-test-markdown-bfm-inline-card
+                {{context.cardComponentModifier
+                  card=slot.card
+                  format='data'
+                  fieldType=undefined
+                  fieldName=undefined
+                }}
+              >
+                <CardComponent
+                  @format={{slot.format}}
+                  @displayContainer={{false}}
+                />
+              </span>
+            {{else}}
+              <div
+                class='markdown-bfm-card-slot markdown-bfm-card-slot--block'
+                data-test-markdown-bfm-block-card
+                {{context.cardComponentModifier
+                  card=slot.card
+                  format='data'
+                  fieldType=undefined
+                  fieldName=undefined
+                }}
+              >
+                <CardComponent
+                  @format={{slot.format}}
+                  @displayContainer={{false}}
+                />
+              </div>
+            {{/if}}
+          {{/let}}
+        </CardContextConsumer>
       {{/in-element}}
     {{/each}}
     <style scoped>
@@ -416,9 +459,19 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         .markdown-content :deep([data-boxel-bfm-block-ref]) {
           display: block;
           margin: var(--boxel-sp) 0;
-          border: 1px solid var(--boxel-200);
-          border-radius: var(--boxel-border-radius);
-          overflow: hidden;
+        }
+
+        .markdown-bfm-card-slot {
+          max-width: 100%;
+        }
+
+        .markdown-bfm-card-slot--inline {
+          display: inline-flex;
+          vertical-align: middle;
+        }
+
+        .markdown-bfm-card-slot--block {
+          display: block;
         }
       }
     </style>
diff --git a/packages/host/app/components/operator-mode/code-submode/module-inspector.gts b/packages/host/app/components/operator-mode/code-submode/module-inspector.gts
index 83402fd4c41..21e562f38eb 100644
--- a/packages/host/app/components/operator-mode/code-submode/module-inspector.gts
+++ b/packages/host/app/components/operator-mode/code-submode/module-inspector.gts
@@ -575,6 +575,7 @@ export default class ModuleInspector extends Component<ModuleInspectorSignature>
         @card={{this.fileDefInstance}}
         @format={{@previewFormat}}
         @setFormat={{@setPreviewFormat}}
+        @viewCard={{this.viewCardInCodeSubmode}}
       />
     {{else if this.isFileDefLoading}}
       <div class='file-loading' data-test-file-preview-loading>
diff --git a/packages/host/app/components/operator-mode/overlays.gts b/packages/host/app/components/operator-mode/overlays.gts
index 593c1c7e333..ea193339691 100644
--- a/packages/host/app/components/operator-mode/overlays.gts
+++ b/packages/host/app/components/operator-mode/overlays.gts
@@ -312,7 +312,9 @@ export default class Overlays extends Component<OverlaySignature> {
   protected getFormatForCard(
     renderedCard: RenderedCardForOverlayActions,
   ): Format {
-    // Default implementation - prefer stackItem.format if available, otherwise use direct format
+    if (renderedCard.format === 'data') {
+      return 'isolated';
+    }
     return (renderedCard.format || 'isolated') as Format;
   }
 
diff --git a/packages/host/app/components/operator-mode/preview-panel/index.gts b/packages/host/app/components/operator-mode/preview-panel/index.gts
index ade126b6bdb..b6db2446a30 100644
--- a/packages/host/app/components/operator-mode/preview-panel/index.gts
+++ b/packages/host/app/components/operator-mode/preview-panel/index.gts
@@ -186,7 +186,11 @@ export default class PreviewPanel extends Component<Signature> {
       return undefined;
     }
     let entries = this.cardTracker.filter(
-      [{ fieldType: 'linksTo' }, { fieldType: 'linksToMany' }],
+      [
+        { format: 'data' },
+        { fieldType: 'linksTo' },
+        { fieldType: 'linksToMany' },
+      ],
       'or',
       // the only linksTo field with isolated format is in the index card,
       // we don't want to show overlays for those cards here
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index e2c35f24829..588d8905df8 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -1,4 +1,10 @@
-import { visit, waitFor, waitUntil } from '@ember/test-helpers';
+import {
+  click,
+  triggerEvent,
+  visit,
+  waitFor,
+  waitUntil,
+} from '@ember/test-helpers';
 
 import { getService } from '@universal-ember/test-support';
 
@@ -325,6 +331,25 @@ module('Acceptance | markdown BFM card references', function (hooks) {
       .dom('[data-test-pet-embedded]')
       .exists('block card reference renders in embedded format');
     assert.dom('[data-test-pet-embedded]').hasText('Jackie');
+    assert
+      .dom(
+        '[data-boxel-bfm-inline-ref] [data-test-field-component-card].display-container-false',
+      )
+      .exists(
+        'inline card reference renders without the shared card container',
+      );
+    assert
+      .dom(
+        '[data-boxel-bfm-block-ref] [data-test-field-component-card].display-container-false',
+      )
+      .exists('block card reference renders without the shared card container');
+    assert.strictEqual(
+      getComputedStyle(
+        document.querySelector('[data-boxel-bfm-block-ref]') as HTMLElement,
+      ).borderTopWidth,
+      '0px',
+      'block card wrapper does not add its own border',
+    );
     assert
       .dom('[data-boxel-bfm-block-ref]')
       .doesNotIncludeText(
@@ -348,4 +373,89 @@ module('Acceptance | markdown BFM card references', function (hooks) {
         'unresolvable reference shows URL as fallback text',
       );
   });
+
+  test('code mode shows overlays for markdown card references and clicking navigates', async function (assert) {
+    await visitOperatorMode({
+      submode: 'code',
+      codePath: `${testRealmURL}bfm-test.md`,
+    });
+
+    await waitFor('[data-test-markdown-bfm-inline-card]', { timeout: 10000 });
+    await waitFor('[data-test-markdown-bfm-block-card]', { timeout: 10000 });
+    await waitFor('[data-test-card-url-bar-input]');
+
+    let urlInput = document.querySelector(
+      '[data-test-card-url-bar-input]',
+    ) as HTMLInputElement | null;
+    let startingValue = urlInput?.value ?? '';
+
+    await triggerEvent('[data-test-markdown-bfm-block-card]', 'mouseenter');
+    assert
+      .dom('[data-test-card-overlay]')
+      .exists(
+        'block markdown card reference gets a hover overlay in code mode',
+      );
+
+    await triggerEvent('[data-test-markdown-bfm-inline-card]', 'mouseenter');
+    assert
+      .dom('[data-test-card-overlay]')
+      .exists(
+        'inline markdown card reference gets a hover overlay in code mode',
+      );
+
+    await click('[data-test-markdown-bfm-inline-card]');
+
+    await waitUntil(() => {
+      let currentValue =
+        (
+          document.querySelector(
+            '[data-test-card-url-bar-input]',
+          ) as HTMLInputElement | null
+        )?.value ?? '';
+      return currentValue !== startingValue;
+    });
+
+    assert
+      .dom('[data-test-card-url-bar-input]')
+      .hasValue(`${testRealmURL}Pet/mango.json`);
+  });
+
+  test('interact mode shows overlays for markdown card references and clicking navigates', async function (assert) {
+    await visitOperatorMode({
+      stacks: [
+        [
+          {
+            id: `${testRealmURL}bfm-test.md`,
+            type: 'file',
+            format: 'isolated',
+          },
+        ],
+      ],
+    });
+
+    await waitFor('[data-test-markdown-bfm-inline-card]', { timeout: 10000 });
+    await waitFor('[data-test-markdown-bfm-block-card]', { timeout: 10000 });
+
+    await triggerEvent('[data-test-markdown-bfm-inline-card]', 'mouseenter');
+    assert
+      .dom(`[data-test-overlay-card="${testRealmURL}Pet/mango"]`)
+      .exists(
+        'inline markdown card reference gets an action overlay in interact mode',
+      );
+
+    await triggerEvent('[data-test-markdown-bfm-block-card]', 'mouseenter');
+    assert
+      .dom(`[data-test-overlay-card="${testRealmURL}Pet/jackie"]`)
+      .exists(
+        'block markdown card reference gets an action overlay in interact mode',
+      );
+
+    await click('[data-test-markdown-bfm-block-card]');
+
+    assert
+      .dom(
+        `[data-test-stack-card="${testRealmURL}Pet/jackie"] [data-test-card-format="isolated"]`,
+      )
+      .exists('clicking a block markdown card reference opens the target card');
+  });
 });

From 2315c727280cf39137cd1e61ed05c3dfa02ce166 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 15:44:33 -0400
Subject: [PATCH 08/50] Prevent flash of raw URLs in markdown card references

Strip text content from card-type BFM elements in renderedHtml using
DOMParser so no URL text is ever in the DOM. The modifier uses a
_modifierHasRun flag to skip fallback injection on the first run (when
linkedCards is still loading as an empty []), and only injects fallback
text on subsequent runs for truly unresolvable refs.

Also adds MutationObserver + scheduleOnce to handle back-navigation
re-rendering, and a new acceptance test for that scenario.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  | 165 +++++++++++++-----
 packages/host/app/lib/externals.ts            |   2 +
 .../acceptance/markdown-file-def-test.gts     |  46 +++++
 3 files changed, 174 insertions(+), 39 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index e90b13e14bd..b4c125a6047 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -1,4 +1,5 @@
 import { task } from 'ember-concurrency';
+import { scheduleOnce } from '@ember/runloop';
 import GlimmerComponent from '@glimmer/component';
 import { cached, tracked } from '@glimmer/tracking';
 import { htmlSafe } from '@ember/template';
@@ -55,6 +56,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 }> {
   @tracked monacoContextInternal: any = undefined;
   @tracked cardSlots: CardSlot[] = [];
+  private _modifierHasRun = false;
   get isPrerenderContext() {
     return Boolean((globalThis as any).__boxelRenderContext);
   }
@@ -96,61 +98,146 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     // reparses that sanitized HTML so it can add wrapper divs around tables we
     // control for styling/overflow behavior. Re-sanitizing the result was
     // adding avoidable DOMParser churn during prerender and acceptance tests.
-    return htmlSafe(wrapTablesHtml(html));
+    html = wrapTablesHtml(html);
+    // Strip text content from card-type BFM refs so there is no flash of raw
+    // URLs. The URL is preserved in the data attribute; the modifier will
+    // inject fallback text for refs that can't be resolved to a card.
+    if (
+      typeof DOMParser !== 'undefined' &&
+      html.includes('data-boxel-bfm-type="card"')
+    ) {
+      let doc = new DOMParser().parseFromString(html, 'text/html');
+      doc
+        .querySelectorAll('[data-boxel-bfm-type="card"]')
+        .forEach((el) => (el.textContent = ''));
+      html = doc.body.innerHTML;
+    }
+    return htmlSafe(html);
   }
 
   captureCardSlots = modifier(
     (element: HTMLElement, _positional: unknown[]) => {
       let linkedCards = this.args.linkedCards;
       let baseUrl = this.args.cardReferenceBaseUrl;
+      let pendingUpdate = false;
+
+      // On the very first modifier setup, linkedCards is likely still loading
+      // (empty []). We skip showing fallback text on that run to avoid
+      // flashing raw URLs that will soon be replaced by card components.
+      let showFallback = this._modifierHasRun;
+      this._modifierHasRun = true;
+
+      let collectSlots = () => {
+        let cardsByUrl = new Map<string, CardDef>();
+        if (linkedCards?.length) {
+          for (let card of linkedCards) {
+            if (card?.id) {
+              cardsByUrl.set(card.id, card);
+            }
+          }
+        }
+
+        let slots: CardSlot[] = [];
 
-      let cardsByUrl = new Map<string, CardDef>();
-      if (linkedCards?.length) {
-        for (let card of linkedCards) {
-          if (card?.id) {
-            cardsByUrl.set(card.id, card);
+        for (let el of Array.from(
+          element.querySelectorAll<HTMLElement>(
+            '[data-boxel-bfm-inline-ref][data-boxel-bfm-type="card"]',
+          ),
+        )) {
+          let rawUrl = el.dataset.boxelBfmInlineRef;
+          if (!rawUrl) continue;
+          let resolved = resolveUrl(rawUrl, baseUrl);
+          let card = cardsByUrl.get(resolved);
+          if (card) {
+            slots.push({ element: el, card, format: 'atom', kind: 'inline' });
           }
         }
-      }
 
-      let slots: CardSlot[] = [];
-
-      for (let el of Array.from(
-        element.querySelectorAll<HTMLElement>(
-          '[data-boxel-bfm-inline-ref][data-boxel-bfm-type="card"]',
-        ),
-      )) {
-        let rawUrl = el.dataset.boxelBfmInlineRef;
-        if (!rawUrl) continue;
-        let resolved = resolveUrl(rawUrl, baseUrl);
-        let card = cardsByUrl.get(resolved);
-        if (card) {
-          el.textContent = '';
-          slots.push({ element: el, card, format: 'atom', kind: 'inline' });
+        for (let el of Array.from(
+          element.querySelectorAll<HTMLElement>(
+            '[data-boxel-bfm-block-ref][data-boxel-bfm-type="card"]',
+          ),
+        )) {
+          let rawUrl = el.dataset.boxelBfmBlockRef;
+          if (!rawUrl) continue;
+          let resolved = resolveUrl(rawUrl, baseUrl);
+          let card = cardsByUrl.get(resolved);
+          if (card) {
+            slots.push({
+              element: el,
+              card,
+              format: 'embedded',
+              kind: 'block',
+            });
+          }
+        }
+
+        // Inject fallback text for unresolvable card refs. Text content was
+        // stripped from the HTML in renderedHtml to prevent flash, so the URL
+        // must be read from the data attribute.  We only do this after the
+        // modifier has run once (giving linkedCards time to load).
+        if (showFallback) {
+          let resolvedEls = new Set(slots.map((s) => s.element));
+          for (let el of Array.from(
+            element.querySelectorAll<HTMLElement>(
+              '[data-boxel-bfm-type="card"]',
+            ),
+          )) {
+            if (!resolvedEls.has(el) && el.childElementCount === 0) {
+              let url =
+                el.dataset.boxelBfmInlineRef ||
+                el.dataset.boxelBfmBlockRef ||
+                '';
+              el.textContent = url;
+            }
+          }
         }
-      }
 
-      for (let el of Array.from(
-        element.querySelectorAll<HTMLElement>(
-          '[data-boxel-bfm-block-ref][data-boxel-bfm-type="card"]',
-        ),
-      )) {
-        let rawUrl = el.dataset.boxelBfmBlockRef;
-        if (!rawUrl) continue;
-        let resolved = resolveUrl(rawUrl, baseUrl);
-        let card = cardsByUrl.get(resolved);
-        if (card) {
-          el.textContent = '';
-          slots.push({
-            element: el,
-            card,
-            format: 'embedded',
-            kind: 'block',
+        return slots;
+      };
+
+      let updateSlots = () => {
+        pendingUpdate = false;
+        let nextSlots = collectSlots();
+        let didChange =
+          nextSlots.length !== this.cardSlots.length ||
+          nextSlots.some((slot, index) => {
+            let current = this.cardSlots[index];
+            return (
+              !current ||
+              current.element !== slot.element ||
+              current.card !== slot.card ||
+              current.format !== slot.format ||
+              current.kind !== slot.kind
+            );
           });
+
+        if (didChange) {
+          this.cardSlots = nextSlots;
+        }
+      };
+
+      let scheduleUpdate = () => {
+        if (pendingUpdate) {
+          return;
         }
+        pendingUpdate = true;
+        scheduleOnce('afterRender', this, updateSlots);
+      };
+
+      scheduleUpdate();
+
+      if (typeof MutationObserver === 'undefined') {
+        return;
       }
 
-      this.cardSlots = slots;
+      let observer = new MutationObserver(scheduleUpdate);
+      observer.observe(element, {
+        childList: true,
+        subtree: true,
+      });
+
+      return () => observer.disconnect();
     },
   );
 
diff --git a/packages/host/app/lib/externals.ts b/packages/host/app/lib/externals.ts
index ed71bae7107..ffd74cf6ddc 100644
--- a/packages/host/app/lib/externals.ts
+++ b/packages/host/app/lib/externals.ts
@@ -5,6 +5,7 @@ import * as emberHelper from '@ember/helper';
 import * as emberModifier from '@ember/modifier';
 import * as emberObject from '@ember/object';
 import * as emberObjectInternals from '@ember/object/internals';
+import * as emberRunloop from '@ember/runloop';
 import * as emberService from '@ember/service';
 
 import * as emberTemplate from '@ember/template';
@@ -90,6 +91,7 @@ export function shimExternals(virtualNetwork: VirtualNetwork) {
   virtualNetwork.shimModule('@ember/modifier', emberModifier);
   virtualNetwork.shimModule('@ember/object', emberObject);
   virtualNetwork.shimModule('@ember/object/internals', emberObjectInternals);
+  virtualNetwork.shimModule('@ember/runloop', emberRunloop);
   virtualNetwork.shimModule('@ember/service', emberService);
   virtualNetwork.shimModule('@ember/template', emberTemplate);
   virtualNetwork.shimModule('@ember/template-factory', emberTemplateFactory);
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 588d8905df8..2fcda43da92 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -7,6 +7,7 @@ import {
 } from '@ember/test-helpers';
 
 import { getService } from '@universal-ember/test-support';
+import window from 'ember-window-mock';
 
 import { module, test } from 'qunit';
 
@@ -420,6 +421,51 @@ module('Acceptance | markdown BFM card references', function (hooks) {
       .hasValue(`${testRealmURL}Pet/mango.json`);
   });
 
+  test('code mode restores embedded markdown card references after browser back navigation', async function (assert) {
+    await visitOperatorMode({
+      submode: 'code',
+      codePath: `${testRealmURL}bfm-test.md`,
+    });
+
+    await waitFor('[data-test-pet-atom]', { timeout: 10000 });
+    await waitFor('[data-test-pet-embedded]', { timeout: 10000 });
+    await waitFor('[data-test-card-url-bar-input]');
+
+    await click('[data-test-markdown-bfm-inline-card]');
+
+    await waitUntil(() => {
+      let currentValue =
+        (
+          document.querySelector(
+            '[data-test-card-url-bar-input]',
+          ) as HTMLInputElement | null
+        )?.value ?? '';
+      return currentValue === `${testRealmURL}Pet/mango.json`;
+    });
+
+    window.history.back();
+
+    await waitUntil(() => {
+      let currentValue =
+        (
+          document.querySelector(
+            '[data-test-card-url-bar-input]',
+          ) as HTMLInputElement | null
+        )?.value ?? '';
+      return currentValue === `${testRealmURL}bfm-test.md`;
+    });
+
+    await waitFor('[data-test-pet-atom]', { timeout: 10000 });
+    await waitFor('[data-test-pet-embedded]', { timeout: 10000 });
+
+    assert
+      .dom('[data-test-pet-atom]')
+      .exists('inline markdown card reference is restored after going back');
+    assert
+      .dom('[data-test-pet-embedded]')
+      .exists('block markdown card reference is restored after going back');
+  });
+
   test('interact mode shows overlays for markdown card references and clicking navigates', async function (assert) {
     await visitOperatorMode({
       stacks: [

From 58f7bf944f76d6673edab89632940b343f37a426 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 16:06:35 -0400
Subject: [PATCH 09/50] Fix CI: remove _modifierHasRun gate, add @ember/runloop
 to expected refs

The _modifierHasRun flag prevented fallback text from appearing when
the modifier only runs once (all card refs unresolvable). Since text
content is already stripped from the HTML, the afterRender fallback
injection is brief enough to not cause a visible flash.

Also adds @ember/runloop to the expected card references in the
indexing tests since the markdown template now imports scheduleOnce.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  | 36 +++++++------------
 .../tests/integration/realm-indexing-test.gts |  2 ++
 2 files changed, 15 insertions(+), 23 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index b4c125a6047..31d59840382 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -56,7 +56,6 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 }> {
   @tracked monacoContextInternal: any = undefined;
   @tracked cardSlots: CardSlot[] = [];
-  private _modifierHasRun = false;
   get isPrerenderContext() {
     return Boolean((globalThis as any).__boxelRenderContext);
   }
@@ -121,12 +120,6 @@ export default class MarkDownTemplate extends GlimmerComponent<{
       let baseUrl = this.args.cardReferenceBaseUrl;
       let pendingUpdate = false;
 
-      // On the very first modifier setup, linkedCards is likely still loading
-      // (empty []). We skip showing fallback text on that run to avoid
-      // flashing raw URLs that will soon be replaced by card components.
-      let showFallback = this._modifierHasRun;
-      this._modifierHasRun = true;
-
       let collectSlots = () => {
         let cardsByUrl = new Map<string, CardDef>();
         if (linkedCards?.length) {
@@ -174,22 +167,19 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 
         // Inject fallback text for unresolvable card refs. Text content was
         // stripped from the HTML in renderedHtml to prevent flash, so the URL
-        // must be read from the data attribute.  We only do this after the
-        // modifier has run once (giving linkedCards time to load).
-        if (showFallback) {
-          let resolvedEls = new Set(slots.map((s) => s.element));
-          for (let el of Array.from(
-            element.querySelectorAll<HTMLElement>(
-              '[data-boxel-bfm-type="card"]',
-            ),
-          )) {
-            if (!resolvedEls.has(el) && el.childElementCount === 0) {
-              let url =
-                el.dataset.boxelBfmInlineRef ||
-                el.dataset.boxelBfmBlockRef ||
-                '';
-              el.textContent = url;
-            }
+        // must be read from the data attribute.
+        let resolvedEls = new Set(slots.map((s) => s.element));
+        for (let el of Array.from(
+          element.querySelectorAll<HTMLElement>(
+            '[data-boxel-bfm-type="card"]',
+          ),
+        )) {
+          if (!resolvedEls.has(el) && el.childElementCount === 0) {
+            let url =
+              el.dataset.boxelBfmInlineRef ||
+              el.dataset.boxelBfmBlockRef ||
+              '';
+            el.textContent = url;
           }
         }
 
diff --git a/packages/host/tests/integration/realm-indexing-test.gts b/packages/host/tests/integration/realm-indexing-test.gts
index f85a747ab37..4cc42bec685 100644
--- a/packages/host/tests/integration/realm-indexing-test.gts
+++ b/packages/host/tests/integration/realm-indexing-test.gts
@@ -4190,6 +4190,7 @@ module(`Integration | realm indexing`, function (hooks) {
         'https://packages/@ember/helper',
         'https://packages/@ember/modifier',
         'https://packages/@ember/object',
+        'https://packages/@ember/runloop',
         'https://packages/@ember/template',
         'https://packages/@ember/template-factory',
         'https://packages/@glimmer/component',
@@ -4326,6 +4327,7 @@ module(`Integration | realm indexing`, function (hooks) {
         'https://packages/@ember/helper',
         'https://packages/@ember/modifier',
         'https://packages/@ember/object',
+        'https://packages/@ember/runloop',
         'https://packages/@ember/template',
         'https://packages/@ember/template-factory',
         'https://packages/@glimmer/component',

From a2ba3170e6e85b1afe69c24fb61611c9ec65b22c Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 16:21:05 -0400
Subject: [PATCH 10/50] Add comments explaining why modifier complexity is
 needed

Document why scheduleOnce, MutationObserver, pendingUpdate, and
didChange are all load-bearing in the captureCardSlots modifier.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 31d59840382..04883bbfee9 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -186,6 +186,10 @@ export default class MarkDownTemplate extends GlimmerComponent<{
         return slots;
       };
 
+      // Deferred via scheduleOnce to avoid Glimmer backtracking assertion.
+      // The didChange guard prevents an infinite loop: MutationObserver fires
+      // when #in-element renders cards → collectSlots → set cardSlots →
+      // re-render → observer fires again.
       let updateSlots = () => {
         pendingUpdate = false;
         let nextSlots = collectSlots();
@@ -217,6 +221,8 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 
       scheduleUpdate();
 
+      // MutationObserver re-collects slots when the DOM is reconstructed
+      // (e.g. after browser back-navigation rebuilds the element's children).
       if (typeof MutationObserver === 'undefined') {
         return;
       }

From debe3925e145b24ae2fe2a0b3195f916df8749c3 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 16:54:57 -0400
Subject: [PATCH 11/50] Prevent flash of raw URLs in markdown card references

- Restore _modifierHasRun gate to skip fallback text injection on the
  first modifier run (when linkedCards is still loading as empty [])
- Clean up leftover fallback text nodes when a card later resolves
- Guard fallback injection with textContent !== url to prevent infinite
  MutationObserver loop
- Update fallback test to waitUntil the text appears (second modifier
  run is async)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  | 38 ++++++++++++++-----
 .../acceptance/markdown-file-def-test.gts     |  9 ++++-
 2 files changed, 37 insertions(+), 10 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 04883bbfee9..217d85b2d8c 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -56,6 +56,10 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 }> {
   @tracked monacoContextInternal: any = undefined;
   @tracked cardSlots: CardSlot[] = [];
+  // Tracks whether the modifier has run at least once. On the first run,
+  // linkedCards is likely still loading (empty []) so we skip fallback text
+  // injection to avoid flashing raw URLs for cards that will soon resolve.
+  private _modifierHasRun = false;
   get isPrerenderContext() {
     return Boolean((globalThis as any).__boxelRenderContext);
   }
@@ -119,6 +123,8 @@ export default class MarkDownTemplate extends GlimmerComponent<{
       let linkedCards = this.args.linkedCards;
       let baseUrl = this.args.cardReferenceBaseUrl;
       let pendingUpdate = false;
+      let showFallback = this._modifierHasRun;
+      this._modifierHasRun = true;
 
       let collectSlots = () => {
         let cardsByUrl = new Map<string, CardDef>();
@@ -142,6 +148,9 @@ export default class MarkDownTemplate extends GlimmerComponent<{
           let resolved = resolveUrl(rawUrl, baseUrl);
           let card = cardsByUrl.get(resolved);
           if (card) {
+            if (el.firstChild?.nodeType === Node.TEXT_NODE) {
+              el.firstChild.remove();
+            }
             slots.push({ element: el, card, format: 'atom', kind: 'inline' });
           }
         }
@@ -156,6 +165,9 @@ export default class MarkDownTemplate extends GlimmerComponent<{
           let resolved = resolveUrl(rawUrl, baseUrl);
           let card = cardsByUrl.get(resolved);
           if (card) {
+            if (el.firstChild?.nodeType === Node.TEXT_NODE) {
+              el.firstChild.remove();
+            }
             slots.push({
               element: el,
               card,
@@ -167,19 +179,27 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 
         // Inject fallback text for unresolvable card refs. Text content was
         // stripped from the HTML in renderedHtml to prevent flash, so the URL
-        // must be read from the data attribute.
-        let resolvedEls = new Set(slots.map((s) => s.element));
-        for (let el of Array.from(
-          element.querySelectorAll<HTMLElement>(
-            '[data-boxel-bfm-type="card"]',
-          ),
-        )) {
-          if (!resolvedEls.has(el) && el.childElementCount === 0) {
+        // must be read from the data attribute. Only runs after the first
+        // modifier setup (showFallback) so we don't flash URLs while
+        // linkedCards is still loading.
+        if (showFallback) {
+          let resolvedEls = new Set(slots.map((s) => s.element));
+          for (let el of Array.from(
+            element.querySelectorAll<HTMLElement>(
+              '[data-boxel-bfm-type="card"]',
+            ),
+          )) {
             let url =
               el.dataset.boxelBfmInlineRef ||
               el.dataset.boxelBfmBlockRef ||
               '';
-            el.textContent = url;
+            if (
+              !resolvedEls.has(el) &&
+              el.childElementCount === 0 &&
+              el.textContent !== url
+            ) {
+              el.textContent = url;
+            }
           }
         }
 
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 2fcda43da92..77669d80a4b 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -365,7 +365,14 @@ module('Acceptance | markdown BFM card references', function (hooks) {
       codePath: `${testRealmURL}bfm-fallback.md`,
     });
 
-    await waitFor('[data-test-markdown-isolated]', { timeout: 10000 });
+    // Fallback text is only injected after the modifier's second run
+    // (first run skips it while linkedCards is loading).
+    await waitUntil(
+      () =>
+        document.querySelector('[data-boxel-bfm-inline-ref]')?.textContent ===
+        'https://nonexistent.example/Card/missing',
+      { timeout: 10000 },
+    );
 
     assert
       .dom('[data-boxel-bfm-inline-ref]')

From f15a4cbc931ee055db07f3c6751513fb8a6e5608 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 17:27:09 -0400
Subject: [PATCH 12/50] sideload relationships when returning FileDef JSON-API

---
 packages/base/markdown-file-def.gts           |  8 ++-
 .../tests/realm-endpoints-test.ts             | 53 +++++++++++++++++++
 .../realm-index-query-engine.ts               | 14 +++++
 packages/runtime-common/realm.ts              | 18 ++++++-
 4 files changed, 91 insertions(+), 2 deletions(-)

diff --git a/packages/base/markdown-file-def.gts b/packages/base/markdown-file-def.gts
index 7c2ace68fea..f4801efba0d 100644
--- a/packages/base/markdown-file-def.gts
+++ b/packages/base/markdown-file-def.gts
@@ -472,7 +472,12 @@ export class MarkdownDef extends FileDef {
     getStream: () => Promise<ByteStream>,
     options: { contentHash?: string } = {},
   ): Promise<
-    SerializedFile<{ title: string; excerpt: string; content: string }>
+    SerializedFile<{
+      title: string;
+      excerpt: string;
+      content: string;
+      cardReferenceUrls: string[];
+    }>
   > {
     let extension = getExtension(url);
     if (!MARKDOWN_EXTENSIONS.has(extension)) {
@@ -497,6 +502,7 @@ export class MarkdownDef extends FileDef {
       title: extractTitle(markdown, fallbackTitle),
       excerpt: extractExcerpt(markdown),
       content: markdown,
+      cardReferenceUrls: extractCardReferenceUrls(markdown, url),
     };
   }
 }
diff --git a/packages/realm-server/tests/realm-endpoints-test.ts b/packages/realm-server/tests/realm-endpoints-test.ts
index d9a99eaba76..ce9fbad3949 100644
--- a/packages/realm-server/tests/realm-endpoints-test.ts
+++ b/packages/realm-server/tests/realm-endpoints-test.ts
@@ -262,6 +262,59 @@ module(basename(__filename), function () {
       });
     });
 
+    test('file meta for markdown with card references includes sideloaded linked cards', async function (assert) {
+      let realmEventTimestampStart = Date.now();
+
+      await testRealm.write(
+        'card-refs.md',
+        `# Card References\n\nInline ref: :card[${testRealmHref}hassan]\n\n::card[${testRealmHref}jade]\n`,
+      );
+
+      await waitForIncrementalIndexEvent(
+        getMessagesSince,
+        realmEventTimestampStart,
+      );
+
+      let response = await request
+        .get(`/card-refs.md`)
+        .set('Accept', SupportedMimeType.FileMeta)
+        .set(
+          'Authorization',
+          `Bearer ${createJWT(testRealm, 'user', ['read', 'write'])}`,
+        );
+
+      assert.strictEqual(response.status, 200, 'HTTP 200 status');
+
+      let json = response.body;
+      assert.strictEqual(json.data.type, 'file-meta');
+      assert.deepEqual(json.data.meta?.adoptsFrom, {
+        module: `${baseRealm.url}markdown-file-def`,
+        name: 'MarkdownDef',
+      });
+
+      // The linkedCards query relationship should be populated
+      let linkedCards = json.data.relationships?.linkedCards;
+      assert.ok(linkedCards, 'linkedCards relationship is present');
+      assert.ok(
+        linkedCards?.links?.search,
+        'linkedCards has a search link',
+      );
+
+      // Sideloaded included resources should contain the referenced cards
+      assert.ok(json.included, 'response has included resources');
+      let includedIds = (json.included ?? []).map(
+        (r: { id: string }) => r.id,
+      );
+      assert.true(
+        includedIds.some((id: string) => id.includes('hassan')),
+        'included resources contain hassan card',
+      );
+      assert.true(
+        includedIds.some((id: string) => id.includes('jade')),
+        'included resources contain jade card',
+      );
+    });
+
     test('sets canonical path header for nested module requests', async function (assert) {
       let response = await request
         .get(`/nested/example`)
diff --git a/packages/runtime-common/realm-index-query-engine.ts b/packages/runtime-common/realm-index-query-engine.ts
index 249b44df8ba..080b76f7bd1 100644
--- a/packages/runtime-common/realm-index-query-engine.ts
+++ b/packages/runtime-common/realm-index-query-engine.ts
@@ -442,6 +442,20 @@ export class RealmIndexQueryEngine {
     return await this.#indexQueryEngine.getFile(url, opts);
   }
 
+  async loadLinksForResource(
+    resource: LooseCardResource | FileMetaResource,
+    opts?: Options,
+  ): Promise<(CardResource<Saved> | FileMetaResource)[]> {
+    return await this.loadLinks(
+      {
+        realmURL: this.realmURL,
+        resource,
+        omit: [...(resource.id ? [resource.id] : [])],
+      },
+      opts,
+    );
+  }
+
   private async populateQueryFields(
     resource: LooseCardResource | FileMetaResource,
     realmURL: URL,
diff --git a/packages/runtime-common/realm.ts b/packages/runtime-common/realm.ts
index 4bd49b503f8..82869a7bc68 100644
--- a/packages/runtime-common/realm.ts
+++ b/packages/runtime-common/realm.ts
@@ -133,7 +133,10 @@ import type { ResponseWithNodeStream, VirtualNetwork } from './virtual-network';
 import { RealmAuthDataSource } from './realm-auth-data-source';
 import { AliasCache } from './cache/alias-cache';
 import { fetcher } from './fetcher';
-import { RealmIndexQueryEngine } from './realm-index-query-engine';
+import {
+  RealmIndexQueryEngine,
+  relativizeDocument,
+} from './realm-index-query-engine';
 import { RealmIndexUpdater } from './realm-index-updater';
 import serialize from './file-serializer';
 import { validateWriteSize } from './write-size-validation';
@@ -2679,6 +2682,7 @@ export class Realm {
         attributes[key] = value;
       }
     }
+    let relationships = fileEntry.resource?.relationships;
     let doc: SingleFileMetaDocument = {
       data: {
         type: 'file-meta',
@@ -2686,6 +2690,7 @@ export class Realm {
         attributes: {
           ...attributes,
         },
+        ...(relationships ? { relationships } : {}),
         meta: {
           adoptsFrom,
           realmInfo,
@@ -2694,6 +2699,17 @@ export class Realm {
         links: { self: fileURL },
       },
     };
+    let included = await this.#realmIndexQueryEngine.loadLinksForResource(
+      doc.data,
+      { loadLinks: true },
+    );
+    if (included.length > 0) {
+      doc.included = included;
+    }
+    relativizeDocument(
+      doc as unknown as SingleCardDocument,
+      new URL(this.url),
+    );
     return createResponse({
       body: JSON.stringify(doc, null, 2),
       init: {

From fd61b8693c62d1dbd59d79ee2900a541bdb4417d Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 20:35:25 -0400
Subject: [PATCH 13/50] Fix CI: remove server-side sideloading from file-meta
 responses

The loadLinksForResource call caused timeouts for non-markdown files
and relativizeDocument broke adoptsFrom URL assertions. The client
deserialization pipeline also can't handle included resources in
file-meta docs. Instead, cardReferenceUrls is stored in indexed
attributes via extractAttributes, letting client-side queries work.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../realm-server/tests/cards/card-refs.md     |  7 ++++
 .../tests/realm-endpoints-test.ts             | 36 +++++--------------
 packages/runtime-common/realm.ts              | 18 +---------
 3 files changed, 16 insertions(+), 45 deletions(-)
 create mode 100644 packages/realm-server/tests/cards/card-refs.md

diff --git a/packages/realm-server/tests/cards/card-refs.md b/packages/realm-server/tests/cards/card-refs.md
new file mode 100644
index 00000000000..c1ebea7f72e
--- /dev/null
+++ b/packages/realm-server/tests/cards/card-refs.md
@@ -0,0 +1,7 @@
+# Card References
+
+Inline ref: :card[./hassan]
+
+::card[./jade]
+
+End of document.
diff --git a/packages/realm-server/tests/realm-endpoints-test.ts b/packages/realm-server/tests/realm-endpoints-test.ts
index ce9fbad3949..894cb630abf 100644
--- a/packages/realm-server/tests/realm-endpoints-test.ts
+++ b/packages/realm-server/tests/realm-endpoints-test.ts
@@ -262,19 +262,7 @@ module(basename(__filename), function () {
       });
     });
 
-    test('file meta for markdown with card references includes sideloaded linked cards', async function (assert) {
-      let realmEventTimestampStart = Date.now();
-
-      await testRealm.write(
-        'card-refs.md',
-        `# Card References\n\nInline ref: :card[${testRealmHref}hassan]\n\n::card[${testRealmHref}jade]\n`,
-      );
-
-      await waitForIncrementalIndexEvent(
-        getMessagesSince,
-        realmEventTimestampStart,
-      );
-
+    test('file meta for markdown with card references stores cardReferenceUrls', async function (assert) {
       let response = await request
         .get(`/card-refs.md`)
         .set('Accept', SupportedMimeType.FileMeta)
@@ -292,26 +280,18 @@ module(basename(__filename), function () {
         name: 'MarkdownDef',
       });
 
-      // The linkedCards query relationship should be populated
-      let linkedCards = json.data.relationships?.linkedCards;
-      assert.ok(linkedCards, 'linkedCards relationship is present');
+      let cardReferenceUrls = json.data.attributes?.cardReferenceUrls;
       assert.ok(
-        linkedCards?.links?.search,
-        'linkedCards has a search link',
-      );
-
-      // Sideloaded included resources should contain the referenced cards
-      assert.ok(json.included, 'response has included resources');
-      let includedIds = (json.included ?? []).map(
-        (r: { id: string }) => r.id,
+        Array.isArray(cardReferenceUrls),
+        'cardReferenceUrls attribute is present',
       );
       assert.true(
-        includedIds.some((id: string) => id.includes('hassan')),
-        'included resources contain hassan card',
+        cardReferenceUrls.some((url: string) => url.includes('hassan')),
+        'cardReferenceUrls includes hassan',
       );
       assert.true(
-        includedIds.some((id: string) => id.includes('jade')),
-        'included resources contain jade card',
+        cardReferenceUrls.some((url: string) => url.includes('jade')),
+        'cardReferenceUrls includes jade',
       );
     });
 
diff --git a/packages/runtime-common/realm.ts b/packages/runtime-common/realm.ts
index 82869a7bc68..4bd49b503f8 100644
--- a/packages/runtime-common/realm.ts
+++ b/packages/runtime-common/realm.ts
@@ -133,10 +133,7 @@ import type { ResponseWithNodeStream, VirtualNetwork } from './virtual-network';
 import { RealmAuthDataSource } from './realm-auth-data-source';
 import { AliasCache } from './cache/alias-cache';
 import { fetcher } from './fetcher';
-import {
-  RealmIndexQueryEngine,
-  relativizeDocument,
-} from './realm-index-query-engine';
+import { RealmIndexQueryEngine } from './realm-index-query-engine';
 import { RealmIndexUpdater } from './realm-index-updater';
 import serialize from './file-serializer';
 import { validateWriteSize } from './write-size-validation';
@@ -2682,7 +2679,6 @@ export class Realm {
         attributes[key] = value;
       }
     }
-    let relationships = fileEntry.resource?.relationships;
     let doc: SingleFileMetaDocument = {
       data: {
         type: 'file-meta',
@@ -2690,7 +2686,6 @@ export class Realm {
         attributes: {
           ...attributes,
         },
-        ...(relationships ? { relationships } : {}),
         meta: {
           adoptsFrom,
           realmInfo,
@@ -2699,17 +2694,6 @@ export class Realm {
         links: { self: fileURL },
       },
     };
-    let included = await this.#realmIndexQueryEngine.loadLinksForResource(
-      doc.data,
-      { loadLinks: true },
-    );
-    if (included.length > 0) {
-      doc.included = included;
-    }
-    relativizeDocument(
-      doc as unknown as SingleCardDocument,
-      new URL(this.url),
-    );
     return createResponse({
       body: JSON.stringify(doc, null, 2),
       init: {

From e7cf1ea8d878c5346e278c7a7c98d10d7a14277a Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 21:52:22 -0400
Subject: [PATCH 14/50] Fix CI: add card-refs.md to directory listing, increase
 waitUntil timeouts

The new card-refs.md test fixture was missing from the expected directory
listing assertion. Also increased waitUntil timeouts in the back-navigation
test from the default 1000ms to 5000ms to avoid CI flakiness.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../acceptance/markdown-file-def-test.gts     | 42 +++++++++++--------
 .../tests/realm-endpoints-test.ts             |  8 ++++
 2 files changed, 32 insertions(+), 18 deletions(-)

diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 77669d80a4b..5c645fd4e54 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -440,27 +440,33 @@ module('Acceptance | markdown BFM card references', function (hooks) {
 
     await click('[data-test-markdown-bfm-inline-card]');
 
-    await waitUntil(() => {
-      let currentValue =
-        (
-          document.querySelector(
-            '[data-test-card-url-bar-input]',
-          ) as HTMLInputElement | null
-        )?.value ?? '';
-      return currentValue === `${testRealmURL}Pet/mango.json`;
-    });
+    await waitUntil(
+      () => {
+        let currentValue =
+          (
+            document.querySelector(
+              '[data-test-card-url-bar-input]',
+            ) as HTMLInputElement | null
+          )?.value ?? '';
+        return currentValue === `${testRealmURL}Pet/mango.json`;
+      },
+      { timeout: 5000 },
+    );
 
     window.history.back();
 
-    await waitUntil(() => {
-      let currentValue =
-        (
-          document.querySelector(
-            '[data-test-card-url-bar-input]',
-          ) as HTMLInputElement | null
-        )?.value ?? '';
-      return currentValue === `${testRealmURL}bfm-test.md`;
-    });
+    await waitUntil(
+      () => {
+        let currentValue =
+          (
+            document.querySelector(
+              '[data-test-card-url-bar-input]',
+            ) as HTMLInputElement | null
+          )?.value ?? '';
+        return currentValue === `${testRealmURL}bfm-test.md`;
+      },
+      { timeout: 5000 },
+    );
 
     await waitFor('[data-test-pet-atom]', { timeout: 10000 });
     await waitFor('[data-test-pet-embedded]', { timeout: 10000 });
diff --git a/packages/realm-server/tests/realm-endpoints-test.ts b/packages/realm-server/tests/realm-endpoints-test.ts
index 894cb630abf..063f39ca9f7 100644
--- a/packages/realm-server/tests/realm-endpoints-test.ts
+++ b/packages/realm-server/tests/realm-endpoints-test.ts
@@ -1461,6 +1461,14 @@ module(basename(__filename), function () {
                   kind: 'file',
                 },
               },
+              'card-refs.md': {
+                links: {
+                  related: `${testRealmHref}card-refs.md`,
+                },
+                meta: {
+                  kind: 'file',
+                },
+              },
               'chess-gallery.gts': {
                 links: {
                   related: `${testRealmHref}chess-gallery.gts`,

From be011fae6e47bebbe5023caf06390d2d3b81502f Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Thu, 2 Apr 2026 22:41:53 -0400
Subject: [PATCH 15/50] Fix CI: wait for overlay click handler before clicking
 card reference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The back-navigation test clicked the inline card reference before the
Overlays component had bound its click handler. ElementTracker schedules
afterRender, then Overlays re-renders and binds handlers — two render
cycles after the card component appears. Wait for cursor:pointer (set
by Overlays) as a signal the handler is ready. Also add card-refs.md
to the directory listing assertion.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../host/tests/acceptance/markdown-file-def-test.gts  | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 5c645fd4e54..1c68eb5a374 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -438,6 +438,17 @@ module('Acceptance | markdown BFM card references', function (hooks) {
     await waitFor('[data-test-pet-embedded]', { timeout: 10000 });
     await waitFor('[data-test-card-url-bar-input]');
 
+    // Wait for the overlay click handler to be bound (cursor: pointer is set by the Overlays component)
+    await waitUntil(
+      () => {
+        let el = document.querySelector(
+          '[data-test-markdown-bfm-inline-card]',
+        ) as HTMLElement | null;
+        return el?.style.cursor === 'pointer';
+      },
+      { timeout: 5000 },
+    );
+
     await click('[data-test-markdown-bfm-inline-card]');
 
     await waitUntil(

From 9bb4bda0aefa17329233b3898044db5cf1a3df5c Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 11:02:12 -0400
Subject: [PATCH 16/50] Fix CI: increase overlay click handler timeout for
 back-navigation test

The cursor:pointer waitUntil was at 5000ms but CI runners under load
(widespread Failed to fetch errors for icons/modules) can need longer
for the two render cycles before the Overlays click handler binds.
Increase to 10000ms to match the other waitFor timeouts in this test.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/tests/acceptance/markdown-file-def-test.gts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 1c68eb5a374..38abc7df227 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -438,7 +438,9 @@ module('Acceptance | markdown BFM card references', function (hooks) {
     await waitFor('[data-test-pet-embedded]', { timeout: 10000 });
     await waitFor('[data-test-card-url-bar-input]');
 
-    // Wait for the overlay click handler to be bound (cursor: pointer is set by the Overlays component)
+    // Wait for the overlay click handler to be bound (cursor: pointer is set by the Overlays component).
+    // CI runners under load can take longer for the two render cycles (ElementTracker afterRender →
+    // Overlays re-render + handler bind), so use a generous timeout.
     await waitUntil(
       () => {
         let el = document.querySelector(
@@ -446,7 +448,7 @@ module('Acceptance | markdown BFM card references', function (hooks) {
         ) as HTMLElement | null;
         return el?.style.cursor === 'pointer';
       },
-      { timeout: 5000 },
+      { timeout: 10000 },
     );
 
     await click('[data-test-markdown-bfm-inline-card]');

From 831863641c491ad945fdf514443232822c3c6341 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 11:25:39 -0400
Subject: [PATCH 17/50] Fix CI: increase all waitUntil timeouts to 15s with
 diagnostic messages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The back-navigation test has three waitUntil calls — overlay handler
bind, URL bar after click, and URL bar after history.back(). All
involve async card search queries that can be slow on CI runners under
load. Bumped all three from 5-10s to 15s and added timeoutMessage to
each so future failures identify which step timed out.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../acceptance/markdown-file-def-test.gts     | 22 ++++++++++++++-----
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 38abc7df227..74b3d409c6f 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -438,9 +438,9 @@ module('Acceptance | markdown BFM card references', function (hooks) {
     await waitFor('[data-test-pet-embedded]', { timeout: 10000 });
     await waitFor('[data-test-card-url-bar-input]');
 
-    // Wait for the overlay click handler to be bound (cursor: pointer is set by the Overlays component).
-    // CI runners under load can take longer for the two render cycles (ElementTracker afterRender →
-    // Overlays re-render + handler bind), so use a generous timeout.
+    // Wait for the overlay click handler to be bound (cursor: pointer is set
+    // by the Overlays component). CI runners under load need longer for the
+    // render cycles before the handler binds.
     await waitUntil(
       () => {
         let el = document.querySelector(
@@ -448,7 +448,10 @@ module('Acceptance | markdown BFM card references', function (hooks) {
         ) as HTMLElement | null;
         return el?.style.cursor === 'pointer';
       },
-      { timeout: 10000 },
+      {
+        timeout: 15000,
+        timeoutMessage: 'overlay click handler (cursor:pointer) was not bound',
+      },
     );
 
     await click('[data-test-markdown-bfm-inline-card]');
@@ -463,7 +466,10 @@ module('Acceptance | markdown BFM card references', function (hooks) {
           )?.value ?? '';
         return currentValue === `${testRealmURL}Pet/mango.json`;
       },
-      { timeout: 5000 },
+      {
+        timeout: 15000,
+        timeoutMessage: 'URL bar did not navigate to Pet/mango.json after click',
+      },
     );
 
     window.history.back();
@@ -478,7 +484,11 @@ module('Acceptance | markdown BFM card references', function (hooks) {
           )?.value ?? '';
         return currentValue === `${testRealmURL}bfm-test.md`;
       },
-      { timeout: 5000 },
+      {
+        timeout: 15000,
+        timeoutMessage:
+          'URL bar did not navigate back to bfm-test.md after history.back()',
+      },
     );
 
     await waitFor('[data-test-pet-atom]', { timeout: 10000 });

From 4f372d42443cd09eb5069e60f8c55b958a03a50d Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 12:38:15 -0400
Subject: [PATCH 18/50] Fix CI: replace history.back() with URL bar navigation
 in back-nav test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Code-mode navigation uses replaceState (not pushState), so
history.back() has no entry to return to — causing the test to
time out on CI and close the browser tab locally. Navigate back
via the URL bar instead, which still tests that card references
re-render correctly after returning to a markdown file.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../acceptance/markdown-file-def-test.gts     | 36 ++++++++-----------
 1 file changed, 15 insertions(+), 21 deletions(-)

diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 74b3d409c6f..7bcb1555253 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -1,13 +1,14 @@
 import {
   click,
+  fillIn,
   triggerEvent,
+  triggerKeyEvent,
   visit,
   waitFor,
   waitUntil,
 } from '@ember/test-helpers';
 
 import { getService } from '@universal-ember/test-support';
-import window from 'ember-window-mock';
 
 import { module, test } from 'qunit';
 
@@ -428,7 +429,7 @@ module('Acceptance | markdown BFM card references', function (hooks) {
       .hasValue(`${testRealmURL}Pet/mango.json`);
   });
 
-  test('code mode restores embedded markdown card references after browser back navigation', async function (assert) {
+  test('code mode restores embedded markdown card references after navigating away and back', async function (assert) {
     await visitOperatorMode({
       submode: 'code',
       codePath: `${testRealmURL}bfm-test.md`,
@@ -472,23 +473,16 @@ module('Acceptance | markdown BFM card references', function (hooks) {
       },
     );
 
-    window.history.back();
-
-    await waitUntil(
-      () => {
-        let currentValue =
-          (
-            document.querySelector(
-              '[data-test-card-url-bar-input]',
-            ) as HTMLInputElement | null
-          )?.value ?? '';
-        return currentValue === `${testRealmURL}bfm-test.md`;
-      },
-      {
-        timeout: 15000,
-        timeoutMessage:
-          'URL bar did not navigate back to bfm-test.md after history.back()',
-      },
+    // Navigate back to the markdown file via the URL bar (code-mode navigation
+    // uses replaceState, so history.back() has no entry to return to).
+    await fillIn(
+      '[data-test-card-url-bar-input]',
+      `${testRealmURL}bfm-test.md`,
+    );
+    await triggerKeyEvent(
+      '[data-test-card-url-bar-input]',
+      'keypress',
+      'Enter',
     );
 
     await waitFor('[data-test-pet-atom]', { timeout: 10000 });
@@ -496,10 +490,10 @@ module('Acceptance | markdown BFM card references', function (hooks) {
 
     assert
       .dom('[data-test-pet-atom]')
-      .exists('inline markdown card reference is restored after going back');
+      .exists('inline markdown card reference is restored after navigating back');
     assert
       .dom('[data-test-pet-embedded]')
-      .exists('block markdown card reference is restored after going back');
+      .exists('block markdown card reference is restored after navigating back');
   });
 
   test('interact mode shows overlays for markdown card references and clicking navigates', async function (assert) {

From 4c27f351c7f7bec9f4d7b43542b45725623aebed Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 13:08:19 -0400
Subject: [PATCH 19/50] Fix lint: prettier formatting in back-navigation test

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../host/tests/acceptance/markdown-file-def-test.gts  | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index 7bcb1555253..c320439e3e4 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -469,7 +469,8 @@ module('Acceptance | markdown BFM card references', function (hooks) {
       },
       {
         timeout: 15000,
-        timeoutMessage: 'URL bar did not navigate to Pet/mango.json after click',
+        timeoutMessage:
+          'URL bar did not navigate to Pet/mango.json after click',
       },
     );
 
@@ -490,10 +491,14 @@ module('Acceptance | markdown BFM card references', function (hooks) {
 
     assert
       .dom('[data-test-pet-atom]')
-      .exists('inline markdown card reference is restored after navigating back');
+      .exists(
+        'inline markdown card reference is restored after navigating back',
+      );
     assert
       .dom('[data-test-pet-embedded]')
-      .exists('block markdown card reference is restored after navigating back');
+      .exists(
+        'block markdown card reference is restored after navigating back',
+      );
   });
 
   test('interact mode shows overlays for markdown card references and clicking navigates', async function (assert) {

From fc706d70f1c42927d2c596a7d4d3e7dce23c7f3b Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 16:41:07 -0400
Subject: [PATCH 20/50] Address PR review comments on bfm-card-references

- Fix document-order preservation in extractBfmReferences(): collect all
  matches with their index and sort before deduplicating, instead of
  grouping by keyword which reorders references.
- Handle multi-backtick inline code spans (e.g. ``code``) in extraction
  regex, not just single-backtick spans.
- Update doc comment for bfmExtensionsForKeyword() to reflect that
  placeholders include URL as fallback text content.
- Add test for multi-backtick inline code case.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../tests/unit/bfm-card-references-test.ts    |  8 +++-
 .../runtime-common/bfm-card-references.ts     | 40 +++++++++++++------
 2 files changed, 34 insertions(+), 14 deletions(-)

diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 3ca10a62f5e..1c39bd6096f 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -67,6 +67,12 @@ module('Unit | bfm-card-references', function () {
       assert.deepEqual(urls, []);
     });
 
+    test('ignores references inside multi-backtick inline code', function (assert) {
+      let markdown = 'Use ``:card[https://example.com/cards/1]`` syntax.';
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, []);
+    });
+
     test('skips malformed URLs with empty base', function (assert) {
       let markdown = ':card[not a valid url at all]';
       let urls = extractCardReferenceUrls(markdown, '');
@@ -209,7 +215,7 @@ module('Unit | bfm-card-references', function () {
     test('markdown without card refs is unaffected', function (assert) {
       let markdown = '# Hello\n\nSome **bold** text.';
       let withBfm = markdownToHtml(markdown);
-      assert.true(withBfm.includes('<h1>Hello</h1>'));
+      assert.true(withBfm.includes('<h1 id="hello">Hello</h1>'));
       assert.true(withBfm.includes('<strong>bold</strong>'));
       assert.false(withBfm.includes('data-boxel-bfm'));
     });
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
index b029117452b..95836ea3ca3 100644
--- a/packages/runtime-common/bfm-card-references.ts
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -5,7 +5,9 @@ import type { TokenizerAndRendererExtension } from 'marked';
 // Regex patterns for stripping code before extraction.
 // These avoid backtick-in-regex issues that break content-tag in .gts files.
 const FENCED_CODE_RE = /```[\s\S]*?```/g;
-const INLINE_CODE_RE = /`([^`]+)`/g;
+// Match code spans with any number of consecutive backticks as delimiter
+// (e.g. `code`, ``code``, ```code```).
+const INLINE_CODE_RE = new RegExp('(`+)([\\s\\S]*?)\\1', 'g');
 
 function resolveUrl(ref: string, baseUrl: string | undefined): string | null {
   try {
@@ -36,8 +38,8 @@ export function extractBfmReferences(
     .replace(FENCED_CODE_RE, '')
     .replace(INLINE_CODE_RE, '');
 
-  let seen = new Set<string>();
-  let refs: BfmReference[] = [];
+  // Collect all matches with their position so we can sort by document order
+  let matches: { index: number; url: string; keyword: string }[] = [];
 
   for (let keyword of keywords) {
     let blockRe = new RegExp(`^::${keyword}\\[([^\\]]+)\\]`, 'gm');
@@ -46,20 +48,30 @@ export function extractBfmReferences(
 
     for (let match of stripped.matchAll(blockRe)) {
       let resolved = resolveUrl(match[1], baseUrl);
-      if (resolved && !seen.has(resolved)) {
-        seen.add(resolved);
-        refs.push({ url: resolved, keyword });
+      if (resolved) {
+        matches.push({ index: match.index!, url: resolved, keyword });
       }
     }
     for (let match of stripped.matchAll(inlineRe)) {
       let resolved = resolveUrl(match[1], baseUrl);
-      if (resolved && !seen.has(resolved)) {
-        seen.add(resolved);
-        refs.push({ url: resolved, keyword });
+      if (resolved) {
+        matches.push({ index: match.index!, url: resolved, keyword });
       }
     }
   }
 
+  // Sort by position in the document, then deduplicate by URL (keeping first)
+  matches.sort((a, b) => a.index - b.index);
+
+  let seen = new Set<string>();
+  let refs: BfmReference[] = [];
+  for (let m of matches) {
+    if (!seen.has(m.url)) {
+      seen.add(m.url);
+      refs.push({ url: m.url, keyword: m.keyword });
+    }
+  }
+
   return refs;
 }
 
@@ -77,11 +89,13 @@ export function extractCardReferenceUrls(
 /**
  * Creates marked v12 extensions for a given BFM keyword.
  *
- * Block: `::keyword[URL]` → `<div data-boxel-bfm-block-ref="URL" data-boxel-bfm-type="keyword"></div>`
- * Inline: `:keyword[URL]` → `<span data-boxel-bfm-inline-ref="URL" data-boxel-bfm-type="keyword"></span>`
+ * Block: `::keyword[URL]` → `<div data-boxel-bfm-block-ref="URL" data-boxel-bfm-type="keyword">URL</div>`
+ * Inline: `:keyword[URL]` → `<span data-boxel-bfm-inline-ref="URL" data-boxel-bfm-type="keyword">URL</span>`
  *
- * URLs are emitted as-is (unresolved). The consumer is responsible for
- * resolving them against a base URL before matching to instance IDs.
+ * The URL text content serves as fallback text shown before referenced cards
+ * load or when they cannot be resolved. URLs are emitted as-is (unresolved).
+ * The consumer is responsible for resolving them against a base URL before
+ * matching to instance IDs.
  */
 export function bfmExtensionsForKeyword(
   keyword: string,

From 31bf2d5b0693e97a2b20eb5bb7cb990bf0c35b93 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 16:58:14 -0400
Subject: [PATCH 21/50] Fix test: revert heading ID assertion not yet in this
 PR

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/tests/unit/bfm-card-references-test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 1c39bd6096f..8591c7738b3 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -215,7 +215,7 @@ module('Unit | bfm-card-references', function () {
     test('markdown without card refs is unaffected', function (assert) {
       let markdown = '# Hello\n\nSome **bold** text.';
       let withBfm = markdownToHtml(markdown);
-      assert.true(withBfm.includes('<h1 id="hello">Hello</h1>'));
+      assert.true(withBfm.includes('<h1>Hello</h1>'));
       assert.true(withBfm.includes('<strong>bold</strong>'));
       assert.false(withBfm.includes('data-boxel-bfm'));
     });

From 87cda0ad397c590dccda5b497ceb586431c4a767 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Mon, 6 Apr 2026 11:12:09 -0400
Subject: [PATCH 22/50] Handle .json extension in BFM card reference URLs

Card IDs in the index don't include .json, but users may write
:card[http://example.com/my-card.json] in markdown. Strip the .json
extension in extractBfmReferences() (so the linksToMany query matches)
and in the resolveUrl helper (so slot matching finds the card).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  |  5 +++--
 .../tests/unit/bfm-card-references-test.ts    | 22 +++++++++++++++++++
 .../runtime-common/bfm-card-references.ts     | 13 +++++++++--
 3 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 217d85b2d8c..12a3e0cf741 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -12,6 +12,7 @@ import {
   markdownToHtml,
   preloadMarkdownLanguages,
   resolveCardReference,
+  trimJsonExtension,
 } from '@cardstack/runtime-common';
 import { type BaseDef, type CardDef, getComponent } from '../card-api';
 import { CardContextConsumer } from '../field-component';
@@ -41,9 +42,9 @@ interface CardSlot {
 
 function resolveUrl(raw: string, baseUrl: string | null | undefined): string {
   try {
-    return resolveCardReference(raw, baseUrl || undefined);
+    return trimJsonExtension(resolveCardReference(raw, baseUrl || undefined));
   } catch {
-    return raw;
+    return trimJsonExtension(raw);
   }
 }
 
diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 8591c7738b3..83accd5a2b3 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -44,6 +44,28 @@ module('Unit | bfm-card-references', function () {
       assert.deepEqual(urls, ['https://realm.example/docs/my-card']);
     });
 
+    test('strips .json extension from extracted URLs', function (assert) {
+      let markdown = [
+        ':card[https://example.com/cards/1.json]',
+        '',
+        '::card[https://example.com/cards/2.json]',
+      ].join('\n');
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, [
+        'https://example.com/cards/1',
+        'https://example.com/cards/2',
+      ]);
+    });
+
+    test('deduplicates URLs that differ only by .json extension', function (assert) {
+      let markdown = [
+        ':card[https://example.com/cards/1]',
+        ':card[https://example.com/cards/1.json]',
+      ].join('\n');
+      let urls = extractCardReferenceUrls(markdown, 'https://base.com/');
+      assert.deepEqual(urls, ['https://example.com/cards/1']);
+    });
+
     test('deduplicates URLs', function (assert) {
       let markdown = [
         ':card[https://example.com/cards/1]',
diff --git a/packages/runtime-common/bfm-card-references.ts b/packages/runtime-common/bfm-card-references.ts
index 95836ea3ca3..2b5a403112c 100644
--- a/packages/runtime-common/bfm-card-references.ts
+++ b/packages/runtime-common/bfm-card-references.ts
@@ -1,5 +1,6 @@
 import { escapeHtml } from './helpers/html';
 import { resolveCardReference } from './card-reference-resolver';
+import { trimJsonExtension } from './url';
 import type { TokenizerAndRendererExtension } from 'marked';
 
 // Regex patterns for stripping code before extraction.
@@ -49,13 +50,21 @@ export function extractBfmReferences(
     for (let match of stripped.matchAll(blockRe)) {
       let resolved = resolveUrl(match[1], baseUrl);
       if (resolved) {
-        matches.push({ index: match.index!, url: resolved, keyword });
+        matches.push({
+          index: match.index!,
+          url: trimJsonExtension(resolved),
+          keyword,
+        });
       }
     }
     for (let match of stripped.matchAll(inlineRe)) {
       let resolved = resolveUrl(match[1], baseUrl);
       if (resolved) {
-        matches.push({ index: match.index!, url: resolved, keyword });
+        matches.push({
+          index: match.index!,
+          url: trimJsonExtension(resolved),
+          keyword,
+        });
       }
     }
   }

From d15aecb471dd4027956fa69936c00aa10739c752 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 21:17:35 -0400
Subject: [PATCH 23/50] Add BFM Layer 3 markdown extensions: alerts, footnotes,
 math, tables, heading IDs, mermaid

Register 5 community marked extensions and 1 custom extension for BFM
(Boxel Flavored Markdown) Layer 3 features:

- marked-alert: GFM alert/admonition syntax (> [!NOTE], > [!WARNING], etc.)
- marked-footnote: footnote syntax ([^1] references + definitions)
- marked-extended-tables: colspan/rowspan in markdown tables
- marked-gfm-heading-id: auto-generated slug IDs on headings
- bfm-math (custom): LaTeX math placeholders ($...$, $$...$$) that emit
  lightweight placeholder HTML instead of bundling KaTeX (~268KB min +
  1.1MB fonts), enabling lazy client-side rendering
- Mermaid code blocks (```mermaid) emit a <pre class="mermaid"> placeholder
  for client-side rendering

Each feature has smoke tests covering both markedSync output and
DOMPurify sanitization pass-through.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/tests/unit/marked-sync-test.ts | 190 ++++++++++++++++++-
 packages/runtime-common/bfm-math.ts          |  91 +++++++++
 packages/runtime-common/marked-sync.ts       |  19 ++
 packages/runtime-common/package.json         |   4 +
 pnpm-lock.yaml                               |  66 +++++++
 pnpm-workspace.yaml                          |   4 +
 6 files changed, 370 insertions(+), 4 deletions(-)
 create mode 100644 packages/runtime-common/bfm-math.ts

diff --git a/packages/host/tests/unit/marked-sync-test.ts b/packages/host/tests/unit/marked-sync-test.ts
index b535bbc6923..42e4f10d52a 100644
--- a/packages/host/tests/unit/marked-sync-test.ts
+++ b/packages/host/tests/unit/marked-sync-test.ts
@@ -11,8 +11,8 @@ module('Unit | marked-sync', function () {
     const result = markedSync(markdown);
 
     assert.true(
-      result.includes('<h1>Hello</h1>'),
-      'converts heading correctly',
+      result.includes('<h1 id="hello">Hello</h1>'),
+      'converts heading correctly (with auto-generated id)',
     );
     assert.true(
       result.includes('<strong>Bold text</strong>'),
@@ -46,7 +46,10 @@ module('Unit | marked-sync', function () {
     const markdown = '# Hello <script>alert("XSS")</script>';
     const result = markdownToHtml(markdown);
 
-    assert.true(result.includes('<h1>Hello </h1>'), 'heading was preserved');
+    assert.true(
+      result.includes('id="hello-') && result.includes('>Hello </h1>'),
+      'heading was preserved with auto-generated id',
+    );
   });
 
   test('markdownToHtml with sanitize=false', function (assert) {
@@ -54,7 +57,7 @@ module('Unit | marked-sync', function () {
     const result = markdownToHtml(markdown, { sanitize: false });
 
     assert.true(
-      result.includes('<h1>Hello <script>alert("XSS")</script></h1>'),
+      result.includes('<script>alert("XSS")</script></h1>'),
       'returns unsanitized HTML',
     );
   });
@@ -174,4 +177,183 @@ module('Unit | marked-sync', function () {
       'escapes HTML tags within code fences tags',
     );
   });
+
+  // ── BFM Layer 3: GFM Alerts (marked-alert) ──
+
+  test('markedSync renders GFM note alert', function (assert) {
+    const markdown = '> [!NOTE]\n> This is a note.';
+    const result = markedSync(markdown);
+
+    assert.true(
+      result.includes('markdown-alert'),
+      'output contains alert class',
+    );
+    assert.true(
+      result.includes('markdown-alert-note'),
+      'output contains note variant class',
+    );
+    assert.true(
+      result.includes('This is a note.'),
+      'alert content is rendered',
+    );
+  });
+
+  test('markedSync renders GFM warning alert', function (assert) {
+    const markdown = '> [!WARNING]\n> Be careful!';
+    const result = markedSync(markdown);
+
+    assert.true(
+      result.includes('markdown-alert-warning'),
+      'output contains warning variant class',
+    );
+  });
+
+  // ── BFM Layer 3: Math / LaTeX (placeholder for lazy KaTeX) ──
+
+  test('markedSync renders inline math as placeholder', function (assert) {
+    const markdown = 'The formula $E = mc^2$ is famous.';
+    const result = markedSync(markdown);
+
+    assert.true(
+      result.includes('class="math-placeholder"'),
+      'output contains math placeholder class',
+    );
+    assert.true(
+      result.includes('data-math="E = mc^2"'),
+      'placeholder carries math expression in data attribute',
+    );
+    assert.true(
+      result.includes('data-display="false"'),
+      'inline math has display=false',
+    );
+  });
+
+  test('markedSync renders block math as placeholder', function (assert) {
+    const markdown = '$$\nx^2 + y^2 = z^2\n$$';
+    const result = markedSync(markdown);
+
+    assert.true(
+      result.includes('<div class="math-placeholder"'),
+      'block math uses a div placeholder',
+    );
+    assert.true(
+      result.includes('data-display="true"'),
+      'block math has display=true',
+    );
+  });
+
+  // ── BFM Layer 3: Mermaid diagram placeholder ──
+
+  test('markedSync renders mermaid code block as placeholder', function (assert) {
+    const markdown = '```mermaid\nflowchart TD\n    A --> B\n```';
+    const result = markedSync(markdown);
+
+    assert.true(
+      result.includes('<pre class="mermaid">'),
+      'mermaid block uses mermaid class instead of data-code-language',
+    );
+    assert.true(
+      result.includes('flowchart TD'),
+      'mermaid source is preserved in placeholder',
+    );
+    assert.false(
+      result.includes('data-code-language'),
+      'mermaid block does not use code language attribute',
+    );
+  });
+
+  // ── BFM Layer 3: Footnotes (marked-footnote) ──
+
+  test('markedSync renders footnotes', function (assert) {
+    const markdown =
+      'Statement with a footnote[^1].\n\n[^1]: This is the footnote.';
+    const result = markedSync(markdown);
+
+    assert.true(
+      result.includes('data-footnote-ref'),
+      'output contains footnote reference',
+    );
+    assert.true(
+      result.includes('This is the footnote.'),
+      'footnote content is rendered',
+    );
+  });
+
+  // ── BFM Layer 3: Extended Tables (marked-extended-tables) ──
+
+  test('markedSync renders tables with colspan', function (assert) {
+    const markdown = `
+| H1      | H2      | H3      |
+| ------- | ------- | ------- |
+| This spans three ||          |
+| A       | B       | C       |
+`;
+    const result = markedSync(markdown);
+
+    assert.true(
+      result.includes('<table>'),
+      'table is rendered',
+    );
+    assert.true(
+      result.includes('colspan'),
+      'colspan attribute is present',
+    );
+  });
+
+  // ── BFM Layer 3: Heading IDs (marked-gfm-heading-id) ──
+
+  test('markedSync adds id attributes to headings', function (assert) {
+    const markdown = '## My Section Title';
+    const result = markedSync(markdown);
+
+    assert.true(
+      result.includes('id="my-section-title"'),
+      'heading has a slug-based id attribute',
+    );
+  });
+
+  test('markdownToHtml preserves GFM alert markup through sanitization', function (assert) {
+    const markdown = '> [!NOTE]\n> Important info.';
+    const result = markdownToHtml(markdown);
+
+    assert.true(
+      result.includes('markdown-alert'),
+      'alert markup survives DOMPurify sanitization',
+    );
+  });
+
+  test('markdownToHtml preserves math placeholder through sanitization', function (assert) {
+    const markdown = 'Inline: $x^2$';
+    const result = markdownToHtml(markdown);
+
+    assert.true(
+      result.includes('math-placeholder'),
+      'math placeholder survives DOMPurify sanitization',
+    );
+    assert.true(
+      result.includes('data-math'),
+      'data-math attribute survives DOMPurify sanitization',
+    );
+  });
+
+  test('markdownToHtml preserves footnote markup through sanitization', function (assert) {
+    const markdown =
+      'Text[^1].\n\n[^1]: Footnote content.';
+    const result = markdownToHtml(markdown);
+
+    assert.true(
+      result.includes('Footnote content.'),
+      'footnote content survives DOMPurify sanitization',
+    );
+  });
+
+  test('markdownToHtml preserves heading IDs through sanitization', function (assert) {
+    const markdown = '## Test Heading';
+    const result = markdownToHtml(markdown);
+
+    assert.true(
+      result.includes('id="test-heading"'),
+      'heading ID survives DOMPurify sanitization',
+    );
+  });
 });
diff --git a/packages/runtime-common/bfm-math.ts b/packages/runtime-common/bfm-math.ts
new file mode 100644
index 00000000000..6ec7e3dd7ff
--- /dev/null
+++ b/packages/runtime-common/bfm-math.ts
@@ -0,0 +1,91 @@
+import { escapeHtml } from './helpers/html';
+import type { MarkedExtension, TokenizerAndRendererExtension } from 'marked';
+
+// Regex patterns adapted from marked-katex-extension.
+// Inline: $...$ or $$...$$ on one line, with standard spacing rules.
+const inlineRule =
+  /^(\${1,2})(?!\$)((?:\\.|[^\\\n])*?(?:\\.|[^\\\n$]))\1(?=[\s?!.,:\uFF1F\uFF01\u3002\uFF0C\uFF1A]|$)/;
+// Block: $$ on its own line, content, $$ on its own line.
+const blockRule = /^(\${1,2})\n((?:\\[^]|[^\\])+?)\n\1(?:\n|$)/;
+
+/**
+ * A marked extension that tokenizes LaTeX math (`$...$` inline, `$$...$$`
+ * block) and emits lightweight placeholder HTML instead of rendering with
+ * KaTeX at parse time. This keeps the heavy KaTeX library (~268 KB min) out
+ * of the initial bundle.
+ *
+ * Placeholders:
+ *   Inline:  <span class="math-placeholder" data-math="..." data-display="false">$...$</span>
+ *   Block:   <div  class="math-placeholder" data-math="..." data-display="true">$$...$$</div>
+ *
+ * A client-side modifier should query `.math-placeholder` elements, lazy-load
+ * KaTeX via `import('katex')`, and call `katex.render()` on each one.
+ */
+export function markedKatexPlaceholder(): MarkedExtension {
+  return {
+    extensions: [inlineKatex(), blockKatex()],
+  };
+}
+
+function inlineKatex(): TokenizerAndRendererExtension {
+  return {
+    name: 'inlineKatex',
+    level: 'inline',
+    start(src: string) {
+      let indexSrc = src;
+      while (indexSrc) {
+        let index = indexSrc.indexOf('$');
+        if (index === -1) return undefined;
+        if (index === 0 || indexSrc.charAt(index - 1) === ' ') {
+          let possibleKatex = indexSrc.substring(index);
+          if (possibleKatex.match(inlineRule)) {
+            return index;
+          }
+        }
+        indexSrc = indexSrc.substring(index + 1).replace(/^\$+/, '');
+      }
+      return undefined;
+    },
+    tokenizer(src: string) {
+      let match = src.match(inlineRule);
+      if (match) {
+        return {
+          type: 'inlineKatex',
+          raw: match[0],
+          text: match[2].trim(),
+          displayMode: match[1].length === 2,
+        };
+      }
+      return undefined;
+    },
+    renderer(token) {
+      let math = escapeHtml((token as any).text);
+      let raw = escapeHtml((token as any).raw);
+      return `<span class="math-placeholder" data-math="${math}" data-display="false">${raw}</span>`;
+    },
+  };
+}
+
+function blockKatex(): TokenizerAndRendererExtension {
+  return {
+    name: 'blockKatex',
+    level: 'block',
+    tokenizer(src: string) {
+      let match = src.match(blockRule);
+      if (match) {
+        return {
+          type: 'blockKatex',
+          raw: match[0],
+          text: match[2].trim(),
+          displayMode: match[1].length === 2,
+        };
+      }
+      return undefined;
+    },
+    renderer(token) {
+      let math = escapeHtml((token as any).text);
+      let raw = escapeHtml((token as any).raw);
+      return `<div class="math-placeholder" data-math="${math}" data-display="true">${raw}</div>\n`;
+    },
+  };
+}
diff --git a/packages/runtime-common/marked-sync.ts b/packages/runtime-common/marked-sync.ts
index e94fc1bd9b9..93b6f7ffd2f 100644
--- a/packages/runtime-common/marked-sync.ts
+++ b/packages/runtime-common/marked-sync.ts
@@ -2,6 +2,13 @@ import { marked } from 'marked';
 import { sanitizeHtml } from './dompurify-runtime';
 import { escapeHtml } from './helpers/html';
 import { bfmCardReferenceExtensions } from './bfm-card-references';
+import markedAlert from 'marked-alert';
+import markedFootnote from 'marked-footnote';
+import { markedKatexPlaceholder } from './bfm-math';
+// marked-extended-tables's ESM export isn't resolved by webpack; load via CJS.
+// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+const markedExtendedTables = require('marked-extended-tables/lib/index.cjs') as () => import('marked').MarkedExtension;
+import { gfmHeadingId } from 'marked-gfm-heading-id';
 import type * as _MonacoSDK from 'monaco-editor';
 type MonacoSDK = typeof _MonacoSDK;
 
@@ -9,6 +16,13 @@ type MonacoSDK = typeof _MonacoSDK;
 // not conflict with the per-call renderer override in markedSync().
 marked.use({ extensions: bfmCardReferenceExtensions() });
 
+// Register community marked extensions for BFM layers 3+ (GFM enhancements).
+marked.use(gfmHeadingId());
+marked.use(markedAlert());
+marked.use(markedFootnote());
+marked.use(markedExtendedTables());
+marked.use(markedKatexPlaceholder());
+
 const DECORATIVE_BULLET_PATTERN =
   // eslint-disable-next-line no-misleading-character-class -- match pictographic symbols plus a few geometric glyphs not covered by the Unicode class
   /(^|\n)(\s*)([\p{Extended_Pictographic}★•▪●❖✦✧◉◦◾◽⬢⬡☑✔☑️➤➔➜➡→])(\s+)/gu;
@@ -101,6 +115,11 @@ export function markedSync(
     .use({
       renderer: {
         code(code, language = '') {
+          // Mermaid blocks are rendered client-side; emit a placeholder.
+          if (language === 'mermaid') {
+            return `<pre class="mermaid">${escapeHtml(code)}</pre>\n`;
+          }
+
           let highlighted = renderWithMonaco(code, language, options);
           if (highlighted) {
             return highlighted;
diff --git a/packages/runtime-common/package.json b/packages/runtime-common/package.json
index c46bf5c79d4..907396a96f0 100644
--- a/packages/runtime-common/package.json
+++ b/packages/runtime-common/package.json
@@ -53,6 +53,10 @@
     "lodash": "catalog:",
     "loglevel": "catalog:",
     "marked": "catalog:",
+    "marked-alert": "catalog:",
+    "marked-extended-tables": "catalog:",
+    "marked-footnote": "catalog:",
+    "marked-gfm-heading-id": "catalog:",
     "matrix-js-sdk": "catalog:",
     "mime-types": "catalog:",
     "openai": "catalog:",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 67c9ab5e099..847b5ecbb95 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -498,6 +498,18 @@ catalogs:
     marked:
       specifier: ^12.0.1
       version: 12.0.2
+    marked-alert:
+      specifier: ^2.1.2
+      version: 2.1.2
+    marked-extended-tables:
+      specifier: ^2.0.1
+      version: 2.0.1
+    marked-footnote:
+      specifier: ^1.4.0
+      version: 1.4.0
+    marked-gfm-heading-id:
+      specifier: ^3.2.0
+      version: 3.2.0
     matrix-js-sdk:
       specifier: ^38.3.0
       version: 38.3.0
@@ -2791,6 +2803,18 @@ importers:
       marked:
         specifier: 'catalog:'
         version: 12.0.2
+      marked-alert:
+        specifier: 'catalog:'
+        version: 2.1.2(marked@12.0.2)
+      marked-extended-tables:
+        specifier: 'catalog:'
+        version: 2.0.1(marked@12.0.2)
+      marked-footnote:
+        specifier: 'catalog:'
+        version: 1.4.0(marked@12.0.2)
+      marked-gfm-heading-id:
+        specifier: 'catalog:'
+        version: 3.2.0(marked@12.0.2)
       matrix-js-sdk:
         specifier: 'catalog:'
         version: 38.3.0(patch_hash=0472d34281d936a5dcdacff67d2851d88c1df9593cd06b7725ee8414c12aa1d5)
@@ -9950,6 +9974,9 @@ packages:
   github-from-package@0.0.0:
     resolution: {integrity: sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==}
 
+  github-slugger@2.0.0:
+    resolution: {integrity: sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==}
+
   glimmer-scoped-css@0.8.1:
     resolution: {integrity: sha512-7n6kQr9+2yqMVWc1b04XlGQ1Eb4Ctq0FmPUVAeo/RhHU9De04zymEw4DI4fqZenLYF/AbnaDiLk9jrnv0kS/FA==}
 
@@ -11196,6 +11223,26 @@ packages:
   markdown-table@3.0.4:
     resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
 
+  marked-alert@2.1.2:
+    resolution: {integrity: sha512-EFNRZ08d8L/iEIPLTlQMDjvwIsj03gxWCczYTht6DCiHJIZhMk4NK5gtPY9UqAYb09eV5VGT+jD4lp396E0I+w==}
+    peerDependencies:
+      marked: '>=7.0.0'
+
+  marked-extended-tables@2.0.1:
+    resolution: {integrity: sha512-DV4Si978ZdaFbycIxzG4TdaNMtC0J8QfIKj1UOCejgJHwVjVJse8DNdJriWDeo/n74DWVYpRC6S56AdgWDPrPA==}
+    peerDependencies:
+      marked: '>=3 <16'
+
+  marked-footnote@1.4.0:
+    resolution: {integrity: sha512-fZTxAhI1TcLEs5UOjCfYfTHpyKGaWQevbxaGTEA68B51l7i87SctPFtHETYqPkEN0ka5opvy4Dy1l/yXVC+hmg==}
+    peerDependencies:
+      marked: '>=7.0.0'
+
+  marked-gfm-heading-id@3.2.0:
+    resolution: {integrity: sha512-Xfxpr5lXLDLY10XqzSCA9l2dDaiabQUgtYM9hw8yunyVsB/xYBRpiic6BOiY/EAJw1ik1eWr1ET1HKOAPZBhXg==}
+    peerDependencies:
+      marked: '>=4 <13'
+
   marked@12.0.2:
     resolution: {integrity: sha512-qXUm7e/YKFoqFPYPa3Ukg9xlI5cyAtGmyEIzMfW//m6kXwCy2Ps9DYf5ioijFKQ8qyuscrHoY04iJGctu2Kg0Q==}
     engines: {node: '>= 18'}
@@ -23496,6 +23543,8 @@ snapshots:
   github-from-package@0.0.0:
     optional: true
 
+  github-slugger@2.0.0: {}
+
   glimmer-scoped-css@0.8.1:
     dependencies:
       '@embroider/addon-shim': 1.10.2
@@ -24900,6 +24949,23 @@ snapshots:
 
   markdown-table@3.0.4: {}
 
+  marked-alert@2.1.2(marked@12.0.2):
+    dependencies:
+      marked: 12.0.2
+
+  marked-extended-tables@2.0.1(marked@12.0.2):
+    dependencies:
+      marked: 12.0.2
+
+  marked-footnote@1.4.0(marked@12.0.2):
+    dependencies:
+      marked: 12.0.2
+
+  marked-gfm-heading-id@3.2.0(marked@12.0.2):
+    dependencies:
+      github-slugger: 2.0.0
+      marked: 12.0.2
+
   marked@12.0.2: {}
 
   matcher-collection@1.1.2:
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 8f0c1031ea4..04cb97c5d71 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -182,6 +182,10 @@ catalog:
   macro-decorators: ^0.1.2
   magic-string: 0.25.9
   marked: ^12.0.1
+  marked-alert: ^2.1.2
+  marked-extended-tables: ^2.0.1
+  marked-footnote: ^1.4.0
+  marked-gfm-heading-id: ^3.2.0
   matrix-js-sdk: ^38.3.0
   mime-types: ^2.1.35
   moment: ^2.29.4

From e899c91da0c592984acd4d2f43e60773d084b31e Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 21:17:55 -0400
Subject: [PATCH 24/50] Update BFM card reference tests for heading ID
 extension

The gfmHeadingId extension now adds id attributes to headings,
so test assertions need to match the new output format.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/tests/unit/bfm-card-references-test.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 83accd5a2b3..c2868a19b9b 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -237,7 +237,7 @@ module('Unit | bfm-card-references', function () {
     test('markdown without card refs is unaffected', function (assert) {
       let markdown = '# Hello\n\nSome **bold** text.';
       let withBfm = markdownToHtml(markdown);
-      assert.true(withBfm.includes('<h1>Hello</h1>'));
+      assert.true(withBfm.includes('<h1 id="hello">Hello</h1>'));
       assert.true(withBfm.includes('<strong>bold</strong>'));
       assert.false(withBfm.includes('data-boxel-bfm'));
     });
@@ -274,7 +274,7 @@ module('Unit | bfm-card-references', function () {
         ),
         'has block ref',
       );
-      assert.true(html.includes('<h1>Title</h1>'), 'heading preserved');
+      assert.true(html.includes('<h1 id="title">Title</h1>'), 'heading preserved');
     });
   });
 });

From d26c6c659367ee4e2d2ea840551fd3650a36ecdf Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 21:31:24 -0400
Subject: [PATCH 25/50] Add Mermaid diagram client-side rendering (CS-10602)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lazy-load Mermaid.js (~2MB) to render diagram placeholders emitted by
the BFM markdown pipeline. Mermaid is never included in the initial
bundle — it's loaded on-demand only when pre.mermaid elements are
present in the rendered markdown.

Implementation:
- Add `mermaid` dependency to host package (webpack code-splits it)
- Register `__loadMermaid` global loader in application route (same
  pattern as Monaco)
- Add `renderMermaidDiagrams` modifier to markdown template that
  queries pre.mermaid elements, lazy-loads mermaid, and calls
  mermaid.run() with securityLevel: 'strict'
- Add CSS for rendered diagrams (transparent background, centered,
  responsive SVG sizing)
- Add acceptance test verifying mermaid code blocks render as SVG

On failure, the placeholder <pre> with raw diagram source remains
visible as readable fallback text.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  |  71 +-
 packages/host/app/routes/application.ts       |   7 +
 packages/host/package.json                    |   1 +
 .../acceptance/markdown-file-def-test.gts     |  34 +
 pnpm-lock.yaml                                | 878 +++++++++++++++++-
 pnpm-workspace.yaml                           |   1 +
 6 files changed, 987 insertions(+), 5 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 12a3e0cf741..7a2cb0cc7a9 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -191,9 +191,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
             ),
           )) {
             let url =
-              el.dataset.boxelBfmInlineRef ||
-              el.dataset.boxelBfmBlockRef ||
-              '';
+              el.dataset.boxelBfmInlineRef || el.dataset.boxelBfmBlockRef || '';
             if (
               !resolvedEls.has(el) &&
               el.childElementCount === 0 &&
@@ -258,12 +256,58 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     },
   );
 
+  renderMermaidDiagrams = modifier(
+    (element: HTMLElement, _positional: unknown[]) => {
+      let mermaidNodes =
+        element.querySelectorAll<HTMLPreElement>('pre.mermaid');
+      if (!mermaidNodes.length) {
+        return;
+      }
+
+      let cancelled = false;
+
+      let render = async () => {
+        let loadMermaid = (globalThis as any).__loadMermaid;
+        if (typeof loadMermaid !== 'function') {
+          return;
+        }
+        try {
+          let mermaid = await loadMermaid();
+          if (cancelled) return;
+
+          mermaid.initialize({
+            startOnLoad: false,
+            securityLevel: 'strict',
+            theme: 'default',
+          });
+
+          // mermaid.run() mutates the nodes in-place, replacing the <pre>
+          // text content with rendered SVG.
+          await mermaid.run({
+            nodes: Array.from(mermaidNodes),
+            suppressErrors: true,
+          });
+        } catch (error) {
+          console.error('[markdown] Mermaid rendering failed:', error);
+          // On failure the placeholder <pre> with source text remains visible.
+        }
+      };
+
+      scheduleOnce('afterRender', null, render);
+
+      return () => {
+        cancelled = true;
+      };
+    },
+  );
+
   getCardComponent = (card: BaseDef) => getComponent(card);
 
   <template>
     <div
       class='markdown-content'
       {{this.captureCardSlots this.renderedHtml @linkedCards}}
+      {{this.renderMermaidDiagrams this.renderedHtml}}
     >
       {{this.renderedHtml}}
     </div>
@@ -555,6 +599,27 @@ export default class MarkDownTemplate extends GlimmerComponent<{
           border-bottom: 1px solid var(--md-border);
         }
 
+        /* Mermaid diagrams */
+        .markdown-content :deep(pre.mermaid) {
+          background-color: transparent;
+          color: inherit;
+          text-align: center;
+          padding: var(--boxel-sp);
+          border-radius: var(--boxel-border-radius-xl);
+          overflow-x: auto;
+        }
+
+        .markdown-content :deep(pre.mermaid svg) {
+          max-width: 100%;
+          height: auto;
+        }
+
+        /* Mermaid error display */
+        .markdown-content :deep(pre.mermaid[data-processed='true'] .error-icon),
+        .markdown-content :deep(pre.mermaid #d .error-text) {
+          fill: var(--boxel-error-200, #b00020);
+        }
+
         /* BFM references (card, file, etc.) */
         .markdown-content :deep([data-boxel-bfm-inline-ref]) {
           display: inline;
diff --git a/packages/host/app/routes/application.ts b/packages/host/app/routes/application.ts
index 4df85f5507a..35e1be643b1 100644
--- a/packages/host/app/routes/application.ts
+++ b/packages/host/app/routes/application.ts
@@ -29,6 +29,12 @@ export default class Application extends Route {
         }
         return await route.monacoService.getMonacoContext();
       };
+      // Lazy-load Mermaid.js for diagram rendering in markdown content.
+      // The base package's markdown template calls this via globalThis.
+      (globalThis as any).__loadMermaid ??= async () => {
+        let mod = await import('mermaid');
+        return mod.default;
+      };
     }
   }
 
@@ -36,6 +42,7 @@ export default class Application extends Route {
     super.willDestroy?.();
     if (typeof globalThis !== 'undefined') {
       delete (globalThis as any).__loadMonacoForMarkdown;
+      delete (globalThis as any).__loadMermaid;
     }
   }
 }
diff --git a/packages/host/package.json b/packages/host/package.json
index cfbad04a24f..6a3f61ffaba 100644
--- a/packages/host/package.json
+++ b/packages/host/package.json
@@ -161,6 +161,7 @@
     "lodash": "catalog:",
     "loglevel": "catalog:",
     "matrix-js-sdk": "catalog:",
+    "mermaid": "catalog:",
     "moment": "catalog:",
     "moment-locales-webpack-plugin": "catalog:",
     "monaco-editor": "catalog:",
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index c320439e3e4..bd16ea08946 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -303,6 +303,16 @@ module('Acceptance | markdown BFM card references', function (hooks) {
             '',
             ':card[https://nonexistent.example/Card/missing]',
           ].join('\n'),
+          'mermaid-test.md': [
+            '# Mermaid Test',
+            '',
+            '```mermaid',
+            'flowchart TD',
+            '    A[Start] --> B{Decision}',
+            '    B -->|Yes| C[Result 1]',
+            '    B -->|No| D[Result 2]',
+            '```',
+          ].join('\n'),
         },
       }),
     );
@@ -539,4 +549,28 @@ module('Acceptance | markdown BFM card references', function (hooks) {
       )
       .exists('clicking a block markdown card reference opens the target card');
   });
+
+  test('mermaid code blocks are rendered as SVG diagrams', async function (assert) {
+    await visitOperatorMode({
+      submode: 'code',
+      codePath: `${testRealmURL}mermaid-test.md`,
+    });
+
+    // Wait for mermaid to lazy-load and render the diagram into an SVG.
+    await waitUntil(() => document.querySelector('pre.mermaid svg') !== null, {
+      timeout: 15000,
+      timeoutMessage: 'Mermaid diagram was not rendered as SVG within timeout',
+    });
+
+    assert
+      .dom('pre.mermaid svg')
+      .exists('mermaid code block is rendered as an SVG diagram');
+
+    assert
+      .dom('pre.mermaid')
+      .doesNotIncludeText(
+        'flowchart TD',
+        'raw mermaid source is replaced by rendered SVG',
+      );
+  });
 });
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 847b5ecbb95..a123919cfe3 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -513,6 +513,9 @@ catalogs:
     matrix-js-sdk:
       specifier: ^38.3.0
       version: 38.3.0
+    mermaid:
+      specifier: ^11.14.0
+      version: 11.14.0
     mime-types:
       specifier: ^2.1.35
       version: 2.1.35
@@ -2180,6 +2183,9 @@ importers:
       matrix-js-sdk:
         specifier: 'catalog:'
         version: 38.3.0(patch_hash=0472d34281d936a5dcdacff67d2851d88c1df9593cd06b7725ee8414c12aa1d5)
+      mermaid:
+        specifier: 'catalog:'
+        version: 11.14.0
       moment:
         specifier: 'catalog:'
         version: 2.30.1
@@ -3135,6 +3141,9 @@ packages:
   '@adraffy/ens-normalize@1.10.1':
     resolution: {integrity: sha512-96Z2IP3mYmF1Xg2cDm8f1gWGf/HUVedQ3FMifV4kG/PQ4yEP51xDtRAEfhVNt5f/uzpNkZHwWQuUcu6D6K+Ekw==}
 
+  '@antfu/install-pkg@1.1.0':
+    resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==}
+
   '@asamuzakjp/css-color@3.2.0':
     resolution: {integrity: sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw==}
 
@@ -3807,6 +3816,9 @@ packages:
     resolution: {integrity: sha512-0ZrskXVEHSWIqZM/sQZ4EV3jZJXRkio/WCxaqKZP1g//CEWEPSfeZFcms4XeKBCHU0ZKnIkdJeU/kF+eRp5lBg==}
     engines: {node: '>=6.9.0'}
 
+  '@braintree/sanitize-url@7.1.2':
+    resolution: {integrity: sha512-jigsZK+sMF/cuiB7sERuo9V7N9jx+dhmHHnQyDSVdpZwVutaBu7WvNYqMDLSgFgfB30n452TP3vjDAvFC973mA==}
+
   '@cardstack/logger@0.2.1':
     resolution: {integrity: sha512-xT8NWm9OYz15Qf7U/y9EQmCiGgZMTJaUbmyh/RxfMupmnBaM/KHMSI1iRuJa2mJ5crY5rcO3rzth+nVk34+jag==}
     engines: {node: '>= 8'}
@@ -3819,6 +3831,21 @@ packages:
     peerDependencies:
       ember-modifier: ^4.1.0
 
+  '@chevrotain/cst-dts-gen@11.1.2':
+    resolution: {integrity: sha512-XTsjvDVB5nDZBQB8o0o/0ozNelQtn2KrUVteIHSlPd2VAV2utEb6JzyCJaJ8tGxACR4RiBNWy5uYUHX2eji88Q==}
+
+  '@chevrotain/gast@11.1.2':
+    resolution: {integrity: sha512-Z9zfXR5jNZb1Hlsd/p+4XWeUFugrHirq36bKzPWDSIacV+GPSVXdk+ahVWZTwjhNwofAWg/sZg58fyucKSQx5g==}
+
+  '@chevrotain/regexp-to-ast@11.1.2':
+    resolution: {integrity: sha512-nMU3Uj8naWer7xpZTYJdxbAs6RIv/dxYzkYU8GSwgUtcAAlzjcPfX1w+RKRcYG8POlzMeayOQ/znfwxEGo5ulw==}
+
+  '@chevrotain/types@11.1.2':
+    resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
+
+  '@chevrotain/utils@11.1.2':
+    resolution: {integrity: sha512-4mudFAQ6H+MqBTfqLmU7G1ZwRzCLfJEooL/fsF6rCX5eePMbGhoy5n4g+G4vlh2muDcsCTJtL+uKbOzWxs5LHA==}
+
   '@cnakazawa/watch@1.0.4':
     resolution: {integrity: sha512-v9kIhKwjeZThiWrLmj0y17CWoyddASLj9O2yvbZkbvw/N3rWOYy9zkV66ursAoVr0mV15bL8g0c4QZUE6cdDoQ==}
     engines: {node: '>=0.1.95'}
@@ -4957,6 +4984,12 @@ packages:
     resolution: {integrity: sha512-93zYdMES/c1D69yZiKDBj0V24vqNzB/koF26KPaagAfd3P/4gUlh3Dys5ogAK+Exi9QyzlD8x/08Zt7wIKcDcA==}
     deprecated: Use @eslint/object-schema instead
 
+  '@iconify/types@2.0.0':
+    resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==}
+
+  '@iconify/utils@3.1.0':
+    resolution: {integrity: sha512-Zlzem1ZXhI1iHeeERabLNzBHdOa4VhQbqAcOQaMKuTuyZCpwKbC2R4Dd0Zo3g9EAc+Y4fiarO8HIHRAth7+skw==}
+
   '@inquirer/ansi@2.0.4':
     resolution: {integrity: sha512-DpcZrQObd7S0R/U3bFdkcT5ebRwbTTC4D3tCc1vsJizmgPLxNJBo+AAFmrZwe8zk30P2QzgzGWZ3Q9uJwWuhIg==}
     engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
@@ -5176,6 +5209,9 @@ packages:
     resolution: {integrity: sha512-QyxHvncvkl7nf+tnn92PjQ54gMNV8hMSpiukiDgNrqF6IYwgySTlcSdkPYdw8QjZJ0NR6fnVrNzMec0OohM3wA==}
     engines: {node: '>= 18'}
 
+  '@mermaid-js/parser@1.1.0':
+    resolution: {integrity: sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==}
+
   '@nicolo-ribaudo/eslint-scope-5-internals@5.1.1-v1':
     resolution: {integrity: sha512-54/JRvkLIzzDWshCWfuhadfrfZVPiElY8Fcgmg1HroEly/EDSszzhBAsarCux+D/kOslTRquNzuyGSmUSTTHGg==}
 
@@ -6052,6 +6088,99 @@ packages:
   '@types/cors@2.8.19':
     resolution: {integrity: sha512-mFNylyeyqN93lfe/9CSxOGREz8cpzAhH+E93xJ4xWQf62V8sQ/24reV2nyzUWM6H6Xji+GGHpkbLe7pVoUEskg==}
 
+  '@types/d3-array@3.2.2':
+    resolution: {integrity: sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==}
+
+  '@types/d3-axis@3.0.6':
+    resolution: {integrity: sha512-pYeijfZuBd87T0hGn0FO1vQ/cgLk6E1ALJjfkC0oJ8cbwkZl3TpgS8bVBLZN+2jjGgg38epgxb2zmoGtSfvgMw==}
+
+  '@types/d3-brush@3.0.6':
+    resolution: {integrity: sha512-nH60IZNNxEcrh6L1ZSMNA28rj27ut/2ZmI3r96Zd+1jrZD++zD3LsMIjWlvg4AYrHn/Pqz4CF3veCxGjtbqt7A==}
+
+  '@types/d3-chord@3.0.6':
+    resolution: {integrity: sha512-LFYWWd8nwfwEmTZG9PfQxd17HbNPksHBiJHaKuY1XeqscXacsS2tyoo6OdRsjf+NQYeB6XrNL3a25E3gH69lcg==}
+
+  '@types/d3-color@3.1.3':
+    resolution: {integrity: sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==}
+
+  '@types/d3-contour@3.0.6':
+    resolution: {integrity: sha512-BjzLgXGnCWjUSYGfH1cpdo41/hgdWETu4YxpezoztawmqsvCeep+8QGfiY6YbDvfgHz/DkjeIkkZVJavB4a3rg==}
+
+  '@types/d3-delaunay@6.0.4':
+    resolution: {integrity: sha512-ZMaSKu4THYCU6sV64Lhg6qjf1orxBthaC161plr5KuPHo3CNm8DTHiLw/5Eq2b6TsNP0W0iJrUOFscY6Q450Hw==}
+
+  '@types/d3-dispatch@3.0.7':
+    resolution: {integrity: sha512-5o9OIAdKkhN1QItV2oqaE5KMIiXAvDWBDPrD85e58Qlz1c1kI/J0NcqbEG88CoTwJrYe7ntUCVfeUl2UJKbWgA==}
+
+  '@types/d3-drag@3.0.7':
+    resolution: {integrity: sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==}
+
+  '@types/d3-dsv@3.0.7':
+    resolution: {integrity: sha512-n6QBF9/+XASqcKK6waudgL0pf/S5XHPPI8APyMLLUHd8NqouBGLsU8MgtO7NINGtPBtk9Kko/W4ea0oAspwh9g==}
+
+  '@types/d3-ease@3.0.2':
+    resolution: {integrity: sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==}
+
+  '@types/d3-fetch@3.0.7':
+    resolution: {integrity: sha512-fTAfNmxSb9SOWNB9IoG5c8Hg6R+AzUHDRlsXsDZsNp6sxAEOP0tkP3gKkNSO/qmHPoBFTxNrjDprVHDQDvo5aA==}
+
+  '@types/d3-force@3.0.10':
+    resolution: {integrity: sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==}
+
+  '@types/d3-format@3.0.4':
+    resolution: {integrity: sha512-fALi2aI6shfg7vM5KiR1wNJnZ7r6UuggVqtDA+xiEdPZQwy/trcQaHnwShLuLdta2rTymCNpxYTiMZX/e09F4g==}
+
+  '@types/d3-geo@3.1.0':
+    resolution: {integrity: sha512-856sckF0oP/diXtS4jNsiQw/UuK5fQG8l/a9VVLeSouf1/PPbBE1i1W852zVwKwYCBkFJJB7nCFTbk6UMEXBOQ==}
+
+  '@types/d3-hierarchy@3.1.7':
+    resolution: {integrity: sha512-tJFtNoYBtRtkNysX1Xq4sxtjK8YgoWUNpIiUee0/jHGRwqvzYxkq0hGVbbOGSz+JgFxxRu4K8nb3YpG3CMARtg==}
+
+  '@types/d3-interpolate@3.0.4':
+    resolution: {integrity: sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==}
+
+  '@types/d3-path@3.1.1':
+    resolution: {integrity: sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg==}
+
+  '@types/d3-polygon@3.0.2':
+    resolution: {integrity: sha512-ZuWOtMaHCkN9xoeEMr1ubW2nGWsp4nIql+OPQRstu4ypeZ+zk3YKqQT0CXVe/PYqrKpZAi+J9mTs05TKwjXSRA==}
+
+  '@types/d3-quadtree@3.0.6':
+    resolution: {integrity: sha512-oUzyO1/Zm6rsxKRHA1vH0NEDG58HrT5icx/azi9MF1TWdtttWl0UIUsjEQBBh+SIkrpd21ZjEv7ptxWys1ncsg==}
+
+  '@types/d3-random@3.0.3':
+    resolution: {integrity: sha512-Imagg1vJ3y76Y2ea0871wpabqp613+8/r0mCLEBfdtqC7xMSfj9idOnmBYyMoULfHePJyxMAw3nWhJxzc+LFwQ==}
+
+  '@types/d3-scale-chromatic@3.1.0':
+    resolution: {integrity: sha512-iWMJgwkK7yTRmWqRB5plb1kadXyQ5Sj8V/zYlFGMUBbIPKQScw+Dku9cAAMgJG+z5GYDoMjWGLVOvjghDEFnKQ==}
+
+  '@types/d3-scale@4.0.9':
+    resolution: {integrity: sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==}
+
+  '@types/d3-selection@3.0.11':
+    resolution: {integrity: sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==}
+
+  '@types/d3-shape@3.1.8':
+    resolution: {integrity: sha512-lae0iWfcDeR7qt7rA88BNiqdvPS5pFVPpo5OfjElwNaT2yyekbM0C9vK+yqBqEmHr6lDkRnYNoTBYlAgJa7a4w==}
+
+  '@types/d3-time-format@4.0.3':
+    resolution: {integrity: sha512-5xg9rC+wWL8kdDj153qZcsJ0FWiFt0J5RB6LYUNZjwSnesfblqrI/bJ1wBdJ8OQfncgbJG5+2F+qfqnqyzYxyg==}
+
+  '@types/d3-time@3.0.4':
+    resolution: {integrity: sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==}
+
+  '@types/d3-timer@3.0.2':
+    resolution: {integrity: sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==}
+
+  '@types/d3-transition@3.0.9':
+    resolution: {integrity: sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==}
+
+  '@types/d3-zoom@3.0.8':
+    resolution: {integrity: sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==}
+
+  '@types/d3@7.4.3':
+    resolution: {integrity: sha512-lZXZ9ckh5R8uiFVt8ogUNf+pIrK4EsWrx2Np75WvF/eTpJ0FMHNhjXk8CKEx/+gpHbNQyJWehbFaTvqmHWB3ww==}
+
   '@types/debug@4.1.12':
     resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==}
 
@@ -6098,6 +6227,9 @@ packages:
   '@types/fs-extra@8.1.5':
     resolution: {integrity: sha512-0dzKcwO+S8s2kuF5Z9oUWatQJj5Uq/iqphEtE3GQJVRRYm/tD1LglU2UnXi2A8jLq5umkGouOXOR9y0n613ZwQ==}
 
+  '@types/geojson@7946.0.16':
+    resolution: {integrity: sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==}
+
   '@types/glob@7.2.0':
     resolution: {integrity: sha512-ZUxbzKl0IfJILTS6t7ip5fQQM/J3TJYubDm3nMbgubNNYS62eXeUpoLUC8/7fJNiFYHTrGPQn7hspDUzIHX3UA==}
 
@@ -6442,6 +6574,9 @@ packages:
       ember-source: '>= 3.28'
       qunit: ^2.20.1
 
+  '@upsetjs/venn.js@2.0.0':
+    resolution: {integrity: sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==}
+
   '@vitest/expect@2.1.9':
     resolution: {integrity: sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw==}
 
@@ -6655,6 +6790,11 @@ packages:
     engines: {node: '>=0.4.0'}
     hasBin: true
 
+  acorn@8.16.0:
+    resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
   aes-js@4.0.0-beta.5:
     resolution: {integrity: sha512-G965FqalsNyrPqgEGON7nIx1e/OVENSgiEIzyC63haUMuvNnwIgIjMs52hlTCKhkBny7A2ORNlfY9Zu+jmGk1Q==}
 
@@ -7609,6 +7749,14 @@ packages:
   chess.js@1.0.0-beta.8:
     resolution: {integrity: sha512-UngzUMXmexcQaQA/UEJuJj5vatEy34awYMD5YMOp/FW3HM7lqspp7ymYs5JAmquDq0WROtURRfSffoa/vrCCyw==}
 
+  chevrotain-allstar@0.3.1:
+    resolution: {integrity: sha512-b7g+y9A0v4mxCW1qUhf3BSVPg+/NvGErk/dOkrDaHA0nQIQGAtrOjlX//9OQtRlSCy+x9rfB5N8yC71lH1nvMw==}
+    peerDependencies:
+      chevrotain: ^11.0.0
+
+  chevrotain@11.1.2:
+    resolution: {integrity: sha512-opLQzEVriiH1uUQ4Kctsd49bRoFDXGGSC4GUqj7pGyxM3RehRhvTlZJc1FL/Flew2p5uwxa1tUDWKzI4wNM8pg==}
+
   chownr@1.1.4:
     resolution: {integrity: sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==}
 
@@ -7829,6 +7977,9 @@ packages:
     engines: {node: ^14.13.0 || >=16.0.0}
     hasBin: true
 
+  confbox@0.1.8:
+    resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==}
+
   configstore@5.0.1:
     resolution: {integrity: sha512-aMKprgk5YhBNyH25hj8wGt2+D52Sw1DRRIzqBwLp2Ya9mFmY8KPvvtvmna8SxVR9JMZ4kzMD68N22vlaRpkeFA==}
     engines: {node: '>=8'}
@@ -8101,6 +8252,12 @@ packages:
     resolution: {integrity: sha512-utCYNzRSQIZNPIcGZdQc92UVJYAhtGAteCFg0yRaFm8f0P+CPtyGyHXJcGXnffjCybUCEx3FQ2G7U3/o9eIkVQ==}
     engines: {node: '>= 0.4.0'}
 
+  cose-base@1.0.3:
+    resolution: {integrity: sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==}
+
+  cose-base@2.2.0:
+    resolution: {integrity: sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==}
+
   cosmiconfig@8.3.6:
     resolution: {integrity: sha512-kcZ6+W5QzcJ3P1Mt+83OUv/oHFqZHIx8DuxG6eZ5RGMERoLqp4BuGjhHLYGK+Kf5XVkQvqBSmAy/nGWN3qDgEA==}
     engines: {node: '>=14'}
@@ -8215,9 +8372,165 @@ packages:
   csstype@3.2.3:
     resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
 
+  cytoscape-cose-bilkent@4.1.0:
+    resolution: {integrity: sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape-fcose@2.2.0:
+    resolution: {integrity: sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape@3.33.1:
+    resolution: {integrity: sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==}
+    engines: {node: '>=0.10'}
+
+  d3-array@2.12.1:
+    resolution: {integrity: sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==}
+
+  d3-array@3.2.4:
+    resolution: {integrity: sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==}
+    engines: {node: '>=12'}
+
+  d3-axis@3.0.0:
+    resolution: {integrity: sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==}
+    engines: {node: '>=12'}
+
+  d3-brush@3.0.0:
+    resolution: {integrity: sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==}
+    engines: {node: '>=12'}
+
+  d3-chord@3.0.1:
+    resolution: {integrity: sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==}
+    engines: {node: '>=12'}
+
+  d3-color@3.1.0:
+    resolution: {integrity: sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==}
+    engines: {node: '>=12'}
+
+  d3-contour@4.0.2:
+    resolution: {integrity: sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==}
+    engines: {node: '>=12'}
+
+  d3-delaunay@6.0.4:
+    resolution: {integrity: sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==}
+    engines: {node: '>=12'}
+
+  d3-dispatch@3.0.1:
+    resolution: {integrity: sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==}
+    engines: {node: '>=12'}
+
+  d3-drag@3.0.0:
+    resolution: {integrity: sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==}
+    engines: {node: '>=12'}
+
+  d3-dsv@3.0.1:
+    resolution: {integrity: sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==}
+    engines: {node: '>=12'}
+    hasBin: true
+
+  d3-ease@3.0.1:
+    resolution: {integrity: sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==}
+    engines: {node: '>=12'}
+
+  d3-fetch@3.0.1:
+    resolution: {integrity: sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==}
+    engines: {node: '>=12'}
+
+  d3-force@3.0.0:
+    resolution: {integrity: sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==}
+    engines: {node: '>=12'}
+
+  d3-format@3.1.2:
+    resolution: {integrity: sha512-AJDdYOdnyRDV5b6ArilzCPPwc1ejkHcoyFarqlPqT7zRYjhavcT3uSrqcMvsgh2CgoPbK3RCwyHaVyxYcP2Arg==}
+    engines: {node: '>=12'}
+
+  d3-geo@3.1.1:
+    resolution: {integrity: sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q==}
+    engines: {node: '>=12'}
+
+  d3-hierarchy@3.1.2:
+    resolution: {integrity: sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==}
+    engines: {node: '>=12'}
+
+  d3-interpolate@3.0.1:
+    resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
+    engines: {node: '>=12'}
+
+  d3-path@1.0.9:
+    resolution: {integrity: sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==}
+
+  d3-path@3.1.0:
+    resolution: {integrity: sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==}
+    engines: {node: '>=12'}
+
+  d3-polygon@3.0.1:
+    resolution: {integrity: sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==}
+    engines: {node: '>=12'}
+
+  d3-quadtree@3.0.1:
+    resolution: {integrity: sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==}
+    engines: {node: '>=12'}
+
+  d3-random@3.0.1:
+    resolution: {integrity: sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==}
+    engines: {node: '>=12'}
+
+  d3-sankey@0.12.3:
+    resolution: {integrity: sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ==}
+
+  d3-scale-chromatic@3.1.0:
+    resolution: {integrity: sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ==}
+    engines: {node: '>=12'}
+
+  d3-scale@4.0.2:
+    resolution: {integrity: sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==}
+    engines: {node: '>=12'}
+
+  d3-selection@3.0.0:
+    resolution: {integrity: sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==}
+    engines: {node: '>=12'}
+
+  d3-shape@1.3.7:
+    resolution: {integrity: sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==}
+
+  d3-shape@3.2.0:
+    resolution: {integrity: sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==}
+    engines: {node: '>=12'}
+
+  d3-time-format@4.1.0:
+    resolution: {integrity: sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==}
+    engines: {node: '>=12'}
+
+  d3-time@3.1.0:
+    resolution: {integrity: sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==}
+    engines: {node: '>=12'}
+
+  d3-timer@3.0.1:
+    resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
+    engines: {node: '>=12'}
+
+  d3-transition@3.0.1:
+    resolution: {integrity: sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      d3-selection: 2 - 3
+
+  d3-zoom@3.0.0:
+    resolution: {integrity: sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==}
+    engines: {node: '>=12'}
+
+  d3@7.9.0:
+    resolution: {integrity: sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==}
+    engines: {node: '>=12'}
+
   dag-map@2.0.2:
     resolution: {integrity: sha512-xnsprIzYuDeiyu5zSKwilV/ajRHxnoMlAhEREfyfTgTSViMVY2fGP1ZcHJbtwup26oCkofySU/m6oKJ3HrkW7w==}
 
+  dagre-d3-es@7.0.14:
+    resolution: {integrity: sha512-P4rFMVq9ESWqmOgK+dlXvOtLwYg0i7u0HBGJER0LZDJT2VHIPAMZ/riPxqJceWMStH5+E61QxFra9kIS3AqdMg==}
+
   data-uri-to-buffer@3.0.1:
     resolution: {integrity: sha512-WboRycPNsVw3B3TL559F7kuBUM4d8CgMEvk6xEJlOp7OBPjt6G7z8WMWlD2rOFZLk6OYfFIUGsCOWzcQH9K2og==}
     engines: {node: '>= 6'}
@@ -8388,6 +8701,9 @@ packages:
     resolution: {integrity: sha512-ua8BhapfP0JUJKC/zV9yHHDW/rDoDxP4Zhn3AkA6/xT6gY7jYXJiaeyBZznYVujhZZET+UgcbZiQ7sN3WqcImg==}
     engines: {node: '>=10'}
 
+  delaunator@5.1.0:
+    resolution: {integrity: sha512-AGrQ4QSgssa1NGmWmLPqN5NY2KajF5MqxetNEO+o0n3ZwZZeTmt7bBnvzHWrmkZFxGgr4HdyFgelzgi06otLuQ==}
+
   delayed-stream@1.0.0:
     resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
     engines: {node: '>=0.4.0'}
@@ -10021,7 +10337,7 @@ packages:
   glob@8.1.0:
     resolution: {integrity: sha512-r8hpEjiQEYlF2QU0df3dS+nxxSIreXQS1qRhMJM0Q5NDdR386C7jb7Hwwod8Fgiuex+k0GFjgft18yvxm5XoCQ==}
     engines: {node: '>=12'}
-    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+    deprecated: Glob versions prior to v9 are no longer supported
 
   glob@9.3.5:
     resolution: {integrity: sha512-e1LleDykUz2Iu+MTYdkSsuWX8lvAjAcs0Xef0lNIu0S2wOAzuTxCJtcd9S3cijlwYF18EsU3rzb8jPVobxDh9Q==}
@@ -10091,6 +10407,9 @@ packages:
   growly@1.3.0:
     resolution: {integrity: sha512-+xGQY0YyAWCnqy7Cd++hc2JqMYzlm0dG30Jd0beaA64sROr8C4nt8Yc9V5Ro3avlSUDTN0ulqP/VBKi1/lLygw==}
 
+  hachure-fill@0.5.2:
+    resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
+
   handlebars@4.7.8:
     resolution: {integrity: sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==}
     engines: {node: '>=0.4.7'}
@@ -10427,6 +10746,13 @@ packages:
     resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
     engines: {node: '>= 0.4'}
 
+  internmap@1.0.1:
+    resolution: {integrity: sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==}
+
+  internmap@2.0.3:
+    resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
+    engines: {node: '>=12'}
+
   invert-kv@3.0.1:
     resolution: {integrity: sha512-CYdFeFexxhv/Bcny+Q0BfOV+ltRlJcd4BBZBYFX/O0u4npJrgZtIcjokegtiSMAvlMTJ+Koq0GBCc//3bueQxw==}
     engines: {node: '>=8'}
@@ -10910,6 +11236,10 @@ packages:
     resolution: {integrity: sha512-+KJGIyHgkGuIq3IEBNftfhW/LfWhXUIY6OmyVWjliu5KH1y0fw7VQ8YndE2O4qZdMSd9SqbnC8GOcZEy0Om7sA==}
     engines: {node: '>=18'}
 
+  katex@0.16.44:
+    resolution: {integrity: sha512-EkxoDTk8ufHqHlf9QxGwcxeLkWRR3iOuYfRpfORgYfqc8s13bgb+YtRY59NK5ZpRaCwq1kqA6a5lpX8C/eLphQ==}
+    hasBin: true
+
   keygrip@1.1.0:
     resolution: {integrity: sha512-iYSchDJ+liQ8iwbSI2QqsQOvqv58eJCEanyJPJi+Khyu8smkcKSFUCbPwzFcL7YVtZ6eONjqRX/38caJ7QjRAQ==}
     engines: {node: '>= 0.6'}
@@ -10923,6 +11253,9 @@ packages:
   keyv@4.5.4:
     resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
 
+  khroma@2.1.0:
+    resolution: {integrity: sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw==}
+
   kind-of@3.2.2:
     resolution: {integrity: sha512-NOW9QQXMoZGg/oqnVNoNTTIFEIid1627WCffUBJEdMxYApq7mNE7CpzucIPc+ZQg25Phej7IJSmX3hO+oblOtQ==}
     engines: {node: '>=0.10.0'}
@@ -10951,6 +11284,16 @@ packages:
     resolution: {integrity: sha512-zPPuIt+ku1iCpFBRwseMcPYQ1cJL8l60rSmKeOuGfOXyE6YnTBmf2aEFNL2HQGrD0cPcLO/t+v9RTgC+fwEh/g==}
     engines: {node: ^4.8.4 || ^6.10.1 || ^7.10.1 || >= 8.1.4}
 
+  langium@4.2.1:
+    resolution: {integrity: sha512-zu9QWmjpzJcomzdJQAHgDVhLGq5bLosVak1KVa40NzQHXfqr4eAHupvnPOVXEoLkg6Ocefvf/93d//SB7du4YQ==}
+    engines: {node: '>=20.10.0', npm: '>=10.2.3'}
+
+  layout-base@1.0.2:
+    resolution: {integrity: sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==}
+
+  layout-base@2.0.1:
+    resolution: {integrity: sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==}
+
   lazy-ass@1.6.0:
     resolution: {integrity: sha512-cc8oEVoctTvsFZ/Oje/kGnHbpWHYBe8IAJe4C0QNc3t8uM/0Y8+erSz/7Y1ALuXTEZTMvxXwO6YbX1ey3ujiZw==}
     engines: {node: '> 0.8'}
@@ -11029,6 +11372,12 @@ packages:
     resolution: {integrity: sha512-XT9ewWAC43tiAV7xDAPflMkG0qOPn2QjHqlgX8FOqmWa/rxnyYDulF9T0F7tRy1u+TVTmK/M//6VIOye+2zDXg==}
     engines: {node: '>=20'}
 
+  lodash-es@4.17.23:
+    resolution: {integrity: sha512-kVI48u3PZr38HdYz98UmfPnXl2DXrpdctLrFLCd3kOx1xUkOmpFPx7gCWWM5MPkL/fD8zb+Ph0QzjGFs4+hHWg==}
+
+  lodash-es@4.18.1:
+    resolution: {integrity: sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==}
+
   lodash._baseflatten@3.1.4:
     resolution: {integrity: sha512-fESngZd+X4k+GbTxdMutf8ohQa0s3sJEHIcwtu4/LsIQ2JTDzdRxDCMQjW+ezzwRitLmHnacVVmosCbxifefbw==}
 
@@ -11248,6 +11597,11 @@ packages:
     engines: {node: '>= 18'}
     hasBin: true
 
+  marked@16.4.2:
+    resolution: {integrity: sha512-TI3V8YYWvkVf3KJe1dRkpnjs68JUPyEa5vjKrp1XEEJUAOaQc+Qj+L1qWbPd0SJuAdQkFU0h73sXXqwDYxsiDA==}
+    engines: {node: '>= 20'}
+    hasBin: true
+
   matcher-collection@1.1.2:
     resolution: {integrity: sha512-YQ/teqaOIIfUHedRam08PB3NK7Mjct6BvzRnJmpGDm8uFXpNr1sbY4yuflI5JcEs6COpYA0FpRQhSDBf1tT95g==}
 
@@ -11343,6 +11697,9 @@ packages:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
+  mermaid@11.14.0:
+    resolution: {integrity: sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==}
+
   methods@1.1.2:
     resolution: {integrity: sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==}
     engines: {node: '>= 0.6'}
@@ -11513,6 +11870,9 @@ packages:
     resolution: {integrity: sha512-Q9wJ/xhzeD9Wua1MwDN2v3ah3HENsUVSlzzL9Qw149cL9hHZkXtQGl3Eq36BbdLV+/qUwaP1WtJQ+H/+Oxso8g==}
     engines: {node: 20 || 22 || 24}
 
+  mlly@1.8.2:
+    resolution: {integrity: sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==}
+
   module-details-from-path@1.0.4:
     resolution: {integrity: sha512-EGWKgxALGMgzvxYF1UyGTy0HXX/2vHLkw6+NvDKW2jypWbHpjQuj4UMcqQWXHERJhVGKikolT06G3bcKe4fi7w==}
 
@@ -11961,6 +12321,9 @@ packages:
     resolution: {integrity: sha512-k3bdm2n25tkyxcjSKzB5x8kfVxlMdgsbPr0GkZcwHsLpba6cBjqCt1KlcChKEvxHIcTB1FVMuwoijZ26xex5MQ==}
     engines: {node: '>=8'}
 
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
   pako@2.1.0:
     resolution: {integrity: sha512-w+eufiZ1WuJYgPXbV/PO3NCMEc3xqylkKHzp8bxp1uW4qaSNQUkwmLLEc3kKsfz8lpV1F8Ht3U1Cm+9Srog2ug==}
 
@@ -12024,6 +12387,9 @@ packages:
   path-browserify@1.0.1:
     resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
 
+  path-data-parser@0.1.0:
+    resolution: {integrity: sha512-NOnmBpt5Y2RWbuv0LMzsayp3lVylAHLPUTut412ZA3l+C4uw4ZVkQbjShYCQ8TCpUMdPapr4YjUqLYD6v68j+w==}
+
   path-exists@3.0.0:
     resolution: {integrity: sha512-bpC7GYwiDYQ4wYLe+FA8lhRjhQCMcQGuSgGGqDkg/QerRWw9CmGRT0iSOVRSZJ29NMLZgIzqaljJ63oaL4NIJQ==}
     engines: {node: '>=4'}
@@ -12115,6 +12481,9 @@ packages:
   pathe@1.1.2:
     resolution: {integrity: sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==}
 
+  pathe@2.0.3:
+    resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
+
   pathval@2.0.1:
     resolution: {integrity: sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==}
     engines: {node: '>= 14.16'}
@@ -12194,6 +12563,9 @@ packages:
   pkg-entry-points@1.1.1:
     resolution: {integrity: sha512-BhZa7iaPmB4b3vKIACoppyUoYn8/sFs17VJJtzrzPZvEnN2nqrgg911tdL65lA2m1ml6UI3iPeYbZQ4VXpn1mA==}
 
+  pkg-types@1.3.1:
+    resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
+
   pkg-up@2.0.0:
     resolution: {integrity: sha512-fjAPuiws93rm7mPUu21RdBnkeZNrbfCFCwfAhPWY+rR3zG0ubpe5cEReHOw5fIbfmsxEV/g2kSxGTATY3Bpnwg==}
     engines: {node: '>=4'}
@@ -12219,6 +12591,12 @@ packages:
     resolution: {integrity: sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==}
     engines: {node: '>=4'}
 
+  points-on-curve@0.2.0:
+    resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
+
+  points-on-path@0.2.1:
+    resolution: {integrity: sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==}
+
   portfinder@1.0.38:
     resolution: {integrity: sha512-rEwq/ZHlJIKw++XtLAO8PPuOQA/zaPJOZJ37BVuN97nLpMJeuDVLVGRwbFoBgLudgdTMP2hdRJP++H+8QOA3vg==}
     engines: {node: '>= 10.12'}
@@ -12769,6 +13147,9 @@ packages:
     resolution: {integrity: sha512-5Di9UC0+8h1L6ZD2d7awM7E/T4uA1fJRlx6zk/NvdCCVEoAnFqvHmCuNeIKoCeIixBX/q8uM+6ycDvF8woqosA==}
     engines: {node: '>= 0.8'}
 
+  robust-predicates@3.0.3:
+    resolution: {integrity: sha512-NS3levdsRIUOmiJ8FZWCP7LG3QpJyrs/TE0Zpf1yvZu8cAJJ6QMW92H1c7kWpdIHo8RvmLxN/o2JXTKHp74lUA==}
+
   rollup-plugin-copy-assets@2.0.3:
     resolution: {integrity: sha512-ETShhQGb9SoiwcNrvb3BhUNSGR89Jao0+XxxfzzLW1YsUzx8+rMO4z9oqWWmo6OHUmfNQRvqRj0cAyPkS9lN9w==}
     peerDependencies:
@@ -12789,6 +13170,9 @@ packages:
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
     hasBin: true
 
+  roughjs@4.6.6:
+    resolution: {integrity: sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==}
+
   route-recognizer@0.3.4:
     resolution: {integrity: sha512-2+MhsfPhvauN1O8KaXpXAOfR/fwe8dnUXVM+xw7yt40lJRfPVQxV6yryZm0cgRvAj5fMF/mdRZbL2ptwbs5i2g==}
 
@@ -12842,6 +13226,9 @@ packages:
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
+  rw@1.3.3:
+    resolution: {integrity: sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==}
+
   rxjs@6.6.7:
     resolution: {integrity: sha512-hTdwr+7yYNIT5n4AMYp85KA6yw2Va0FLa3Rguvbpa4W3I5xynaBZo41cM3XM+4Q6fRMj3sBYIR1VAmZMXYJvRQ==}
     engines: {npm: '>=2.0.0'}
@@ -13388,6 +13775,9 @@ packages:
   styled_string@0.0.1:
     resolution: {integrity: sha512-DU2KZiB6VbPkO2tGSqQ9n96ZstUPjW7X4sGO6V2m1myIQluX0p1Ol8BrA/l6/EesqhMqXOIXs3cJNOy1UuU2BA==}
 
+  stylis@4.3.6:
+    resolution: {integrity: sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ==}
+
   super-fast-md5@1.0.3:
     resolution: {integrity: sha512-O3nrtAg5VPcpBFpLsU1z53k6KbVZirirDWWud+r1WrZQB7WzLG5ocFMDoxjSkPUi3ehZ7me9M6KNT+CTDP+WiQ==}
 
@@ -13565,6 +13955,10 @@ packages:
   tinyexec@0.3.2:
     resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
 
+  tinyexec@1.0.4:
+    resolution: {integrity: sha512-u9r3uZC0bdpGOXtlxUIdwf9pkmvhqJdrVCH9fapQtgy/OeTTMZ1nqH7agtvEfmGui6e1XxjcdrlxvxJvc3sMqw==}
+    engines: {node: '>=18'}
+
   tinyglobby@0.2.15:
     resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
     engines: {node: '>=12.0.0'}
@@ -13683,6 +14077,10 @@ packages:
     peerDependencies:
       typescript: '>=4.0.0'
 
+  ts-dedent@2.2.0:
+    resolution: {integrity: sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==}
+    engines: {node: '>=6.10'}
+
   ts-node@10.9.2:
     resolution: {integrity: sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==}
     hasBin: true
@@ -13836,6 +14234,9 @@ packages:
   uc.micro@2.1.0:
     resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==}
 
+  ufo@1.6.3:
+    resolution: {integrity: sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q==}
+
   uglify-js@3.19.3:
     resolution: {integrity: sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==}
     engines: {node: '>=0.8.0'}
@@ -14551,6 +14952,11 @@ snapshots:
 
   '@adraffy/ens-normalize@1.10.1': {}
 
+  '@antfu/install-pkg@1.1.0':
+    dependencies:
+      package-manager-detector: 1.6.0
+      tinyexec: 1.0.4
+
   '@asamuzakjp/css-color@3.2.0':
     dependencies:
       '@csstools/css-calc': 2.1.4(@csstools/css-parser-algorithms@3.0.5(@csstools/css-tokenizer@3.0.4))(@csstools/css-tokenizer@3.0.4)
@@ -15468,6 +15874,8 @@ snapshots:
       '@babel/helper-string-parser': 7.27.1
       '@babel/helper-validator-identifier': 7.28.5
 
+  '@braintree/sanitize-url@7.1.2': {}
+
   '@cardstack/logger@0.2.1':
     dependencies:
       '@types/ms': 0.7.34
@@ -15485,6 +15893,23 @@ snapshots:
       - '@babel/core'
       - supports-color
 
+  '@chevrotain/cst-dts-gen@11.1.2':
+    dependencies:
+      '@chevrotain/gast': 11.1.2
+      '@chevrotain/types': 11.1.2
+      lodash-es: 4.17.23
+
+  '@chevrotain/gast@11.1.2':
+    dependencies:
+      '@chevrotain/types': 11.1.2
+      lodash-es: 4.17.23
+
+  '@chevrotain/regexp-to-ast@11.1.2': {}
+
+  '@chevrotain/types@11.1.2': {}
+
+  '@chevrotain/utils@11.1.2': {}
+
   '@cnakazawa/watch@1.0.4':
     dependencies:
       exec-sh: 0.3.6
@@ -16588,6 +17013,14 @@ snapshots:
 
   '@humanwhocodes/object-schema@2.0.3': {}
 
+  '@iconify/types@2.0.0': {}
+
+  '@iconify/utils@3.1.0':
+    dependencies:
+      '@antfu/install-pkg': 1.1.0
+      '@iconify/types': 2.0.0
+      mlly: 1.8.2
+
   '@inquirer/ansi@2.0.4': {}
 
   '@inquirer/checkbox@5.1.2(@types/node@25.0.8)':
@@ -16805,6 +17238,10 @@ snapshots:
 
   '@matrix-org/matrix-sdk-crypto-wasm@15.3.0': {}
 
+  '@mermaid-js/parser@1.1.0':
+    dependencies:
+      langium: 4.2.1
+
   '@nicolo-ribaudo/eslint-scope-5-internals@5.1.1-v1':
     dependencies:
       eslint-scope: 5.1.1
@@ -17907,6 +18344,123 @@ snapshots:
     dependencies:
       '@types/node': 25.0.8
 
+  '@types/d3-array@3.2.2': {}
+
+  '@types/d3-axis@3.0.6':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-brush@3.0.6':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-chord@3.0.6': {}
+
+  '@types/d3-color@3.1.3': {}
+
+  '@types/d3-contour@3.0.6':
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/geojson': 7946.0.16
+
+  '@types/d3-delaunay@6.0.4': {}
+
+  '@types/d3-dispatch@3.0.7': {}
+
+  '@types/d3-drag@3.0.7':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-dsv@3.0.7': {}
+
+  '@types/d3-ease@3.0.2': {}
+
+  '@types/d3-fetch@3.0.7':
+    dependencies:
+      '@types/d3-dsv': 3.0.7
+
+  '@types/d3-force@3.0.10': {}
+
+  '@types/d3-format@3.0.4': {}
+
+  '@types/d3-geo@3.1.0':
+    dependencies:
+      '@types/geojson': 7946.0.16
+
+  '@types/d3-hierarchy@3.1.7': {}
+
+  '@types/d3-interpolate@3.0.4':
+    dependencies:
+      '@types/d3-color': 3.1.3
+
+  '@types/d3-path@3.1.1': {}
+
+  '@types/d3-polygon@3.0.2': {}
+
+  '@types/d3-quadtree@3.0.6': {}
+
+  '@types/d3-random@3.0.3': {}
+
+  '@types/d3-scale-chromatic@3.1.0': {}
+
+  '@types/d3-scale@4.0.9':
+    dependencies:
+      '@types/d3-time': 3.0.4
+
+  '@types/d3-selection@3.0.11': {}
+
+  '@types/d3-shape@3.1.8':
+    dependencies:
+      '@types/d3-path': 3.1.1
+
+  '@types/d3-time-format@4.0.3': {}
+
+  '@types/d3-time@3.0.4': {}
+
+  '@types/d3-timer@3.0.2': {}
+
+  '@types/d3-transition@3.0.9':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-zoom@3.0.8':
+    dependencies:
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3@7.4.3':
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/d3-axis': 3.0.6
+      '@types/d3-brush': 3.0.6
+      '@types/d3-chord': 3.0.6
+      '@types/d3-color': 3.1.3
+      '@types/d3-contour': 3.0.6
+      '@types/d3-delaunay': 6.0.4
+      '@types/d3-dispatch': 3.0.7
+      '@types/d3-drag': 3.0.7
+      '@types/d3-dsv': 3.0.7
+      '@types/d3-ease': 3.0.2
+      '@types/d3-fetch': 3.0.7
+      '@types/d3-force': 3.0.10
+      '@types/d3-format': 3.0.4
+      '@types/d3-geo': 3.1.0
+      '@types/d3-hierarchy': 3.1.7
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-path': 3.1.1
+      '@types/d3-polygon': 3.0.2
+      '@types/d3-quadtree': 3.0.6
+      '@types/d3-random': 3.0.3
+      '@types/d3-scale': 4.0.9
+      '@types/d3-scale-chromatic': 3.1.0
+      '@types/d3-selection': 3.0.11
+      '@types/d3-shape': 3.1.8
+      '@types/d3-time': 3.0.4
+      '@types/d3-time-format': 4.0.3
+      '@types/d3-timer': 3.0.2
+      '@types/d3-transition': 3.0.9
+      '@types/d3-zoom': 3.0.8
+
   '@types/debug@4.1.12':
     dependencies:
       '@types/ms': 2.1.0
@@ -17973,6 +18527,8 @@ snapshots:
     dependencies:
       '@types/node': 25.0.8
 
+  '@types/geojson@7946.0.16': {}
+
   '@types/glob@7.2.0':
     dependencies:
       '@types/minimatch': 6.0.0
@@ -18066,7 +18622,7 @@ snapshots:
 
   '@types/minimatch@6.0.0':
     dependencies:
-      minimatch: 10.1.1
+      minimatch: 10.2.4
 
   '@types/minimist@1.2.5': {}
 
@@ -18382,6 +18938,11 @@ snapshots:
       - '@glint/template'
       - supports-color
 
+  '@upsetjs/venn.js@2.0.0':
+    optionalDependencies:
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
   '@vitest/expect@2.1.9':
     dependencies:
       '@vitest/spy': 2.1.9
@@ -18671,6 +19232,8 @@ snapshots:
 
   acorn@8.15.0: {}
 
+  acorn@8.16.0: {}
+
   aes-js@4.0.0-beta.5: {}
 
   agent-base@6.0.2:
@@ -20028,6 +20591,20 @@ snapshots:
 
   chess.js@1.0.0-beta.8: {}
 
+  chevrotain-allstar@0.3.1(chevrotain@11.1.2):
+    dependencies:
+      chevrotain: 11.1.2
+      lodash-es: 4.18.1
+
+  chevrotain@11.1.2:
+    dependencies:
+      '@chevrotain/cst-dts-gen': 11.1.2
+      '@chevrotain/gast': 11.1.2
+      '@chevrotain/regexp-to-ast': 11.1.2
+      '@chevrotain/types': 11.1.2
+      '@chevrotain/utils': 11.1.2
+      lodash-es: 4.17.23
+
   chownr@1.1.4:
     optional: true
 
@@ -20227,6 +20804,8 @@ snapshots:
       tree-kill: 1.2.2
       yargs: 17.7.2
 
+  confbox@0.1.8: {}
+
   configstore@5.0.1:
     dependencies:
       dot-prop: 5.3.0
@@ -20338,6 +20917,14 @@ snapshots:
 
   corser@2.0.1: {}
 
+  cose-base@1.0.3:
+    dependencies:
+      layout-base: 1.0.2
+
+  cose-base@2.2.0:
+    dependencies:
+      layout-base: 2.0.1
+
   cosmiconfig@8.3.6(typescript@5.9.3):
     dependencies:
       import-fresh: 3.3.1
@@ -20490,8 +21077,192 @@ snapshots:
 
   csstype@3.2.3: {}
 
+  cytoscape-cose-bilkent@4.1.0(cytoscape@3.33.1):
+    dependencies:
+      cose-base: 1.0.3
+      cytoscape: 3.33.1
+
+  cytoscape-fcose@2.2.0(cytoscape@3.33.1):
+    dependencies:
+      cose-base: 2.2.0
+      cytoscape: 3.33.1
+
+  cytoscape@3.33.1: {}
+
+  d3-array@2.12.1:
+    dependencies:
+      internmap: 1.0.1
+
+  d3-array@3.2.4:
+    dependencies:
+      internmap: 2.0.3
+
+  d3-axis@3.0.0: {}
+
+  d3-brush@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  d3-chord@3.0.1:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-color@3.1.0: {}
+
+  d3-contour@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-delaunay@6.0.4:
+    dependencies:
+      delaunator: 5.1.0
+
+  d3-dispatch@3.0.1: {}
+
+  d3-drag@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-selection: 3.0.0
+
+  d3-dsv@3.0.1:
+    dependencies:
+      commander: 7.2.0
+      iconv-lite: 0.6.3
+      rw: 1.3.3
+
+  d3-ease@3.0.1: {}
+
+  d3-fetch@3.0.1:
+    dependencies:
+      d3-dsv: 3.0.1
+
+  d3-force@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-timer: 3.0.1
+
+  d3-format@3.1.2: {}
+
+  d3-geo@3.1.1:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-hierarchy@3.1.2: {}
+
+  d3-interpolate@3.0.1:
+    dependencies:
+      d3-color: 3.1.0
+
+  d3-path@1.0.9: {}
+
+  d3-path@3.1.0: {}
+
+  d3-polygon@3.0.1: {}
+
+  d3-quadtree@3.0.1: {}
+
+  d3-random@3.0.1: {}
+
+  d3-sankey@0.12.3:
+    dependencies:
+      d3-array: 2.12.1
+      d3-shape: 1.3.7
+
+  d3-scale-chromatic@3.1.0:
+    dependencies:
+      d3-color: 3.1.0
+      d3-interpolate: 3.0.1
+
+  d3-scale@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+      d3-format: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+
+  d3-selection@3.0.0: {}
+
+  d3-shape@1.3.7:
+    dependencies:
+      d3-path: 1.0.9
+
+  d3-shape@3.2.0:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-time-format@4.1.0:
+    dependencies:
+      d3-time: 3.1.0
+
+  d3-time@3.1.0:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-timer@3.0.1: {}
+
+  d3-transition@3.0.1(d3-selection@3.0.0):
+    dependencies:
+      d3-color: 3.1.0
+      d3-dispatch: 3.0.1
+      d3-ease: 3.0.1
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-timer: 3.0.1
+
+  d3-zoom@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  d3@7.9.0:
+    dependencies:
+      d3-array: 3.2.4
+      d3-axis: 3.0.0
+      d3-brush: 3.0.0
+      d3-chord: 3.0.1
+      d3-color: 3.1.0
+      d3-contour: 4.0.2
+      d3-delaunay: 6.0.4
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-dsv: 3.0.1
+      d3-ease: 3.0.1
+      d3-fetch: 3.0.1
+      d3-force: 3.0.0
+      d3-format: 3.1.2
+      d3-geo: 3.1.1
+      d3-hierarchy: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-path: 3.1.0
+      d3-polygon: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-random: 3.0.1
+      d3-scale: 4.0.2
+      d3-scale-chromatic: 3.1.0
+      d3-selection: 3.0.0
+      d3-shape: 3.2.0
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+      d3-timer: 3.0.1
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+      d3-zoom: 3.0.0
+
   dag-map@2.0.2: {}
 
+  dagre-d3-es@7.0.14:
+    dependencies:
+      d3: 7.9.0
+      lodash-es: 4.18.1
+
   data-uri-to-buffer@3.0.1: {}
 
   data-uri-to-buffer@6.0.2: {}
@@ -20659,6 +21430,10 @@ snapshots:
       rimraf: 3.0.2
       slash: 3.0.0
 
+  delaunator@5.1.0:
+    dependencies:
+      robust-predicates: 3.0.3
+
   delayed-stream@1.0.0: {}
 
   delegates@1.0.0: {}
@@ -23722,6 +24497,8 @@ snapshots:
 
   growly@1.3.0: {}
 
+  hachure-fill@0.5.2: {}
+
   handlebars@4.7.8:
     dependencies:
       minimist: 1.2.8
@@ -24135,6 +24912,10 @@ snapshots:
       hasown: 2.0.2
       side-channel: 1.1.0
 
+  internmap@1.0.1: {}
+
+  internmap@2.0.3: {}
+
   invert-kv@3.0.1: {}
 
   ip-address@10.1.0: {}
@@ -24621,6 +25402,10 @@ snapshots:
 
   jwt-decode@4.0.0: {}
 
+  katex@0.16.44:
+    dependencies:
+      commander: 8.3.0
+
   keygrip@1.1.0:
     dependencies:
       tsscmp: 1.0.6
@@ -24639,6 +25424,8 @@ snapshots:
     dependencies:
       json-buffer: 3.0.1
 
+  khroma@2.1.0: {}
+
   kind-of@3.2.2:
     dependencies:
       is-buffer: 1.1.6
@@ -24693,6 +25480,18 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  langium@4.2.1:
+    dependencies:
+      chevrotain: 11.1.2
+      chevrotain-allstar: 0.3.1(chevrotain@11.1.2)
+      vscode-languageserver: 9.0.1
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.1.0
+
+  layout-base@1.0.2: {}
+
+  layout-base@2.0.1: {}
+
   lazy-ass@1.6.0: {}
 
   lazystream@1.0.1:
@@ -24775,6 +25574,10 @@ snapshots:
     dependencies:
       p-locate: 6.0.0
 
+  lodash-es@4.17.23: {}
+
+  lodash-es@4.18.1: {}
+
   lodash._baseflatten@3.1.4:
     dependencies:
       lodash.isarguments: 3.1.0
@@ -24968,6 +25771,8 @@ snapshots:
 
   marked@12.0.2: {}
 
+  marked@16.4.2: {}
+
   matcher-collection@1.1.2:
     dependencies:
       minimatch: 3.1.2
@@ -25086,6 +25891,30 @@ snapshots:
 
   merge2@1.4.1: {}
 
+  mermaid@11.14.0:
+    dependencies:
+      '@braintree/sanitize-url': 7.1.2
+      '@iconify/utils': 3.1.0
+      '@mermaid-js/parser': 1.1.0
+      '@types/d3': 7.4.3
+      '@upsetjs/venn.js': 2.0.0
+      cytoscape: 3.33.1
+      cytoscape-cose-bilkent: 4.1.0(cytoscape@3.33.1)
+      cytoscape-fcose: 2.2.0(cytoscape@3.33.1)
+      d3: 7.9.0
+      d3-sankey: 0.12.3
+      dagre-d3-es: 7.0.14
+      dayjs: 1.11.19
+      dompurify: 3.3.1
+      katex: 0.16.44
+      khroma: 2.1.0
+      lodash-es: 4.18.1
+      marked: 16.4.2
+      roughjs: 4.6.6
+      stylis: 4.3.6
+      ts-dedent: 2.2.0
+      uuid: 11.1.0
+
   methods@1.1.2: {}
 
   micromark@2.11.4:
@@ -25237,6 +26066,13 @@ snapshots:
 
   mktemp@2.0.2: {}
 
+  mlly@1.8.2:
+    dependencies:
+      acorn: 8.16.0
+      pathe: 2.0.3
+      pkg-types: 1.3.1
+      ufo: 1.6.3
+
   module-details-from-path@1.0.4: {}
 
   moment-locales-webpack-plugin@1.2.0(moment@2.30.1)(webpack@5.104.1):
@@ -25735,6 +26571,8 @@ snapshots:
       registry-url: 5.1.0
       semver: 6.3.1
 
+  package-manager-detector@1.6.0: {}
+
   pako@2.1.0: {}
 
   parent-module@1.0.1:
@@ -25807,6 +26645,8 @@ snapshots:
 
   path-browserify@1.0.1: {}
 
+  path-data-parser@0.1.0: {}
+
   path-exists@3.0.0: {}
 
   path-exists@4.0.0: {}
@@ -25875,6 +26715,8 @@ snapshots:
 
   pathe@1.1.2: {}
 
+  pathe@2.0.3: {}
+
   pathval@2.0.1: {}
 
   pause-stream@0.0.11:
@@ -25947,6 +26789,12 @@ snapshots:
 
   pkg-entry-points@1.1.1: {}
 
+  pkg-types@1.3.1:
+    dependencies:
+      confbox: 0.1.8
+      mlly: 1.8.2
+      pathe: 2.0.3
+
   pkg-up@2.0.0:
     dependencies:
       find-up: 2.1.0
@@ -25967,6 +26815,13 @@ snapshots:
 
   pluralize@8.0.0: {}
 
+  points-on-curve@0.2.0: {}
+
+  points-on-path@0.2.1:
+    dependencies:
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+
   portfinder@1.0.38:
     dependencies:
       async: 3.2.6
@@ -26610,6 +27465,8 @@ snapshots:
       hash-base: 3.1.2
       inherits: 2.0.4
 
+  robust-predicates@3.0.3: {}
+
   rollup-plugin-copy-assets@2.0.3(rollup@4.55.1):
     dependencies:
       fs-extra: 7.0.1
@@ -26659,6 +27516,13 @@ snapshots:
       '@rollup/rollup-win32-x64-msvc': 4.55.1
       fsevents: 2.3.3
 
+  roughjs@4.6.6:
+    dependencies:
+      hachure-fill: 0.5.2
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+      points-on-path: 0.2.1
+
   route-recognizer@0.3.4: {}
 
   router@2.2.0:
@@ -26701,6 +27565,8 @@ snapshots:
     dependencies:
       queue-microtask: 1.2.3
 
+  rw@1.3.3: {}
+
   rxjs@6.6.7:
     dependencies:
       tslib: 1.14.1
@@ -27418,6 +28284,8 @@ snapshots:
 
   styled_string@0.0.1: {}
 
+  stylis@4.3.6: {}
+
   super-fast-md5@1.0.3:
     dependencies:
       '@types/node': 20.19.29
@@ -27729,6 +28597,8 @@ snapshots:
 
   tinyexec@0.3.2: {}
 
+  tinyexec@1.0.4: {}
+
   tinyglobby@0.2.15:
     dependencies:
       fdir: 6.5.0(picomatch@4.0.3)
@@ -27854,6 +28724,8 @@ snapshots:
       picomatch: 4.0.3
       typescript: 5.9.3
 
+  ts-dedent@2.2.0: {}
+
   ts-node@10.9.2(@types/node@24.10.8)(typescript@5.9.3):
     dependencies:
       '@cspotcode/source-map-support': 0.8.1
@@ -28024,6 +28896,8 @@ snapshots:
 
   uc.micro@2.1.0: {}
 
+  ufo@1.6.3: {}
+
   uglify-js@3.19.3:
     optional: true
 
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 04cb97c5d71..948eb6bfc44 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -183,6 +183,7 @@ catalog:
   magic-string: 0.25.9
   marked: ^12.0.1
   marked-alert: ^2.1.2
+  mermaid: ^11.14.0
   marked-extended-tables: ^2.0.1
   marked-footnote: ^1.4.0
   marked-gfm-heading-id: ^3.2.0

From 74ff7184111c6abdcc9825032f32f525b43382ce Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 21:52:12 -0400
Subject: [PATCH 26/50] Add KaTeX math client-side rendering (CS-10601)

Lazy-load KaTeX to render math placeholders emitted by the BFM
markdown pipeline. KaTeX JS (~268KB) is loaded on-demand only when
.math-placeholder elements are present in the rendered markdown.

Implementation:
- Add `katex` dependency to host package (webpack code-splits the JS)
- Import katex.min.css statically in app.ts (24KB, needed for font
  declarations so glyphs render correctly on first paint)
- Register `__loadKatex` global loader in application route (same
  pattern as Monaco/Mermaid)
- Add `renderMathExpressions` modifier to markdown template that
  queries .math-placeholder elements, lazy-loads KaTeX, and calls
  katex.render() with throwOnError: false for graceful degradation
- Add acceptance test verifying math placeholders render with KaTeX

On failure, the placeholder with raw LaTeX source ($E = mc^2$)
remains visible as readable fallback text.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  | 43 +++++++++++++++++++
 packages/host/app/app.ts                      |  1 +
 packages/host/app/routes/application.ts       |  7 +++
 packages/host/package.json                    |  1 +
 .../acceptance/markdown-file-def-test.gts     | 37 ++++++++++++++++
 pnpm-lock.yaml                                |  6 +++
 pnpm-workspace.yaml                           |  1 +
 7 files changed, 96 insertions(+)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 7a2cb0cc7a9..1d061b207f5 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -256,6 +256,48 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     },
   );
 
+  renderMathExpressions = modifier(
+    (element: HTMLElement, _positional: unknown[]) => {
+      let mathNodes =
+        element.querySelectorAll<HTMLElement>('.math-placeholder');
+      if (!mathNodes.length) {
+        return;
+      }
+
+      let cancelled = false;
+
+      let render = async () => {
+        let loadKatex = (globalThis as any).__loadKatex;
+        if (typeof loadKatex !== 'function') {
+          return;
+        }
+        try {
+          let katex = await loadKatex();
+          if (cancelled) return;
+
+          for (let el of Array.from(mathNodes)) {
+            let math = el.getAttribute('data-math');
+            if (!math) continue;
+            let displayMode = el.getAttribute('data-display') === 'true';
+            katex.render(math, el, {
+              displayMode,
+              throwOnError: false,
+            });
+          }
+        } catch (error) {
+          console.error('[markdown] KaTeX rendering failed:', error);
+          // On failure the placeholder with raw LaTeX source remains visible.
+        }
+      };
+
+      scheduleOnce('afterRender', null, render);
+
+      return () => {
+        cancelled = true;
+      };
+    },
+  );
+
   renderMermaidDiagrams = modifier(
     (element: HTMLElement, _positional: unknown[]) => {
       let mermaidNodes =
@@ -307,6 +349,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     <div
       class='markdown-content'
       {{this.captureCardSlots this.renderedHtml @linkedCards}}
+      {{this.renderMathExpressions this.renderedHtml}}
       {{this.renderMermaidDiagrams this.renderedHtml}}
     >
       {{this.renderedHtml}}
diff --git a/packages/host/app/app.ts b/packages/host/app/app.ts
index b638ea11e27..beca8236aca 100644
--- a/packages/host/app/app.ts
+++ b/packages/host/app/app.ts
@@ -10,6 +10,7 @@ import './lib/glint-embroider-workaround';
 import '@cardstack/boxel-ui/styles/global.css';
 import '@cardstack/boxel-ui/styles/fonts.css';
 import '@cardstack/boxel-ui/styles/variables.css';
+import 'katex/dist/katex.min.css';
 
 export default class App extends Application {
   modulePrefix = config.modulePrefix;
diff --git a/packages/host/app/routes/application.ts b/packages/host/app/routes/application.ts
index 35e1be643b1..8783d49b405 100644
--- a/packages/host/app/routes/application.ts
+++ b/packages/host/app/routes/application.ts
@@ -29,6 +29,12 @@ export default class Application extends Route {
         }
         return await route.monacoService.getMonacoContext();
       };
+      // Lazy-load KaTeX for math rendering in markdown content.
+      // The base package's markdown template calls this via globalThis.
+      (globalThis as any).__loadKatex ??= async () => {
+        let mod = await import('katex');
+        return mod.default;
+      };
       // Lazy-load Mermaid.js for diagram rendering in markdown content.
       // The base package's markdown template calls this via globalThis.
       (globalThis as any).__loadMermaid ??= async () => {
@@ -42,6 +48,7 @@ export default class Application extends Route {
     super.willDestroy?.();
     if (typeof globalThis !== 'undefined') {
       delete (globalThis as any).__loadMonacoForMarkdown;
+      delete (globalThis as any).__loadKatex;
       delete (globalThis as any).__loadMermaid;
     }
   }
diff --git a/packages/host/package.json b/packages/host/package.json
index 6a3f61ffaba..83e7eda3d72 100644
--- a/packages/host/package.json
+++ b/packages/host/package.json
@@ -157,6 +157,7 @@
     "glimmer-scoped-css": "catalog:",
     "ignore": "catalog:",
     "indefinite": "catalog:",
+    "katex": "catalog:",
     "loader.js": "catalog:",
     "lodash": "catalog:",
     "loglevel": "catalog:",
diff --git a/packages/host/tests/acceptance/markdown-file-def-test.gts b/packages/host/tests/acceptance/markdown-file-def-test.gts
index bd16ea08946..d8975689631 100644
--- a/packages/host/tests/acceptance/markdown-file-def-test.gts
+++ b/packages/host/tests/acceptance/markdown-file-def-test.gts
@@ -313,6 +313,15 @@ module('Acceptance | markdown BFM card references', function (hooks) {
             '    B -->|No| D[Result 2]',
             '```',
           ].join('\n'),
+          'math-test.md': [
+            '# Math Test',
+            '',
+            'The formula $E = mc^2$ is famous.',
+            '',
+            '$$',
+            'x^2 + y^2 = z^2',
+            '$$',
+          ].join('\n'),
         },
       }),
     );
@@ -573,4 +582,32 @@ module('Acceptance | markdown BFM card references', function (hooks) {
         'raw mermaid source is replaced by rendered SVG',
       );
   });
+
+  test('math placeholders are rendered with KaTeX', async function (assert) {
+    await visitOperatorMode({
+      submode: 'code',
+      codePath: `${testRealmURL}math-test.md`,
+    });
+
+    // Wait for KaTeX to lazy-load and render the math expressions.
+    await waitUntil(
+      () => document.querySelector('.math-placeholder .katex') !== null,
+      {
+        timeout: 15000,
+        timeoutMessage: 'KaTeX did not render math expressions within timeout',
+      },
+    );
+
+    assert
+      .dom('.math-placeholder .katex')
+      .exists('math placeholder is rendered with KaTeX');
+
+    // Inline math should not contain the raw LaTeX source as visible text
+    assert
+      .dom('.math-placeholder')
+      .doesNotIncludeText(
+        '$E = mc^2$',
+        'raw LaTeX source is replaced by rendered math',
+      );
+  });
 });
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a123919cfe3..25040fae33d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -477,6 +477,9 @@ catalogs:
     jsonwebtoken:
       specifier: 9.0.3
       version: 9.0.3
+    katex:
+      specifier: ^0.16.44
+      version: 0.16.44
     koa:
       specifier: ^2.14.1
       version: 2.16.3
@@ -2171,6 +2174,9 @@ importers:
       indefinite:
         specifier: 'catalog:'
         version: 2.5.2
+      katex:
+        specifier: 'catalog:'
+        version: 0.16.44
       loader.js:
         specifier: 'catalog:'
         version: 4.7.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 948eb6bfc44..224b82dbfc5 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -181,6 +181,7 @@ catalog:
   lucide-static: ^0.447.0
   macro-decorators: ^0.1.2
   magic-string: 0.25.9
+  katex: ^0.16.44
   marked: ^12.0.1
   marked-alert: ^2.1.2
   mermaid: ^11.14.0

From ad74c7537c3bef7089c122cfc98573f0ad85d247 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 22:54:09 -0400
Subject: [PATCH 27/50] Fix build: add .woff asset rule for KaTeX fonts

KaTeX CSS references both .woff2 and .woff font files. The webpack
config only had a rule for .woff2, causing parse failures on .woff
files. Widen the regex to match both extensions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/ember-cli-build.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/host/ember-cli-build.js b/packages/host/ember-cli-build.js
index 0e599e62264..67194b8be19 100644
--- a/packages/host/ember-cli-build.js
+++ b/packages/host/ember-cli-build.js
@@ -56,7 +56,7 @@ module.exports = function (defaults) {
                 type: 'asset/inline',
               },
               {
-                test: /\.woff2$/,
+                test: /\.woff2?$/,
                 type: 'asset',
               },
               {

From 7b047f31ed4328946321aa690a79d6e569466392 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 23:08:47 -0400
Subject: [PATCH 28/50] Add BFM showcase document to experiments realm

Exercises all Layer 3 features: card references, GFM alerts, math/LaTeX,
mermaid diagrams, footnotes, extended tables, heading IDs, and code blocks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/experiments-realm/bfm-showcase.md | 105 +++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 packages/experiments-realm/bfm-showcase.md

diff --git a/packages/experiments-realm/bfm-showcase.md b/packages/experiments-realm/bfm-showcase.md
new file mode 100644
index 00000000000..289b53c7bf8
--- /dev/null
+++ b/packages/experiments-realm/bfm-showcase.md
@@ -0,0 +1,105 @@
+# BFM Showcase
+
+This document exercises the Boxel Flavored Markdown features added in the Layer 3 extensions.
+
+## Card References
+
+Inline reference to an author: :card[./Author/alice-enwunder] — renders in atom format.
+
+Block reference renders in embedded format:
+
+::card[./Author/jane-doe]
+
+## GFM Alerts
+
+> [!NOTE]
+> This is a note callout. Use it to highlight important information.
+
+> [!WARNING]
+> This is a warning. Be careful when editing production data.
+
+> [!TIP]
+> You can nest **bold**, *italic*, and `code` inside alerts.
+
+## Math / LaTeX
+
+The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ and appears inline.
+
+Euler's identity in a display block:
+
+$$
+e^{i\pi} + 1 = 0
+$$
+
+A summation:
+
+$$
+\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
+$$
+
+## Mermaid Diagrams
+
+```mermaid
+flowchart TD
+    A[Markdown Source] --> B[marked.parse]
+    B --> C{Has Placeholders?}
+    C -->|Math| D[KaTeX Render]
+    C -->|Mermaid| E[Mermaid Render]
+    C -->|Card Ref| F[Card Slot Modifier]
+    D --> G[Final Output]
+    E --> G
+    F --> G
+```
+
+A sequence diagram:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Host
+    participant Realm
+    User->>Host: Open markdown file
+    Host->>Realm: Fetch file content
+    Realm-->>Host: Markdown + linked cards
+    Host->>Host: marked.parse() with BFM extensions
+    Host->>Host: Render placeholders (math, mermaid, cards)
+    Host-->>User: Rendered document
+```
+
+## Footnotes
+
+Boxel Flavored Markdown[^1] extends standard GFM with additional features for rich document rendering.
+
+The math rendering uses KaTeX[^2] for typesetting, while diagrams use Mermaid.js[^3].
+
+[^1]: BFM is documented at [bfm.boxel.site](https://bfm.boxel.site/).
+[^2]: KaTeX is a fast math typesetting library for the web.
+[^3]: Mermaid lets you create diagrams using a markdown-like syntax.
+
+## Extended Tables
+
+| Feature | Status | Bundle Impact |
+| ------- | ------ | ------------- |
+| GFM Alerts | Static HTML | None |
+| Heading IDs | Static HTML | None |
+| Footnotes | Static HTML | None |
+| Extended Tables | Static HTML | None |
+| Math / LaTeX || Lazy KaTeX (~268KB) |
+| Mermaid Diagrams || Lazy Mermaid (~2MB) |
+
+## Heading IDs
+
+Each heading on this page has an auto-generated slug ID (inspect the DOM to see `id="bfm-showcase"`, `id="math--latex"`, etc.). These enable anchor links and table-of-contents navigation.
+
+## Code Blocks
+
+Standard fenced code blocks still work as expected:
+
+```typescript
+import { marked } from 'marked';
+import { markedKatexPlaceholder } from './bfm-math';
+
+marked.use(markedKatexPlaceholder());
+
+const html = marked.parse('The formula $E = mc^2$ is famous.');
+```

From b5794cf6f5a462bf0c02561615347b6470667b59 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 23:10:49 -0400
Subject: [PATCH 29/50] Fix lint: prettier formatting and eslint rule
 violations

- Split logical && in assert.true into separate assertions (qunit/no-assert-logical-expression)
- Fix prettier formatting across test files
- Use eslint-disable block for require() in marked-sync.ts to survive
  prettier line-wrapping

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../tests/unit/bfm-card-references-test.ts     |  5 ++++-
 packages/host/tests/unit/marked-sync-test.ts   | 18 ++++++------------
 packages/runtime-common/marked-sync.ts         |  6 ++++--
 3 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index c2868a19b9b..546a51a2203 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -274,7 +274,10 @@ module('Unit | bfm-card-references', function () {
         ),
         'has block ref',
       );
-      assert.true(html.includes('<h1 id="title">Title</h1>'), 'heading preserved');
+      assert.true(
+        html.includes('<h1 id="title">Title</h1>'),
+        'heading preserved',
+      );
     });
   });
 });
diff --git a/packages/host/tests/unit/marked-sync-test.ts b/packages/host/tests/unit/marked-sync-test.ts
index 42e4f10d52a..200802f9ec1 100644
--- a/packages/host/tests/unit/marked-sync-test.ts
+++ b/packages/host/tests/unit/marked-sync-test.ts
@@ -46,9 +46,10 @@ module('Unit | marked-sync', function () {
     const markdown = '# Hello <script>alert("XSS")</script>';
     const result = markdownToHtml(markdown);
 
+    assert.true(result.includes('id="hello-'), 'heading has auto-generated id');
     assert.true(
-      result.includes('id="hello-') && result.includes('>Hello </h1>'),
-      'heading was preserved with auto-generated id',
+      result.includes('>Hello </h1>'),
+      'heading content was preserved',
     );
   });
 
@@ -290,14 +291,8 @@ module('Unit | marked-sync', function () {
 `;
     const result = markedSync(markdown);
 
-    assert.true(
-      result.includes('<table>'),
-      'table is rendered',
-    );
-    assert.true(
-      result.includes('colspan'),
-      'colspan attribute is present',
-    );
+    assert.true(result.includes('<table>'), 'table is rendered');
+    assert.true(result.includes('colspan'), 'colspan attribute is present');
   });
 
   // ── BFM Layer 3: Heading IDs (marked-gfm-heading-id) ──
@@ -337,8 +332,7 @@ module('Unit | marked-sync', function () {
   });
 
   test('markdownToHtml preserves footnote markup through sanitization', function (assert) {
-    const markdown =
-      'Text[^1].\n\n[^1]: Footnote content.';
+    const markdown = 'Text[^1].\n\n[^1]: Footnote content.';
     const result = markdownToHtml(markdown);
 
     assert.true(
diff --git a/packages/runtime-common/marked-sync.ts b/packages/runtime-common/marked-sync.ts
index 93b6f7ffd2f..f792660758f 100644
--- a/packages/runtime-common/marked-sync.ts
+++ b/packages/runtime-common/marked-sync.ts
@@ -5,9 +5,11 @@ import { bfmCardReferenceExtensions } from './bfm-card-references';
 import markedAlert from 'marked-alert';
 import markedFootnote from 'marked-footnote';
 import { markedKatexPlaceholder } from './bfm-math';
+/* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires */
 // marked-extended-tables's ESM export isn't resolved by webpack; load via CJS.
-// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
-const markedExtendedTables = require('marked-extended-tables/lib/index.cjs') as () => import('marked').MarkedExtension;
+const markedExtendedTables =
+  require('marked-extended-tables/lib/index.cjs') as () => import('marked').MarkedExtension;
+/* eslint-enable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires */
 import { gfmHeadingId } from 'marked-gfm-heading-id';
 import type * as _MonacoSDK from 'monaco-editor';
 type MonacoSDK = typeof _MonacoSDK;

From 3c4b81d31dd8eeba8397535aefa4a1bc35242720 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 23:32:56 -0400
Subject: [PATCH 30/50] Fix KaTeX and Mermaid modifiers: use stable method refs
 with scheduleOnce

The modifiers were creating new arrow functions on each invocation and
passing null as the scheduleOnce target. This differs from the working
captureCardSlots pattern which uses this (component instance) and a
stable method reference. The changes:

- Use this as scheduleOnce target (consistent with captureCardSlots)
- Use stable method references (_renderMath, _renderMermaid) for proper
  scheduleOnce deduplication
- Query DOM fresh inside async methods instead of capturing a NodeList
  that may become stale during async loading
- Check el.isConnected before rendering each node

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts | 140 +++++++++----------
 1 file changed, 66 insertions(+), 74 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 1d061b207f5..747ff8e2d4f 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -256,90 +256,82 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     },
   );
 
-  renderMathExpressions = modifier(
-    (element: HTMLElement, _positional: unknown[]) => {
-      let mathNodes =
-        element.querySelectorAll<HTMLElement>('.math-placeholder');
-      if (!mathNodes.length) {
-        return;
+  private _renderMath = () => {
+    this._mathRenderPromise = this._doRenderMath();
+  };
+  private _mathRenderPromise: Promise<void> | undefined;
+
+  private async _doRenderMath() {
+    let element = this._contentElement;
+    if (!element) return;
+    let mathNodes = element.querySelectorAll<HTMLElement>('.math-placeholder');
+    if (!mathNodes.length) return;
+
+    let loadKatex = (globalThis as any).__loadKatex;
+    if (typeof loadKatex !== 'function') {
+      return;
+    }
+    try {
+      let katex = await loadKatex();
+      for (let el of Array.from(mathNodes)) {
+        if (!el.isConnected) continue;
+        let math = el.getAttribute('data-math');
+        if (!math) continue;
+        let displayMode = el.getAttribute('data-display') === 'true';
+        katex.render(math, el, {
+          displayMode,
+          throwOnError: false,
+        });
       }
+    } catch (error) {
+      console.error('[markdown] KaTeX rendering failed:', error);
+    }
+  }
 
-      let cancelled = false;
+  private _renderMermaid = () => {
+    this._mermaidRenderPromise = this._doRenderMermaid();
+  };
+  private _mermaidRenderPromise: Promise<void> | undefined;
 
-      let render = async () => {
-        let loadKatex = (globalThis as any).__loadKatex;
-        if (typeof loadKatex !== 'function') {
-          return;
-        }
-        try {
-          let katex = await loadKatex();
-          if (cancelled) return;
-
-          for (let el of Array.from(mathNodes)) {
-            let math = el.getAttribute('data-math');
-            if (!math) continue;
-            let displayMode = el.getAttribute('data-display') === 'true';
-            katex.render(math, el, {
-              displayMode,
-              throwOnError: false,
-            });
-          }
-        } catch (error) {
-          console.error('[markdown] KaTeX rendering failed:', error);
-          // On failure the placeholder with raw LaTeX source remains visible.
-        }
-      };
+  private async _doRenderMermaid() {
+    let element = this._contentElement;
+    if (!element) return;
+    let mermaidNodes = element.querySelectorAll<HTMLPreElement>('pre.mermaid');
+    if (!mermaidNodes.length) return;
+
+    let loadMermaid = (globalThis as any).__loadMermaid;
+    if (typeof loadMermaid !== 'function') {
+      return;
+    }
+    try {
+      let mermaid = await loadMermaid();
+      mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: 'strict',
+        theme: 'default',
+      });
+      await mermaid.run({
+        nodes: Array.from(mermaidNodes),
+        suppressErrors: true,
+      });
+    } catch (error) {
+      console.error('[markdown] Mermaid rendering failed:', error);
+    }
+  }
 
-      scheduleOnce('afterRender', null, render);
+  private _contentElement: HTMLElement | null = null;
 
-      return () => {
-        cancelled = true;
-      };
+  renderMathExpressions = modifier(
+    (element: HTMLElement, _positional: unknown[]) => {
+      this._contentElement = element;
+      scheduleOnce('afterRender', this, this._renderMath);
     },
   );
 
   renderMermaidDiagrams = modifier(
     (element: HTMLElement, _positional: unknown[]) => {
-      let mermaidNodes =
-        element.querySelectorAll<HTMLPreElement>('pre.mermaid');
-      if (!mermaidNodes.length) {
-        return;
-      }
-
-      let cancelled = false;
-
-      let render = async () => {
-        let loadMermaid = (globalThis as any).__loadMermaid;
-        if (typeof loadMermaid !== 'function') {
-          return;
-        }
-        try {
-          let mermaid = await loadMermaid();
-          if (cancelled) return;
-
-          mermaid.initialize({
-            startOnLoad: false,
-            securityLevel: 'strict',
-            theme: 'default',
-          });
-
-          // mermaid.run() mutates the nodes in-place, replacing the <pre>
-          // text content with rendered SVG.
-          await mermaid.run({
-            nodes: Array.from(mermaidNodes),
-            suppressErrors: true,
-          });
-        } catch (error) {
-          console.error('[markdown] Mermaid rendering failed:', error);
-          // On failure the placeholder <pre> with source text remains visible.
-        }
-      };
-
-      scheduleOnce('afterRender', null, render);
-
-      return () => {
-        cancelled = true;
-      };
+      this._contentElement = element;
+      scheduleOnce('afterRender', this, this._renderMermaid);
     },
   );
 

From e9b15d7c9a0021809c39a4731bba0b00a88c0bcd Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sat, 4 Apr 2026 23:40:16 -0400
Subject: [PATCH 31/50] Add diagnostic logging to KaTeX/Mermaid modifiers

---
 packages/base/default-templates/markdown.gts | 35 +++++++++++++++++---
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 747ff8e2d4f..9dc907104d3 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -263,16 +263,27 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 
   private async _doRenderMath() {
     let element = this._contentElement;
-    if (!element) return;
+    if (!element) {
+      console.debug('[markdown] KaTeX: no content element');
+      return;
+    }
     let mathNodes = element.querySelectorAll<HTMLElement>('.math-placeholder');
-    if (!mathNodes.length) return;
+    if (!mathNodes.length) {
+      console.debug('[markdown] KaTeX: no .math-placeholder nodes found');
+      return;
+    }
 
     let loadKatex = (globalThis as any).__loadKatex;
     if (typeof loadKatex !== 'function') {
+      console.debug(
+        '[markdown] KaTeX: __loadKatex not available on globalThis',
+      );
       return;
     }
     try {
+      console.debug('[markdown] KaTeX: loading…');
       let katex = await loadKatex();
+      console.debug('[markdown] KaTeX: loaded, rendering', mathNodes.length);
       for (let el of Array.from(mathNodes)) {
         if (!el.isConnected) continue;
         let math = el.getAttribute('data-math');
@@ -295,16 +306,30 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 
   private async _doRenderMermaid() {
     let element = this._contentElement;
-    if (!element) return;
+    if (!element) {
+      console.debug('[markdown] Mermaid: no content element');
+      return;
+    }
     let mermaidNodes = element.querySelectorAll<HTMLPreElement>('pre.mermaid');
-    if (!mermaidNodes.length) return;
+    if (!mermaidNodes.length) {
+      console.debug('[markdown] Mermaid: no pre.mermaid nodes found');
+      return;
+    }
 
     let loadMermaid = (globalThis as any).__loadMermaid;
     if (typeof loadMermaid !== 'function') {
+      console.debug(
+        '[markdown] Mermaid: __loadMermaid not available on globalThis',
+      );
       return;
     }
     try {
+      console.debug('[markdown] Mermaid: loading…');
       let mermaid = await loadMermaid();
+      console.debug(
+        '[markdown] Mermaid: loaded, rendering',
+        mermaidNodes.length,
+      );
       mermaid.initialize({
         startOnLoad: false,
         securityLevel: 'strict',
@@ -323,6 +348,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 
   renderMathExpressions = modifier(
     (element: HTMLElement, _positional: unknown[]) => {
+      console.debug('[markdown] math modifier triggered');
       this._contentElement = element;
       scheduleOnce('afterRender', this, this._renderMath);
     },
@@ -330,6 +356,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
 
   renderMermaidDiagrams = modifier(
     (element: HTMLElement, _positional: unknown[]) => {
+      console.debug('[markdown] mermaid modifier triggered');
       this._contentElement = element;
       scheduleOnce('afterRender', this, this._renderMermaid);
     },

From 94c9c865f4e6b2aa3a4e97df6f819117a4db8421 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 12:07:25 -0400
Subject: [PATCH 32/50] Fix CI: refactor KaTeX/Mermaid to string-level
 processing, fix heading ids

The modifier-based DOM mutation approach for KaTeX and Mermaid was
unreliable because Glimmer re-renders overwrite imperative DOM changes.
Refactored to process math and mermaid at the HTML-string level inside
the `renderedHtml` getter so autotracking sees the final content.

Also fixes:
- DOMPurify stripping heading ids by adding `user-content-` prefix to
  `gfmHeadingId()` (avoids DOM clobbering protection for names like
  "title", "body", "links")
- Missing type declaration for `marked-gfm-heading-id` (CJS resolution
  in `nodenext` mode)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts  | 177 +++++++++---------
 .../tests/unit/bfm-card-references-test.ts    |   4 +-
 packages/runtime-common/bfm-math-render.ts    |  29 +++
 packages/runtime-common/bfm-mermaid-render.ts |  49 +++++
 packages/runtime-common/global.d.ts           |  14 ++
 packages/runtime-common/marked-sync.ts        |   2 +-
 6 files changed, 179 insertions(+), 96 deletions(-)
 create mode 100644 packages/runtime-common/bfm-math-render.ts
 create mode 100644 packages/runtime-common/bfm-mermaid-render.ts

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 9dc907104d3..688177e07aa 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -14,6 +14,11 @@ import {
   resolveCardReference,
   trimJsonExtension,
 } from '@cardstack/runtime-common';
+import { processKatexPlaceholders } from '@cardstack/runtime-common/bfm-math-render';
+import {
+  extractMermaidBlocks,
+  replaceMermaidSvgs,
+} from '@cardstack/runtime-common/bfm-mermaid-render';
 import { type BaseDef, type CardDef, getComponent } from '../card-api';
 import { CardContextConsumer } from '../field-component';
 function wrapTablesHtml(html: string | null | undefined): string {
@@ -103,19 +108,43 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     // control for styling/overflow behavior. Re-sanitizing the result was
     // adding avoidable DOMParser churn during prerender and acceptance tests.
     html = wrapTablesHtml(html);
-    // Strip text content from card-type BFM refs so there is no flash of raw
-    // URLs. The URL is preserved in the data attribute; the modifier will
-    // inject fallback text for refs that can't be resolved to a card.
+
+    // Post-process the HTML string to render math, mermaid, and strip card ref
+    // text. This must happen at the HTML-string level (not via imperative DOM
+    // mutation) so that Glimmer's autotracking sees the final content and does
+    // not overwrite it on re-render.
+    let hasCardRefs = html.includes('data-boxel-bfm-type="card"');
+    let katex = html.includes('math-placeholder') ? this.katexModule : null;
+    let mermaidSvgs = html.includes('<pre class="mermaid">')
+      ? this.mermaidSvgs
+      : null;
+
     if (
       typeof DOMParser !== 'undefined' &&
-      html.includes('data-boxel-bfm-type="card"')
+      (hasCardRefs || katex || (mermaidSvgs && mermaidSvgs.size))
     ) {
       let doc = new DOMParser().parseFromString(html, 'text/html');
-      doc
-        .querySelectorAll('[data-boxel-bfm-type="card"]')
-        .forEach((el) => (el.textContent = ''));
+
+      // Strip text content from card-type BFM refs so there is no flash of raw
+      // URLs. The URL is preserved in the data attribute; the modifier will
+      // inject fallback text for refs that can't be resolved to a card.
+      if (hasCardRefs) {
+        doc
+          .querySelectorAll('[data-boxel-bfm-type="card"]')
+          .forEach((el) => (el.textContent = ''));
+      }
+
+      if (katex) {
+        processKatexPlaceholders(doc, katex);
+      }
+
+      if (mermaidSvgs && mermaidSvgs.size) {
+        replaceMermaidSvgs(doc, mermaidSvgs);
+      }
+
       html = doc.body.innerHTML;
     }
+
     return htmlSafe(html);
   }
 
@@ -256,111 +285,75 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     },
   );
 
-  private _renderMath = () => {
-    this._mathRenderPromise = this._doRenderMath();
-  };
-  private _mathRenderPromise: Promise<void> | undefined;
+  // ── KaTeX lazy loading ──
+  @tracked _katex: any = null;
 
-  private async _doRenderMath() {
-    let element = this._contentElement;
-    if (!element) {
-      console.debug('[markdown] KaTeX: no content element');
-      return;
+  get katexModule() {
+    if (this.isPrerenderContext) {
+      return null;
     }
-    let mathNodes = element.querySelectorAll<HTMLElement>('.math-placeholder');
-    if (!mathNodes.length) {
-      console.debug('[markdown] KaTeX: no .math-placeholder nodes found');
-      return;
+    if (!this._katex) {
+      this._loadKatexTask.perform();
     }
+    return this._katex;
+  }
 
+  _loadKatexTask = task({ drop: true }, async () => {
     let loadKatex = (globalThis as any).__loadKatex;
     if (typeof loadKatex !== 'function') {
-      console.debug(
-        '[markdown] KaTeX: __loadKatex not available on globalThis',
-      );
       return;
     }
-    try {
-      console.debug('[markdown] KaTeX: loading…');
-      let katex = await loadKatex();
-      console.debug('[markdown] KaTeX: loaded, rendering', mathNodes.length);
-      for (let el of Array.from(mathNodes)) {
-        if (!el.isConnected) continue;
-        let math = el.getAttribute('data-math');
-        if (!math) continue;
-        let displayMode = el.getAttribute('data-display') === 'true';
-        katex.render(math, el, {
-          displayMode,
-          throwOnError: false,
-        });
-      }
-    } catch (error) {
-      console.error('[markdown] KaTeX rendering failed:', error);
-    }
-  }
+    this._katex = await loadKatex();
+  });
 
-  private _renderMermaid = () => {
-    this._mermaidRenderPromise = this._doRenderMermaid();
-  };
-  private _mermaidRenderPromise: Promise<void> | undefined;
+  // ── Mermaid lazy loading + pre-rendering ──
+  @tracked _mermaidSvgs = new Map<string, string>();
+  private _mermaidIdCounter = 0;
 
-  private async _doRenderMermaid() {
-    let element = this._contentElement;
-    if (!element) {
-      console.debug('[markdown] Mermaid: no content element');
-      return;
+  get mermaidSvgs() {
+    if (this.isPrerenderContext) {
+      return this._mermaidSvgs;
     }
-    let mermaidNodes = element.querySelectorAll<HTMLPreElement>('pre.mermaid');
-    if (!mermaidNodes.length) {
-      console.debug('[markdown] Mermaid: no pre.mermaid nodes found');
+    if (!this._mermaidSvgs.size) {
+      this._renderMermaidTask.perform();
+    }
+    return this._mermaidSvgs;
+  }
+
+  _renderMermaidTask = task({ drop: true }, async () => {
+    let content = this.args.content || '';
+    let blocks = extractMermaidBlocks(content);
+    if (!blocks.length) {
       return;
     }
 
     let loadMermaid = (globalThis as any).__loadMermaid;
     if (typeof loadMermaid !== 'function') {
-      console.debug(
-        '[markdown] Mermaid: __loadMermaid not available on globalThis',
-      );
       return;
     }
-    try {
-      console.debug('[markdown] Mermaid: loading…');
-      let mermaid = await loadMermaid();
-      console.debug(
-        '[markdown] Mermaid: loaded, rendering',
-        mermaidNodes.length,
-      );
-      mermaid.initialize({
-        startOnLoad: false,
-        securityLevel: 'strict',
-        theme: 'default',
-      });
-      await mermaid.run({
-        nodes: Array.from(mermaidNodes),
-        suppressErrors: true,
-      });
-    } catch (error) {
-      console.error('[markdown] Mermaid rendering failed:', error);
-    }
-  }
 
-  private _contentElement: HTMLElement | null = null;
+    let mermaid = await loadMermaid();
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: 'strict',
+      theme: 'default',
+    });
 
-  renderMathExpressions = modifier(
-    (element: HTMLElement, _positional: unknown[]) => {
-      console.debug('[markdown] math modifier triggered');
-      this._contentElement = element;
-      scheduleOnce('afterRender', this, this._renderMath);
-    },
-  );
+    let svgs = new Map<string, string>();
+    for (let block of blocks) {
+      try {
+        let { svg } = await mermaid.render(
+          `mermaid-${++this._mermaidIdCounter}`,
+          block,
+        );
+        svgs.set(block, svg);
+      } catch {
+        // skip failed blocks
+      }
+    }
 
-  renderMermaidDiagrams = modifier(
-    (element: HTMLElement, _positional: unknown[]) => {
-      console.debug('[markdown] mermaid modifier triggered');
-      this._contentElement = element;
-      scheduleOnce('afterRender', this, this._renderMermaid);
-    },
-  );
+    this._mermaidSvgs = svgs;
+  });
 
   getCardComponent = (card: BaseDef) => getComponent(card);
 
@@ -368,8 +361,6 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     <div
       class='markdown-content'
       {{this.captureCardSlots this.renderedHtml @linkedCards}}
-      {{this.renderMathExpressions this.renderedHtml}}
-      {{this.renderMermaidDiagrams this.renderedHtml}}
     >
       {{this.renderedHtml}}
     </div>
diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 546a51a2203..854f0489412 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -275,8 +275,8 @@ module('Unit | bfm-card-references', function () {
         'has block ref',
       );
       assert.true(
-        html.includes('<h1 id="title">Title</h1>'),
-        'heading preserved',
+        html.includes('<h1 id="user-content-title">Title</h1>'),
+        'heading preserved with id',
       );
     });
   });
diff --git a/packages/runtime-common/bfm-math-render.ts b/packages/runtime-common/bfm-math-render.ts
new file mode 100644
index 00000000000..85f84eeca3e
--- /dev/null
+++ b/packages/runtime-common/bfm-math-render.ts
@@ -0,0 +1,29 @@
+/**
+ * Post-processes math placeholder elements in an HTML document by rendering
+ * them with KaTeX. The placeholders are emitted by the `markedKatexPlaceholder`
+ * extension in `bfm-math.ts`.
+ *
+ * This operates on a DOMParser document (string-level processing) so that the
+ * resulting HTML can be set via Glimmer's tracked rendering without being
+ * overwritten by re-renders.
+ */
+export function processKatexPlaceholders(
+  doc: Document,
+  katex: { renderToString(expr: string, opts: object): string },
+): void {
+  for (let el of Array.from(
+    doc.querySelectorAll<HTMLElement>('.math-placeholder'),
+  )) {
+    let math = el.getAttribute('data-math');
+    if (!math) continue;
+    let displayMode = el.getAttribute('data-display') === 'true';
+    try {
+      el.innerHTML = katex.renderToString(math, {
+        displayMode,
+        throwOnError: false,
+      });
+    } catch {
+      // leave placeholder as-is
+    }
+  }
+}
diff --git a/packages/runtime-common/bfm-mermaid-render.ts b/packages/runtime-common/bfm-mermaid-render.ts
new file mode 100644
index 00000000000..54424ba6261
--- /dev/null
+++ b/packages/runtime-common/bfm-mermaid-render.ts
@@ -0,0 +1,49 @@
+/**
+ * Utilities for extracting mermaid diagram definitions from markdown and
+ * replacing placeholder elements with pre-rendered SVG output.
+ *
+ * The placeholder `<pre class="mermaid">...escaped source...</pre>` is emitted
+ * by the custom code renderer in `marked-sync.ts`. This module provides the
+ * helpers used by the markdown component to lazily render those placeholders.
+ */
+
+const MERMAID_FENCE_RE = new RegExp('```mermaid\\s*\\n([\\s\\S]*?)```', 'g');
+
+/**
+ * Extract mermaid code block contents from raw markdown source.
+ *
+ * Returns an array of trimmed mermaid diagram definitions, in document order.
+ */
+export function extractMermaidBlocks(markdown: string): string[] {
+  let blocks: string[] = [];
+  // Reset lastIndex in case of reuse (global regex).
+  MERMAID_FENCE_RE.lastIndex = 0;
+  let match;
+  while ((match = MERMAID_FENCE_RE.exec(markdown)) !== null) {
+    blocks.push(match[1].trim());
+  }
+  return blocks;
+}
+
+/**
+ * Replace `<pre class="mermaid">` placeholder elements in a parsed HTML
+ * document with pre-rendered SVG strings.
+ *
+ * Matching is done by comparing the text content of each `<pre>` element
+ * (trimmed) against the keys in the `svgs` map.
+ */
+export function replaceMermaidSvgs(
+  doc: Document,
+  svgs: Map<string, string>,
+): void {
+  for (let el of Array.from(
+    doc.querySelectorAll<HTMLPreElement>('pre.mermaid'),
+  )) {
+    let code = el.textContent?.trim() || '';
+    let svg = svgs.get(code);
+    if (svg) {
+      el.innerHTML = svg;
+      el.setAttribute('data-processed', 'true');
+    }
+  }
+}
diff --git a/packages/runtime-common/global.d.ts b/packages/runtime-common/global.d.ts
index b5e143df7bc..d1b3c13ca21 100644
--- a/packages/runtime-common/global.d.ts
+++ b/packages/runtime-common/global.d.ts
@@ -12,3 +12,17 @@ declare module '@babel/plugin-transform-typescript' {
   import type * as Babel from '@babel/core';
   export default function makePlugin(babel: typeof Babel): Babel.PluginObj;
 }
+
+declare module 'marked-gfm-heading-id' {
+  import type { MarkedExtension } from 'marked';
+  export function gfmHeadingId(options?: {
+    prefix?: string;
+  }): MarkedExtension;
+  export interface HeadingData {
+    level: number;
+    text: string;
+    id: string;
+  }
+  export function getHeadingList(): HeadingData[];
+  export function resetHeadings(): void;
+}
diff --git a/packages/runtime-common/marked-sync.ts b/packages/runtime-common/marked-sync.ts
index f792660758f..00979551b13 100644
--- a/packages/runtime-common/marked-sync.ts
+++ b/packages/runtime-common/marked-sync.ts
@@ -19,7 +19,7 @@ type MonacoSDK = typeof _MonacoSDK;
 marked.use({ extensions: bfmCardReferenceExtensions() });
 
 // Register community marked extensions for BFM layers 3+ (GFM enhancements).
-marked.use(gfmHeadingId());
+marked.use(gfmHeadingId({ prefix: 'user-content-' }));
 marked.use(markedAlert());
 marked.use(markedFootnote());
 marked.use(markedExtendedTables());

From 0ada8be6642ac8a1790b9a5d960a059aef96ca55 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 12:32:37 -0400
Subject: [PATCH 33/50] Fix: export bfm-math-render and bfm-mermaid-render from
 main entry point

Deep path imports like `@cardstack/runtime-common/bfm-mermaid-render`
are not resolved by the card runtime's module loader. Move imports to
the main barrel export so they resolve correctly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts | 8 +++-----
 packages/runtime-common/index.ts             | 2 ++
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index 688177e07aa..0771a4f1e35 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -8,17 +8,15 @@ import { modifier } from 'ember-modifier';
 import { eq } from '@cardstack/boxel-ui/helpers';
 
 import {
+  extractMermaidBlocks,
   hasCodeBlocks,
   markdownToHtml,
   preloadMarkdownLanguages,
+  processKatexPlaceholders,
+  replaceMermaidSvgs,
   resolveCardReference,
   trimJsonExtension,
 } from '@cardstack/runtime-common';
-import { processKatexPlaceholders } from '@cardstack/runtime-common/bfm-math-render';
-import {
-  extractMermaidBlocks,
-  replaceMermaidSvgs,
-} from '@cardstack/runtime-common/bfm-mermaid-render';
 import { type BaseDef, type CardDef, getComponent } from '../card-api';
 import { CardContextConsumer } from '../field-component';
 function wrapTablesHtml(html: string | null | undefined): string {
diff --git a/packages/runtime-common/index.ts b/packages/runtime-common/index.ts
index 8a8a30c5c5a..9e9294a3350 100644
--- a/packages/runtime-common/index.ts
+++ b/packages/runtime-common/index.ts
@@ -243,6 +243,8 @@ export * from './catalog';
 export * from './commands';
 export * from './card-reference-resolver';
 export * from './bfm-card-references';
+export * from './bfm-math-render';
+export * from './bfm-mermaid-render';
 export * from './constants';
 export * from './helpers/const';
 export * from './document';

From 0d5b19e5a8190dc75df74123f7b54bb9be6d714a Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 12:34:14 -0400
Subject: [PATCH 34/50] Fix test: update heading id assertion to match
 user-content- prefix

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/tests/unit/bfm-card-references-test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/host/tests/unit/bfm-card-references-test.ts b/packages/host/tests/unit/bfm-card-references-test.ts
index 854f0489412..8c83eb98b17 100644
--- a/packages/host/tests/unit/bfm-card-references-test.ts
+++ b/packages/host/tests/unit/bfm-card-references-test.ts
@@ -237,7 +237,7 @@ module('Unit | bfm-card-references', function () {
     test('markdown without card refs is unaffected', function (assert) {
       let markdown = '# Hello\n\nSome **bold** text.';
       let withBfm = markdownToHtml(markdown);
-      assert.true(withBfm.includes('<h1 id="hello">Hello</h1>'));
+      assert.true(withBfm.includes('<h1 id="user-content-hello">Hello</h1>'));
       assert.true(withBfm.includes('<strong>bold</strong>'));
       assert.false(withBfm.includes('data-boxel-bfm'));
     });

From 9a67165942227a475154dde02102cbc8d23bdc17 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 13:01:58 -0400
Subject: [PATCH 35/50] Fix tests: update all heading id assertions to match
 user-content- prefix

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/tests/unit/marked-sync-test.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/host/tests/unit/marked-sync-test.ts b/packages/host/tests/unit/marked-sync-test.ts
index 200802f9ec1..e2aa807d03e 100644
--- a/packages/host/tests/unit/marked-sync-test.ts
+++ b/packages/host/tests/unit/marked-sync-test.ts
@@ -11,7 +11,7 @@ module('Unit | marked-sync', function () {
     const result = markedSync(markdown);
 
     assert.true(
-      result.includes('<h1 id="hello">Hello</h1>'),
+      result.includes('<h1 id="user-content-hello">Hello</h1>'),
       'converts heading correctly (with auto-generated id)',
     );
     assert.true(
@@ -46,7 +46,7 @@ module('Unit | marked-sync', function () {
     const markdown = '# Hello <script>alert("XSS")</script>';
     const result = markdownToHtml(markdown);
 
-    assert.true(result.includes('id="hello-'), 'heading has auto-generated id');
+    assert.true(result.includes('id="user-content-hello-'), 'heading has auto-generated id');
     assert.true(
       result.includes('>Hello </h1>'),
       'heading content was preserved',
@@ -302,7 +302,7 @@ module('Unit | marked-sync', function () {
     const result = markedSync(markdown);
 
     assert.true(
-      result.includes('id="my-section-title"'),
+      result.includes('id="user-content-my-section-title"'),
       'heading has a slug-based id attribute',
     );
   });
@@ -346,7 +346,7 @@ module('Unit | marked-sync', function () {
     const result = markdownToHtml(markdown);
 
     assert.true(
-      result.includes('id="test-heading"'),
+      result.includes('id="user-content-test-heading"'),
       'heading ID survives DOMPurify sanitization',
     );
   });

From f6da55dd91de09783e8a9fc3c19b51c2930fc5b2 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 13:10:45 -0400
Subject: [PATCH 36/50] Fix prettier formatting in marked-sync test

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/tests/unit/marked-sync-test.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/host/tests/unit/marked-sync-test.ts b/packages/host/tests/unit/marked-sync-test.ts
index e2aa807d03e..d994cb1b83a 100644
--- a/packages/host/tests/unit/marked-sync-test.ts
+++ b/packages/host/tests/unit/marked-sync-test.ts
@@ -46,7 +46,10 @@ module('Unit | marked-sync', function () {
     const markdown = '# Hello <script>alert("XSS")</script>';
     const result = markdownToHtml(markdown);
 
-    assert.true(result.includes('id="user-content-hello-'), 'heading has auto-generated id');
+    assert.true(
+      result.includes('id="user-content-hello-'),
+      'heading has auto-generated id',
+    );
     assert.true(
       result.includes('>Hello </h1>'),
       'heading content was preserved',

From e08d7724f62dc24610e8dde40ef9fdceab4c20ef Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 13:26:24 -0400
Subject: [PATCH 37/50] Fix prettier formatting in marked-gfm-heading-id type
 declaration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/runtime-common/global.d.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/runtime-common/global.d.ts b/packages/runtime-common/global.d.ts
index d1b3c13ca21..0d807d5e6ef 100644
--- a/packages/runtime-common/global.d.ts
+++ b/packages/runtime-common/global.d.ts
@@ -15,9 +15,7 @@ declare module '@babel/plugin-transform-typescript' {
 
 declare module 'marked-gfm-heading-id' {
   import type { MarkedExtension } from 'marked';
-  export function gfmHeadingId(options?: {
-    prefix?: string;
-  }): MarkedExtension;
+  export function gfmHeadingId(options?: { prefix?: string }): MarkedExtension;
   export interface HeadingData {
     level: number;
     text: string;

From 861cc4c81c17f0e3f739c7a8d58cf971ff973d0e Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 13:37:23 -0400
Subject: [PATCH 38/50] Fix CI: add marked-gfm-heading-id types to local-types
 directly

The declaration in runtime-common/global.d.ts wasn't being resolved on
CI due to pnpm's module layout differing from the local workspace. Add
the declaration directly to local-types where all packages find it.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/local-types/index.d.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/local-types/index.d.ts b/packages/local-types/index.d.ts
index 44340163048..a1ca300da4c 100644
--- a/packages/local-types/index.d.ts
+++ b/packages/local-types/index.d.ts
@@ -119,4 +119,16 @@ declare module '@ember/routing' {
 // incorporate
 import '../../runtime-common/global';
 
+declare module 'marked-gfm-heading-id' {
+  import type { MarkedExtension } from 'marked';
+  export function gfmHeadingId(options?: { prefix?: string }): MarkedExtension;
+  export interface HeadingData {
+    level: number;
+    text: string;
+    id: string;
+  }
+  export function getHeadingList(): HeadingData[];
+  export function resetHeadings(): void;
+}
+
 import './matrix-js-sdk';

From 8a7796fb0dd8fcc7fe77f907454092a0d4c69432 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 14:07:36 -0400
Subject: [PATCH 39/50] Fix CI: move marked-gfm-heading-id types to standalone
 ambient file

The declare module in local-types/index.d.ts was treated as a module
augmentation (not an ambient declaration) because index.d.ts has
top-level imports making it a module. Ambient declarations must live
in script files with no top-level import/export.

Created a separate marked-gfm-heading-id.d.ts with only the declare
module block (using import() type expressions to avoid top-level
imports), following the same pattern as matrix-js-sdk.d.ts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/local-types/index.d.ts                 | 12 +-----------
 packages/local-types/marked-gfm-heading-id.d.ts | 12 ++++++++++++
 packages/runtime-common/global.d.ts             | 12 ------------
 3 files changed, 13 insertions(+), 23 deletions(-)
 create mode 100644 packages/local-types/marked-gfm-heading-id.d.ts

diff --git a/packages/local-types/index.d.ts b/packages/local-types/index.d.ts
index a1ca300da4c..39252b3a237 100644
--- a/packages/local-types/index.d.ts
+++ b/packages/local-types/index.d.ts
@@ -119,16 +119,6 @@ declare module '@ember/routing' {
 // incorporate
 import '../../runtime-common/global';
 
-declare module 'marked-gfm-heading-id' {
-  import type { MarkedExtension } from 'marked';
-  export function gfmHeadingId(options?: { prefix?: string }): MarkedExtension;
-  export interface HeadingData {
-    level: number;
-    text: string;
-    id: string;
-  }
-  export function getHeadingList(): HeadingData[];
-  export function resetHeadings(): void;
-}
+import './marked-gfm-heading-id';
 
 import './matrix-js-sdk';
diff --git a/packages/local-types/marked-gfm-heading-id.d.ts b/packages/local-types/marked-gfm-heading-id.d.ts
new file mode 100644
index 00000000000..9fed2e03dfd
--- /dev/null
+++ b/packages/local-types/marked-gfm-heading-id.d.ts
@@ -0,0 +1,12 @@
+declare module 'marked-gfm-heading-id' {
+  export function gfmHeadingId(
+    options?: { prefix?: string },
+  ): import('marked').MarkedExtension;
+  export interface HeadingData {
+    level: number;
+    text: string;
+    id: string;
+  }
+  export function getHeadingList(): HeadingData[];
+  export function resetHeadings(): void;
+}
diff --git a/packages/runtime-common/global.d.ts b/packages/runtime-common/global.d.ts
index 0d807d5e6ef..b5e143df7bc 100644
--- a/packages/runtime-common/global.d.ts
+++ b/packages/runtime-common/global.d.ts
@@ -12,15 +12,3 @@ declare module '@babel/plugin-transform-typescript' {
   import type * as Babel from '@babel/core';
   export default function makePlugin(babel: typeof Babel): Babel.PluginObj;
 }
-
-declare module 'marked-gfm-heading-id' {
-  import type { MarkedExtension } from 'marked';
-  export function gfmHeadingId(options?: { prefix?: string }): MarkedExtension;
-  export interface HeadingData {
-    level: number;
-    text: string;
-    id: string;
-  }
-  export function getHeadingList(): HeadingData[];
-  export function resetHeadings(): void;
-}

From 652e202bb5ba54379245d4235933a29316a268eb Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 14:55:37 -0400
Subject: [PATCH 40/50] Fix CI: use require() for marked-alert and
 marked-footnote

These packages declare "type": "module" which triggers TS1479 under
Node16/nodenext module resolution since runtime-common lacks
"type": "module". Use require() with type assertions, matching the
existing pattern for marked-extended-tables.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/runtime-common/marked-sync.ts | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/runtime-common/marked-sync.ts b/packages/runtime-common/marked-sync.ts
index 00979551b13..a09bd535047 100644
--- a/packages/runtime-common/marked-sync.ts
+++ b/packages/runtime-common/marked-sync.ts
@@ -2,11 +2,14 @@ import { marked } from 'marked';
 import { sanitizeHtml } from './dompurify-runtime';
 import { escapeHtml } from './helpers/html';
 import { bfmCardReferenceExtensions } from './bfm-card-references';
-import markedAlert from 'marked-alert';
-import markedFootnote from 'marked-footnote';
 import { markedKatexPlaceholder } from './bfm-math';
 /* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires */
-// marked-extended-tables's ESM export isn't resolved by webpack; load via CJS.
+// These packages declare "type": "module" which causes TS1479 under Node16
+// module resolution (runtime-common lacks "type": "module"). Load via CJS.
+const markedAlert =
+  require('marked-alert') as (opts?: object) => import('marked').MarkedExtension;
+const markedFootnote =
+  require('marked-footnote') as (opts?: object) => import('marked').MarkedExtension;
 const markedExtendedTables =
   require('marked-extended-tables/lib/index.cjs') as () => import('marked').MarkedExtension;
 /* eslint-enable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires */

From 9c548d27d6317ebe7d7385891916fcdef7974e60 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Sun, 5 Apr 2026 15:11:16 -0400
Subject: [PATCH 41/50] Fix prettier formatting for marked-alert and
 marked-footnote requires

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/runtime-common/marked-sync.ts | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/runtime-common/marked-sync.ts b/packages/runtime-common/marked-sync.ts
index a09bd535047..a7601457597 100644
--- a/packages/runtime-common/marked-sync.ts
+++ b/packages/runtime-common/marked-sync.ts
@@ -6,10 +6,12 @@ import { markedKatexPlaceholder } from './bfm-math';
 /* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires */
 // These packages declare "type": "module" which causes TS1479 under Node16
 // module resolution (runtime-common lacks "type": "module"). Load via CJS.
-const markedAlert =
-  require('marked-alert') as (opts?: object) => import('marked').MarkedExtension;
-const markedFootnote =
-  require('marked-footnote') as (opts?: object) => import('marked').MarkedExtension;
+const markedAlert = require('marked-alert') as (
+  opts?: object,
+) => import('marked').MarkedExtension;
+const markedFootnote = require('marked-footnote') as (
+  opts?: object,
+) => import('marked').MarkedExtension;
 const markedExtendedTables =
   require('marked-extended-tables/lib/index.cjs') as () => import('marked').MarkedExtension;
 /* eslint-enable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires */

From fd90242181033ed591816f0d9b0ae0db72357197 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Mon, 6 Apr 2026 06:40:56 -0400
Subject: [PATCH 42/50] Fix memory leak: register marked code renderer once
 instead of per-call

marked.use({ renderer }) wraps the previous renderer in a new closure on
each call. Since markedSync() called use() on every invocation, this created
an ever-growing closure chain that leaked memory (~MB per test), eventually
crashing Chrome on CI. Fix by using a dedicated Marked instance with the
code renderer registered once at module load time.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/runtime-common/marked-sync.ts | 82 +++++++++++++++-----------
 1 file changed, 49 insertions(+), 33 deletions(-)

diff --git a/packages/runtime-common/marked-sync.ts b/packages/runtime-common/marked-sync.ts
index a7601457597..4311f8796d6 100644
--- a/packages/runtime-common/marked-sync.ts
+++ b/packages/runtime-common/marked-sync.ts
@@ -1,4 +1,4 @@
-import { marked } from 'marked';
+import { Marked } from 'marked';
 import { sanitizeHtml } from './dompurify-runtime';
 import { escapeHtml } from './helpers/html';
 import { bfmCardReferenceExtensions } from './bfm-card-references';
@@ -19,16 +19,53 @@ import { gfmHeadingId } from 'marked-gfm-heading-id';
 import type * as _MonacoSDK from 'monaco-editor';
 type MonacoSDK = typeof _MonacoSDK;
 
-// Register BFM card reference extensions globally. This is additive and does
-// not conflict with the per-call renderer override in markedSync().
-marked.use({ extensions: bfmCardReferenceExtensions() });
+// Use a dedicated Marked instance instead of the global singleton.
+// IMPORTANT: Do NOT call bfmMarked.use() inside markedSync() — each use()
+// call wraps the previous renderer in a new closure, creating an ever-growing
+// closure chain that leaks memory over many calls (e.g. during test runs).
+const bfmMarked = new Marked();
+
+// Register BFM card reference extensions.
+bfmMarked.use({ extensions: bfmCardReferenceExtensions() });
 
 // Register community marked extensions for BFM layers 3+ (GFM enhancements).
-marked.use(gfmHeadingId({ prefix: 'user-content-' }));
-marked.use(markedAlert());
-marked.use(markedFootnote());
-marked.use(markedExtendedTables());
-marked.use(markedKatexPlaceholder());
+bfmMarked.use(gfmHeadingId({ prefix: 'user-content-' }));
+bfmMarked.use(markedAlert());
+bfmMarked.use(markedFootnote());
+bfmMarked.use(markedExtendedTables());
+bfmMarked.use(markedKatexPlaceholder());
+
+// Per-call options for the code renderer. Set before each parse() call.
+// Safe because JS is single-threaded and parse() is synchronous.
+let _codeRenderOpts: {
+  escapeHtmlInCodeBlocks?: boolean;
+  enableMonacoSyntaxHighlighting?: boolean;
+  monacoTheme?: string;
+  monaco?: MonacoSDK | null;
+  tabSize?: number;
+} = {};
+
+// Register the code renderer ONCE to avoid closure chain accumulation.
+bfmMarked.use({
+  renderer: {
+    code(code: string, language = '') {
+      if (language === 'mermaid') {
+        return `<pre class="mermaid">${escapeHtml(code)}</pre>\n`;
+      }
+
+      let highlighted = renderWithMonaco(code, language, _codeRenderOpts);
+      if (highlighted) {
+        return highlighted;
+      }
+
+      if (_codeRenderOpts.escapeHtmlInCodeBlocks) {
+        return `<pre data-code-language="${escapeHtml(language)}">${escapeHtml(code)}</pre>`;
+      } else {
+        return `<pre data-code-language="${escapeHtml(language)}">${code}</pre>`;
+      }
+    },
+  },
+});
 
 const DECORATIVE_BULLET_PATTERN =
   // eslint-disable-next-line no-misleading-character-class -- match pictographic symbols plus a few geometric glyphs not covered by the Unicode class
@@ -116,31 +153,10 @@ export function markedSync(
     tabSize?: number;
   } = DEFAULT_MARKED_SYNC_OPTIONS,
 ): string {
-  let options = { ...DEFAULT_MARKED_SYNC_OPTIONS, ...opts };
-
-  return marked
-    .use({
-      renderer: {
-        code(code, language = '') {
-          // Mermaid blocks are rendered client-side; emit a placeholder.
-          if (language === 'mermaid') {
-            return `<pre class="mermaid">${escapeHtml(code)}</pre>\n`;
-          }
-
-          let highlighted = renderWithMonaco(code, language, options);
-          if (highlighted) {
-            return highlighted;
-          }
+  // Set per-call options for the code renderer (registered once above).
+  _codeRenderOpts = { ...DEFAULT_MARKED_SYNC_OPTIONS, ...opts };
 
-          if (options.escapeHtmlInCodeBlocks) {
-            return `<pre data-code-language="${escapeHtml(language)}">${escapeHtml(code)}</pre>`;
-          } else {
-            return `<pre data-code-language="${escapeHtml(language)}">${code}</pre>`;
-          }
-        },
-      },
-    })
-    .parse(markdown, { async: false }) as string;
+  return bfmMarked.parse(markdown, { async: false }) as string;
 }
 
 const DEFAULT_OPTS = {

From 652584c0038480d4d477d0240b380efdd33b2cde Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Mon, 6 Apr 2026 10:28:32 -0400
Subject: [PATCH 43/50] Fix ESM default export interop for marked extensions in
 esbuild bundle

esbuild (used by workspace-sync-cli) preserves ESM default exports as
{ default: fn } when bundling to CJS, unlike webpack which unwraps them.
Add unwrapDefault() helper to handle both bundlers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/runtime-common/marked-sync.ts | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/packages/runtime-common/marked-sync.ts b/packages/runtime-common/marked-sync.ts
index 4311f8796d6..fc3aca4a966 100644
--- a/packages/runtime-common/marked-sync.ts
+++ b/packages/runtime-common/marked-sync.ts
@@ -6,14 +6,23 @@ import { markedKatexPlaceholder } from './bfm-math';
 /* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires */
 // These packages declare "type": "module" which causes TS1479 under Node16
 // module resolution (runtime-common lacks "type": "module"). Load via CJS.
-const markedAlert = require('marked-alert') as (
+// Unwrap .default for ESM default exports — webpack unwraps automatically but
+// esbuild (used by workspace-sync-cli) preserves the { default: fn } wrapper.
+type MarkedExtensionFactory = (
   opts?: object,
 ) => import('marked').MarkedExtension;
-const markedFootnote = require('marked-footnote') as (
-  opts?: object,
-) => import('marked').MarkedExtension;
-const markedExtendedTables =
-  require('marked-extended-tables/lib/index.cjs') as () => import('marked').MarkedExtension;
+function unwrapDefault<T>(mod: T | { default: T }): T {
+  return (mod as { default: T }).default ?? (mod as T);
+}
+const markedAlert = unwrapDefault(
+  require('marked-alert'),
+) as MarkedExtensionFactory;
+const markedFootnote = unwrapDefault(
+  require('marked-footnote'),
+) as MarkedExtensionFactory;
+const markedExtendedTables = unwrapDefault(
+  require('marked-extended-tables/lib/index.cjs'),
+) as () => import('marked').MarkedExtension;
 /* eslint-enable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires */
 import { gfmHeadingId } from 'marked-gfm-heading-id';
 import type * as _MonacoSDK from 'monaco-editor';

From 00639954944ce391149206c495e9638b053190ab Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Mon, 6 Apr 2026 14:29:55 -0400
Subject: [PATCH 44/50] Add RichMarkdownField composite FieldDef with
 linkedCards support

New composite FieldDef that stores markdown content and exposes structured
card relationships via query-based linkedCards. Includes integration tests
for markdown rendering, BFM card references, footnotes, and edit mode.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/rich-markdown.gts               |  94 ++++++++
 packages/host/tests/helpers/base-realm.ts     |  11 +
 .../components/rich-markdown-field-test.gts   | 218 ++++++++++++++++++
 3 files changed, 323 insertions(+)
 create mode 100644 packages/base/rich-markdown.gts
 create mode 100644 packages/host/tests/integration/components/rich-markdown-field-test.gts

diff --git a/packages/base/rich-markdown.gts b/packages/base/rich-markdown.gts
new file mode 100644
index 00000000000..2abd4e0f649
--- /dev/null
+++ b/packages/base/rich-markdown.gts
@@ -0,0 +1,94 @@
+import {
+  extractCardReferenceUrls,
+  relativeTo,
+} from '@cardstack/runtime-common';
+
+import {
+  CardDef,
+  Component,
+  FieldDef,
+  MarkdownField,
+  StringField,
+  contains,
+  containsMany,
+  field,
+  linksToMany,
+} from './card-api';
+import MarkdownTemplate from './default-templates/markdown';
+
+/**
+ * A composite FieldDef that stores markdown content and exposes structured
+ * `linkedCards` relationships for embedded card references.
+ *
+ * Unlike `MarkdownField` (which extends StringField), this field is a
+ * composite FieldDef with sub-fields for content, computed reference URLs,
+ * and query-based linked cards.
+ *
+ * Usage:
+ * ```
+ * import RichMarkdownField from 'https://cardstack.com/base/rich-markdown';
+ *
+ * class MyCard extends CardDef {
+ *   @field body = contains(RichMarkdownField);
+ * }
+ * ```
+ */
+export class RichMarkdownField extends FieldDef {
+  static displayName = 'Rich Markdown';
+
+  /** The raw markdown text. Uses MarkdownField for textarea edit UI. */
+  @field content = contains(MarkdownField);
+
+  /** Resolved absolute URLs of `:card[URL]` and `::card[URL]` references. */
+  @field cardReferenceUrls = containsMany(StringField, {
+    computeVia: function (this: RichMarkdownField) {
+      if (!this.content) {
+        return [];
+      }
+      let baseUrl = this[relativeTo]?.href ?? '';
+      return extractCardReferenceUrls(this.content, baseUrl);
+    },
+  });
+
+  /** Cards referenced in the markdown, loaded via query. */
+  @field linkedCards = linksToMany(CardDef, {
+    query: {
+      filter: {
+        in: { id: '$this.cardReferenceUrls' },
+      },
+    },
+  });
+
+  static embedded = class Embedded extends Component<typeof this> {
+    get content() {
+      return this.args.model?.content ?? null;
+    }
+    get baseUrl(): string | null {
+      return this.args.model?.[relativeTo]?.href ?? null;
+    }
+    <template>
+      <MarkdownTemplate
+        @content={{this.content}}
+        @linkedCards={{@model.linkedCards}}
+        @cardReferenceBaseUrl={{this.baseUrl}}
+      />
+    </template>
+  };
+
+  static atom = class Atom extends Component<typeof this> {
+    get content() {
+      return this.args.model?.content ?? null;
+    }
+    <template>
+      <MarkdownTemplate @content={{this.content}} />
+    </template>
+  };
+
+  static edit = class Edit extends Component<typeof this> {
+    <template>
+      <@fields.content />
+    </template>
+  };
+}
+
+export default RichMarkdownField;
diff --git a/packages/host/tests/helpers/base-realm.ts b/packages/host/tests/helpers/base-realm.ts
index 7e1073ebb40..265262224ef 100644
--- a/packages/host/tests/helpers/base-realm.ts
+++ b/packages/host/tests/helpers/base-realm.ts
@@ -21,6 +21,7 @@ import type * as RealmFieldModule from 'https://cardstack.com/base/realm';
 import type * as SkillModule from 'https://cardstack.com/base/skill';
 import type * as StringFieldModule from 'https://cardstack.com/base/string';
 import type * as SystemCardModule from 'https://cardstack.com/base/system-card';
+import type * as RichMarkdownModule from 'https://cardstack.com/base/rich-markdown';
 import type * as TextAreaFieldModule from 'https://cardstack.com/base/text-area';
 
 type StringField = (typeof StringFieldModule)['default'];
@@ -62,6 +63,9 @@ let TextAreaField: TextAreaField;
 type RealmField = (typeof RealmFieldModule)['default'];
 let RealmField: RealmField;
 
+type RichMarkdownField = (typeof RichMarkdownModule)['RichMarkdownField'];
+let RichMarkdownField: RichMarkdownField;
+
 type PhoneNumberField = (typeof PhoneNumberFieldModule)['default'];
 let PhoneNumberField: PhoneNumberField;
 
@@ -178,6 +182,12 @@ async function initialize() {
     await loader.import<typeof RealmFieldModule>(`${baseRealm.url}realm`)
   ).default;
 
+  RichMarkdownField = (
+    await loader.import<typeof RichMarkdownModule>(
+      `${baseRealm.url}rich-markdown`,
+    )
+  ).RichMarkdownField;
+
   PhoneNumberField = (
     await loader.import<typeof PhoneNumberFieldModule>(
       `${baseRealm.url}phone-number`,
@@ -266,6 +276,7 @@ export {
   MarkdownField,
   TextAreaField,
   RealmField,
+  RichMarkdownField,
   PhoneNumberField,
   CardsGrid,
   SystemCard,
diff --git a/packages/host/tests/integration/components/rich-markdown-field-test.gts b/packages/host/tests/integration/components/rich-markdown-field-test.gts
new file mode 100644
index 00000000000..fdd5203927c
--- /dev/null
+++ b/packages/host/tests/integration/components/rich-markdown-field-test.gts
@@ -0,0 +1,218 @@
+import type { RenderingTestContext } from '@ember/test-helpers';
+
+import { getService } from '@universal-ember/test-support';
+import { module, test } from 'qunit';
+
+import {
+  PermissionsContextName,
+  type Permissions,
+  baseRealm,
+} from '@cardstack/runtime-common';
+import type { Loader } from '@cardstack/runtime-common/loader';
+
+import {
+  cleanWhiteSpace,
+  provideConsumeContext,
+  setupCardLogs,
+  setupIntegrationTestRealm,
+  setupLocalIndexing,
+} from '../../helpers';
+import {
+  setupBaseRealm,
+  CardDef,
+  Component,
+  RichMarkdownField,
+  contains,
+  field,
+} from '../../helpers/base-realm';
+import { setupMockMatrix } from '../../helpers/mock-matrix';
+import { renderCard } from '../../helpers/render-component';
+import { setupRenderingTest } from '../../helpers/setup';
+
+let loader: Loader;
+
+module('Integration | RichMarkdownField', function (hooks) {
+  setupRenderingTest(hooks);
+
+  let mockMatrixUtils = setupMockMatrix(hooks);
+
+  setupBaseRealm(hooks);
+
+  hooks.beforeEach(function (this: RenderingTestContext) {
+    let permissions: Permissions = {
+      canWrite: true,
+      canRead: true,
+    };
+    provideConsumeContext(PermissionsContextName, permissions);
+    loader = getService('loader-service').loader;
+  });
+  setupLocalIndexing(hooks);
+
+  setupCardLogs(
+    hooks,
+    async () => await loader.import(`${baseRealm.url}card-api`),
+  );
+
+  test('renders markdown as HTML', async function (assert) {
+    class TestCard extends CardDef {
+      @field body = contains(RichMarkdownField);
+      static atom = class Atom extends Component<typeof this> {
+        <template><@fields.body /></template>
+      };
+    }
+
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'test-card.gts': { TestCard },
+      },
+    });
+
+    let card = new TestCard({
+      body: new RichMarkdownField({
+        content: '# Hello World\n\nSome **bold** text.',
+      }),
+    });
+    let root = await renderCard(loader, card, 'atom');
+    assert.dom(root.querySelector('h1')).hasText('Hello World');
+    assert.dom(root.querySelector('strong')).hasText('bold');
+  });
+
+  test('edit template renders textarea for content', async function (assert) {
+    class TestCard extends CardDef {
+      @field body = contains(RichMarkdownField);
+      static edit = class Edit extends Component<typeof this> {
+        <template><@fields.body /></template>
+      };
+    }
+
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'test-card.gts': { TestCard },
+      },
+    });
+
+    let card = new TestCard({
+      body: new RichMarkdownField({ content: 'Edit me' }),
+    });
+    let root = await renderCard(loader, card, 'edit');
+    assert.dom(root.querySelector('textarea')).exists('textarea is rendered');
+    assert.dom(root.querySelector('textarea')).hasValue('Edit me');
+  });
+
+  test('renders with null content without error', async function (assert) {
+    class TestCard extends CardDef {
+      @field body = contains(RichMarkdownField);
+      static edit = class Edit extends Component<typeof this> {
+        <template><@fields.body /></template>
+      };
+    }
+
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'test-card.gts': { TestCard },
+      },
+    });
+
+    let card = new TestCard();
+    let root = await renderCard(loader, card, 'edit');
+    assert.dom(root).exists('renders without error');
+  });
+
+  test('renders inline :card references as BFM elements', async function (assert) {
+    class TestCard extends CardDef {
+      @field body = contains(RichMarkdownField);
+      static atom = class Atom extends Component<typeof this> {
+        <template><@fields.body /></template>
+      };
+    }
+
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'test-card.gts': { TestCard },
+      },
+    });
+
+    let card = new TestCard({
+      body: new RichMarkdownField({
+        content: 'See :card[https://example.com/cards/1] for details.',
+      }),
+    });
+    let root = await renderCard(loader, card, 'atom');
+    assert
+      .dom(root.querySelector('[data-boxel-bfm-inline-ref]'))
+      .exists('inline card reference is rendered as BFM element');
+    assert
+      .dom(root.querySelector('[data-boxel-bfm-inline-ref]'))
+      .hasAttribute(
+        'data-boxel-bfm-inline-ref',
+        'https://example.com/cards/1',
+      );
+  });
+
+  test('renders block ::card references as BFM elements', async function (assert) {
+    class TestCard extends CardDef {
+      @field body = contains(RichMarkdownField);
+      static atom = class Atom extends Component<typeof this> {
+        <template><@fields.body /></template>
+      };
+    }
+
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'test-card.gts': { TestCard },
+      },
+    });
+
+    let card = new TestCard({
+      body: new RichMarkdownField({
+        content: '::card[https://example.com/cards/2]\n',
+      }),
+    });
+    let root = await renderCard(loader, card, 'atom');
+    assert
+      .dom(root.querySelector('[data-boxel-bfm-block-ref]'))
+      .exists('block card reference is rendered as BFM element');
+    assert
+      .dom(root.querySelector('[data-boxel-bfm-block-ref]'))
+      .hasAttribute(
+        'data-boxel-bfm-block-ref',
+        'https://example.com/cards/2',
+      );
+  });
+
+  test('renders footnotes', async function (assert) {
+    class TestCard extends CardDef {
+      @field body = contains(RichMarkdownField);
+      static atom = class Atom extends Component<typeof this> {
+        <template><@fields.body /></template>
+      };
+    }
+
+    await setupIntegrationTestRealm({
+      mockMatrixUtils,
+      contents: {
+        'test-card.gts': { TestCard },
+      },
+    });
+
+    let card = new TestCard({
+      body: new RichMarkdownField({
+        content:
+          'Text with a footnote[^1].\n\n[^1]: This is the footnote content.',
+      }),
+    });
+    let root = await renderCard(loader, card, 'atom');
+    assert
+      .dom(root.querySelector('.footnotes'))
+      .exists('footnote section is rendered');
+    assert.ok(
+      root.textContent!.includes('This is the footnote content'),
+      'footnote content is present',
+    );
+  });
+});

From d5ccebb4ffbfe8969caab76221d85f165a607942 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Tue, 7 Apr 2026 14:45:53 -0400
Subject: [PATCH 45/50] Add ProseMirror WYSIWYG editor for RichMarkdownField
 (CS-10572)

Integrate ProseMirror as a platform feature for rich markdown editing,
following the established lazy-loading pattern used by KaTeX, Mermaid,
and Monaco.

New files:
- packages/host/app/lib/prosemirror-context.ts: lazy-loaded module with
  ProseMirror schema (doc, paragraph, heading, blockquote, code_block,
  lists, hr, hard_break, card atom/block placeholders), marks (strong,
  em, code, link), markdown parser, and markdown serializer
- packages/base/prosemirror-editor.gts: Glimmer component with
  ember-concurrency lazy loading, ember-modifier for EditorView
  mounting, keyboard bindings, debounced onUpdate, and scoped CSS
- packages/host/tests/integration/components/prosemirror-editor-test.gts:
  25 tests covering schema, parsing, serialization, round-trip,
  EditorView mounting, card placeholder rendering, and lazy loading

Modified files:
- packages/host/app/routes/application.ts: register __loadProseMirror
- packages/base/rich-markdown.gts: use ProseMirrorEditor in edit mode
- pnpm-workspace.yaml + packages/host/package.json: add prosemirror-*
  dependencies

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/prosemirror-editor.gts          | 351 ++++++++++
 packages/base/rich-markdown.gts               |   9 +-
 packages/host/app/lib/prosemirror-context.ts  | 661 ++++++++++++++++++
 packages/host/app/routes/application.ts       |   9 +
 packages/host/package.json                    |   7 +
 .../components/prosemirror-editor-test.gts    | 383 ++++++++++
 pnpm-lock.yaml                                | 125 ++++
 pnpm-workspace.yaml                           |   7 +
 8 files changed, 1551 insertions(+), 1 deletion(-)
 create mode 100644 packages/base/prosemirror-editor.gts
 create mode 100644 packages/host/app/lib/prosemirror-context.ts
 create mode 100644 packages/host/tests/integration/components/prosemirror-editor-test.gts

diff --git a/packages/base/prosemirror-editor.gts b/packages/base/prosemirror-editor.gts
new file mode 100644
index 00000000000..5638def8a58
--- /dev/null
+++ b/packages/base/prosemirror-editor.gts
@@ -0,0 +1,351 @@
+import { task } from 'ember-concurrency';
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { modifier } from 'ember-modifier';
+
+// The ProseMirrorContext 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
+// globalThis.__loadProseMirror.
+interface ProseMirrorContext {
+  schema: any;
+  EditorState: any;
+  EditorView: any;
+  keymap: (bindings: Record<string, any>) => any;
+  baseKeymap: Record<string, any>;
+  history: () => any;
+  undo: any;
+  redo: any;
+  toggleMark: (markType: any) => any;
+  setBlockType: (nodeType: any, attrs?: any) => any;
+  wrapIn: (nodeType: any) => any;
+  lift: any;
+  wrapInList: (listType: any) => any;
+  splitListItem: (itemType: any) => any;
+  liftListItem: (itemType: any) => any;
+  sinkListItem: (itemType: any) => any;
+  parseMarkdown: (text: string) => any;
+  serializeMarkdown: (doc: any) => string;
+}
+
+const SAVE_DEBOUNCE_MS = 500;
+
+interface ProseMirrorEditorSignature {
+  Args: {
+    content: string | null;
+    onUpdate: (markdown: string) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEditorSignature> {
+  @tracked _pm: ProseMirrorContext | null = null;
+
+  get pm(): ProseMirrorContext | null {
+    if (!this._pm) {
+      this._loadProseMirrorTask.perform();
+    }
+    return this._pm;
+  }
+
+  _loadProseMirrorTask = task({ drop: true }, async () => {
+    let loadProseMirror = (globalThis as any).__loadProseMirror;
+    if (typeof loadProseMirror !== 'function') {
+      return;
+    }
+    this._pm = await loadProseMirror();
+  });
+
+  private editorView: any = null;
+  private lastExternalContent: string | null = null;
+  private saveTimer: ReturnType<typeof setTimeout> | null = null;
+
+  mountEditor = modifier(
+    (element: HTMLElement, _positional: unknown[]) => {
+      let pm = this._pm;
+      if (!pm) {
+        return;
+      }
+
+      let content = this.args.content;
+      let onUpdate = this.args.onUpdate;
+
+      // If editor already exists and content hasn't changed externally, keep it
+      if (
+        this.editorView &&
+        element.contains(this.editorView.dom) &&
+        content === this.lastExternalContent
+      ) {
+        return;
+      }
+
+      // External content changed — destroy old editor
+      if (this.editorView && content !== this.lastExternalContent) {
+        this.editorView.destroy();
+        this.editorView = null;
+      }
+
+      this.lastExternalContent = content;
+
+      // Clear element before creating editor
+      element.innerHTML = '';
+
+      let doc = pm.parseMarkdown(content || '');
+
+      let {
+        schema,
+        keymap: keymapPlugin,
+        baseKeymap,
+        history,
+        undo,
+        redo,
+        toggleMark,
+        splitListItem,
+        liftListItem,
+        sinkListItem,
+      } = pm;
+
+      let formatKeymap = {
+        'Mod-b': toggleMark(schema.marks.strong),
+        'Mod-i': toggleMark(schema.marks.em),
+        'Mod-`': toggleMark(schema.marks.code),
+        'Mod-z': undo,
+        'Shift-Mod-z': redo,
+      };
+
+      let listKeymap = {
+        Enter: splitListItem(schema.nodes.list_item),
+        Tab: sinkListItem(schema.nodes.list_item),
+        'Shift-Tab': liftListItem(schema.nodes.list_item),
+      };
+
+      let state = pm.EditorState.create({
+        doc,
+        plugins: [
+          keymapPlugin(formatKeymap),
+          keymapPlugin(listKeymap),
+          keymapPlugin(baseKeymap),
+          history(),
+        ],
+      });
+
+      let view = new pm.EditorView(element, {
+        state,
+        dispatchTransaction: (tr: any) => {
+          let newState = view.state.apply(tr);
+          view.updateState(newState);
+
+          if (tr.docChanged && onUpdate) {
+            // Debounced save
+            if (this.saveTimer) {
+              clearTimeout(this.saveTimer);
+            }
+            this.saveTimer = setTimeout(() => {
+              this.saveTimer = null;
+              let markdown = pm!.serializeMarkdown(view.state.doc);
+              onUpdate(markdown);
+            }, SAVE_DEBOUNCE_MS);
+          }
+        },
+      });
+
+      this.editorView = view;
+
+      return () => {
+        if (this.saveTimer) {
+          clearTimeout(this.saveTimer);
+          this.saveTimer = null;
+        }
+        if (this.editorView) {
+          this.editorView.destroy();
+          this.editorView = null;
+        }
+      };
+    },
+  );
+
+  // ── Block-level commands (exposed for future toolbar use) ──
+
+  setHeading = (level: number) => {
+    let pm = this._pm;
+    let view = this.editorView;
+    if (!pm || !view) return;
+    pm.setBlockType(pm.schema.nodes.heading, { level })(
+      view.state,
+      view.dispatch,
+    );
+    view.focus();
+  };
+
+  setParagraph = () => {
+    let pm = this._pm;
+    let view = this.editorView;
+    if (!pm || !view) return;
+    pm.setBlockType(pm.schema.nodes.paragraph)(view.state, view.dispatch);
+    view.focus();
+  };
+
+  toggleBulletList = () => {
+    let pm = this._pm;
+    let view = this.editorView;
+    if (!pm || !view) return;
+    pm.wrapInList(pm.schema.nodes.bullet_list)(view.state, view.dispatch);
+    view.focus();
+  };
+
+  toggleOrderedList = () => {
+    let pm = this._pm;
+    let view = this.editorView;
+    if (!pm || !view) return;
+    pm.wrapInList(pm.schema.nodes.ordered_list)(view.state, view.dispatch);
+    view.focus();
+  };
+
+  toggleBlockquote = () => {
+    let pm = this._pm;
+    let view = this.editorView;
+    if (!pm || !view) return;
+    pm.wrapIn(pm.schema.nodes.blockquote)(view.state, view.dispatch);
+    view.focus();
+  };
+
+  insertHorizontalRule = () => {
+    let pm = this._pm;
+    let view = this.editorView;
+    if (!pm || !view) return;
+    let { tr } = view.state;
+    view.dispatch(
+      tr.replaceSelectionWith(pm.schema.nodes.horizontal_rule.create()),
+    );
+    view.focus();
+  };
+
+  liftBlock = () => {
+    let pm = this._pm;
+    let view = this.editorView;
+    if (!pm || !view) return;
+    pm.lift(view.state, view.dispatch);
+    view.focus();
+  };
+
+  <template>
+    {{#if this.pm}}
+      <div
+        class='prosemirror-editor'
+        data-test-prosemirror-editor
+        {{this.mountEditor this.pm this.args.content this.args.onUpdate}}
+        ...attributes
+      >
+      </div>
+    {{else}}
+      <div class='prosemirror-editor-loading' data-test-prosemirror-loading>
+        Loading editor…
+      </div>
+    {{/if}}
+    <style scoped>
+      @layer baseComponent {
+        .prosemirror-editor {
+          min-height: 120px;
+          padding: var(--boxel-sp-xs);
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          cursor: text;
+        }
+
+        .prosemirror-editor :deep(.ProseMirror) {
+          outline: none;
+          min-height: 100px;
+          font-family: inherit;
+          font-size: inherit;
+          line-height: 1.6;
+        }
+
+        .prosemirror-editor :deep(.ProseMirror p) {
+          margin-top: var(--boxel-sp-xs, 4px);
+          margin-bottom: var(--boxel-sp-xs, 4px);
+        }
+
+        .prosemirror-editor :deep(.ProseMirror h1),
+        .prosemirror-editor :deep(.ProseMirror h2),
+        .prosemirror-editor :deep(.ProseMirror h3),
+        .prosemirror-editor :deep(.ProseMirror h4),
+        .prosemirror-editor :deep(.ProseMirror h5),
+        .prosemirror-editor :deep(.ProseMirror h6) {
+          font-weight: 600;
+        }
+
+        .prosemirror-editor :deep(.ProseMirror blockquote) {
+          border-left: 3px solid var(--boxel-border-color, #c4c4c4);
+          padding-left: var(--boxel-sp, 16px);
+          margin-left: 0;
+          margin-right: 0;
+          color: var(--boxel-400, #666);
+        }
+
+        .prosemirror-editor :deep(.ProseMirror pre) {
+          background-color: var(--boxel-100, #f5f5f5);
+          padding: var(--boxel-sp-sm, 8px);
+          border-radius: var(--boxel-border-radius, 4px);
+          font-family: var(--boxel-monospace-font-family, monospace);
+          overflow-x: auto;
+        }
+
+        .prosemirror-editor :deep(.ProseMirror code) {
+          background-color: var(--boxel-100, #f5f5f5);
+          padding: 0.1em 0.3em;
+          border-radius: 3px;
+          font-family: var(--boxel-monospace-font-family, monospace);
+          font-size: 0.9em;
+        }
+
+        .prosemirror-editor :deep(.ProseMirror ul),
+        .prosemirror-editor :deep(.ProseMirror ol) {
+          padding-left: 1.375em;
+        }
+
+        .prosemirror-editor :deep(.ProseMirror hr) {
+          border: none;
+          border-top: 1px solid var(--boxel-border-color, #c4c4c4);
+          margin: var(--boxel-sp, 16px) 0;
+        }
+
+        /* Card node placeholders */
+        .prosemirror-editor :deep(.boxel-card-atom) {
+          display: inline-flex;
+          align-items: center;
+          gap: 4px;
+          background-color: var(--boxel-100, #f0f0f0);
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          padding: 1px 6px;
+          font-size: 0.85em;
+          cursor: default;
+        }
+
+        .prosemirror-editor :deep(.boxel-card-block) {
+          display: block;
+          background-color: var(--boxel-100, #f0f0f0);
+          border: 1px dashed var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          padding: var(--boxel-sp-sm, 8px);
+          margin: var(--boxel-sp-xs, 4px) 0;
+          cursor: default;
+        }
+
+        .prosemirror-editor :deep(.card-block-id) {
+          font-size: 0.85em;
+          color: var(--boxel-400, #666);
+          word-break: break-all;
+        }
+
+        .prosemirror-editor-loading {
+          min-height: 120px;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          color: var(--boxel-400, #999);
+          font-style: italic;
+        }
+      }
+    </style>
+  </template>
+}
diff --git a/packages/base/rich-markdown.gts b/packages/base/rich-markdown.gts
index 2abd4e0f649..a85ade78254 100644
--- a/packages/base/rich-markdown.gts
+++ b/packages/base/rich-markdown.gts
@@ -15,6 +15,7 @@ import {
   linksToMany,
 } from './card-api';
 import MarkdownTemplate from './default-templates/markdown';
+import ProseMirrorEditor from './prosemirror-editor';
 
 /**
  * A composite FieldDef that stores markdown content and exposes structured
@@ -85,8 +86,14 @@ export class RichMarkdownField extends FieldDef {
   };
 
   static edit = class Edit extends Component<typeof this> {
+    updateContent = (markdown: string) => {
+      this.args.model.content = markdown;
+    };
     <template>
-      <@fields.content />
+      <ProseMirrorEditor
+        @content={{@model.content}}
+        @onUpdate={{this.updateContent}}
+      />
     </template>
   };
 }
diff --git a/packages/host/app/lib/prosemirror-context.ts b/packages/host/app/lib/prosemirror-context.ts
new file mode 100644
index 00000000000..50c3e2caa73
--- /dev/null
+++ b/packages/host/app/lib/prosemirror-context.ts
@@ -0,0 +1,661 @@
+/**
+ * ProseMirror context module — lazy-loaded via globalThis.__loadProseMirror.
+ *
+ * This module is the single dynamic-import entry point for ProseMirror.
+ * Webpack will code-split it (and all its transitive deps) into a separate
+ * chunk automatically. The base package's ProseMirrorEditor component
+ * consumes the exported context object.
+ */
+
+import 'prosemirror-view/style/prosemirror.css';
+
+import { Schema } from 'prosemirror-model';
+import type { Node as ProseMirrorNode } from 'prosemirror-model';
+import { EditorState } from 'prosemirror-state';
+import { EditorView } from 'prosemirror-view';
+import { keymap } from 'prosemirror-keymap';
+import { baseKeymap, toggleMark, setBlockType, lift } from 'prosemirror-commands';
+import {
+  wrapInList,
+  splitListItem,
+  liftListItem,
+  sinkListItem,
+} from 'prosemirror-schema-list';
+import { history, undo, redo } from 'prosemirror-history';
+import { wrapIn } from 'prosemirror-commands';
+
+// ── Schema ──────────────────────────────────────────────────────────────────
+
+const schema = new Schema({
+  nodes: {
+    doc: { content: 'block+' },
+
+    paragraph: {
+      content: 'inline*',
+      group: 'block',
+      parseDOM: [{ tag: 'p' }],
+      toDOM() {
+        return ['p', 0];
+      },
+    },
+
+    heading: {
+      attrs: { level: { default: 1 } },
+      content: 'inline*',
+      group: 'block',
+      defining: true,
+      parseDOM: [1, 2, 3, 4, 5, 6].map((level) => ({
+        tag: `h${level}`,
+        attrs: { level },
+      })),
+      toDOM(node) {
+        return [`h${node.attrs.level}`, 0];
+      },
+    },
+
+    blockquote: {
+      content: 'block+',
+      group: 'block',
+      defining: true,
+      parseDOM: [{ tag: 'blockquote' }],
+      toDOM() {
+        return ['blockquote', 0];
+      },
+    },
+
+    code_block: {
+      attrs: { info: { default: '' } },
+      content: 'text*',
+      marks: '',
+      group: 'block',
+      code: true,
+      defining: true,
+      parseDOM: [
+        {
+          tag: 'pre',
+          preserveWhitespace: 'full' as const,
+          getAttrs(dom: HTMLElement) {
+            return { info: dom.getAttribute('data-fence-info') || '' };
+          },
+        },
+      ],
+      toDOM(node) {
+        return node.attrs.info
+          ? ['pre', { 'data-fence-info': node.attrs.info }, ['code', 0]]
+          : ['pre', ['code', 0]];
+      },
+    },
+
+    bullet_list: {
+      content: 'list_item+',
+      group: 'block',
+      parseDOM: [{ tag: 'ul' }],
+      toDOM() {
+        return ['ul', 0];
+      },
+    },
+
+    ordered_list: {
+      content: 'list_item+',
+      group: 'block',
+      attrs: { order: { default: 1 } },
+      parseDOM: [
+        {
+          tag: 'ol',
+          getAttrs(dom: HTMLElement) {
+            return { order: dom.getAttribute('start') || 1 };
+          },
+        },
+      ],
+      toDOM(node) {
+        return node.attrs.order === 1
+          ? ['ol', 0]
+          : ['ol', { start: node.attrs.order }, 0];
+      },
+    },
+
+    list_item: {
+      content: 'paragraph block*',
+      defining: true,
+      parseDOM: [{ tag: 'li' }],
+      toDOM() {
+        return ['li', 0];
+      },
+    },
+
+    horizontal_rule: {
+      group: 'block',
+      parseDOM: [{ tag: 'hr' }],
+      toDOM() {
+        return ['hr'];
+      },
+    },
+
+    hard_break: {
+      inline: true,
+      group: 'inline',
+      selectable: false,
+      parseDOM: [{ tag: 'br' }],
+      toDOM() {
+        return ['br'];
+      },
+    },
+
+    text: { group: 'inline' },
+
+    // ── Custom card placeholder nodes ──
+
+    boxel_card_atom: {
+      attrs: {
+        cardId: {},
+        label: { default: '' },
+      },
+      inline: true,
+      group: 'inline',
+      atom: true,
+      draggable: true,
+      parseDOM: [
+        {
+          tag: 'span[data-boxel-card-atom]',
+          getAttrs(dom: HTMLElement) {
+            return {
+              cardId: dom.getAttribute('data-card-id'),
+              label: dom.getAttribute('data-label') || dom.textContent,
+            };
+          },
+        },
+      ],
+      toDOM(node) {
+        return [
+          'span',
+          {
+            'data-boxel-card-atom': '',
+            'data-card-id': node.attrs.cardId,
+            'data-label': node.attrs.label,
+            class: 'boxel-card-atom',
+          },
+          ['span', { class: 'atom-label' }, node.attrs.label || node.attrs.cardId],
+        ];
+      },
+    },
+
+    boxel_card_block: {
+      attrs: {
+        cardId: {},
+        format: { default: 'embedded' },
+        size: { default: 'full' },
+      },
+      group: 'block',
+      atom: true,
+      draggable: true,
+      parseDOM: [
+        {
+          tag: 'div[data-boxel-card-block]',
+          getAttrs(dom: HTMLElement) {
+            return {
+              cardId: dom.getAttribute('data-card-id'),
+              format: dom.getAttribute('data-format') || 'embedded',
+              size: dom.getAttribute('data-size') || 'full',
+            };
+          },
+        },
+      ],
+      toDOM(node) {
+        return [
+          'div',
+          {
+            'data-boxel-card-block': '',
+            'data-card-id': node.attrs.cardId,
+            'data-format': node.attrs.format,
+            'data-size': node.attrs.size,
+            class: `boxel-card-block format-${node.attrs.format}`,
+          },
+          ['div', { class: 'card-block-id' }, node.attrs.cardId],
+        ];
+      },
+    },
+  },
+
+  marks: {
+    strong: {
+      parseDOM: [
+        { tag: 'strong' },
+        {
+          tag: 'b',
+          getAttrs(node: HTMLElement) {
+            return node.style.fontWeight !== 'normal' && null;
+          },
+        },
+        {
+          style: 'font-weight=400',
+          clearMark(m: any) {
+            return m.type.name === 'strong';
+          },
+        },
+        {
+          style: 'font-weight',
+          getAttrs(value: string) {
+            return /^(bold(er)?|[5-9]\d{2,})$/.test(value) && null;
+          },
+        },
+      ],
+      toDOM() {
+        return ['strong', 0];
+      },
+    },
+
+    em: {
+      parseDOM: [{ tag: 'i' }, { tag: 'em' }, { style: 'font-style=italic' }],
+      toDOM() {
+        return ['em', 0];
+      },
+    },
+
+    code: {
+      parseDOM: [{ tag: 'code' }],
+      toDOM() {
+        return ['code', 0];
+      },
+    },
+
+    link: {
+      attrs: { href: {}, title: { default: null } },
+      inclusive: false,
+      parseDOM: [
+        {
+          tag: 'a[href]',
+          getAttrs(dom: HTMLElement) {
+            return {
+              href: dom.getAttribute('href'),
+              title: dom.getAttribute('title'),
+            };
+          },
+        },
+      ],
+      toDOM(node) {
+        return [
+          'a',
+          { href: node.attrs.href, title: node.attrs.title },
+          0,
+        ];
+      },
+    },
+  },
+});
+
+// ── Markdown → ProseMirror ─────────────────────────────────────────────────
+
+function parseInlineContent(text: string): ProseMirrorNode[] {
+  let nodes: ProseMirrorNode[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    // Link: [text](url)
+    let linkMatch = remaining.match(/^\[([^\]]+)\]\(([^)]+)\)/);
+    if (linkMatch) {
+      nodes.push(
+        schema.text(linkMatch[1], [
+          schema.marks.link.create({ href: linkMatch[2] }),
+        ]),
+      );
+      remaining = remaining.slice(linkMatch[0].length);
+      continue;
+    }
+
+    // Bold+italic: ***text***
+    let boldItalicMatch = remaining.match(/^\*\*\*([^*]+)\*\*\*/);
+    if (boldItalicMatch) {
+      nodes.push(
+        schema.text(boldItalicMatch[1], [
+          schema.marks.strong.create(),
+          schema.marks.em.create(),
+        ]),
+      );
+      remaining = remaining.slice(boldItalicMatch[0].length);
+      continue;
+    }
+
+    // Bold: **text**
+    let boldMatch = remaining.match(/^\*\*([^*]+)\*\*/);
+    if (boldMatch) {
+      nodes.push(
+        schema.text(boldMatch[1], [schema.marks.strong.create()]),
+      );
+      remaining = remaining.slice(boldMatch[0].length);
+      continue;
+    }
+
+    // Italic: *text*
+    let italicMatch = remaining.match(/^\*([^*]+)\*/);
+    if (italicMatch) {
+      nodes.push(
+        schema.text(italicMatch[1], [schema.marks.em.create()]),
+      );
+      remaining = remaining.slice(italicMatch[0].length);
+      continue;
+    }
+
+    // Inline code: `text`
+    let codeMatch = remaining.match(/^`([^`]+)`/);
+    if (codeMatch) {
+      nodes.push(
+        schema.text(codeMatch[1], [schema.marks.code.create()]),
+      );
+      remaining = remaining.slice(codeMatch[0].length);
+      continue;
+    }
+
+    // Card atom: :card[URL]
+    let cardAtomMatch = remaining.match(/^:card\[([^\]]+)\]/);
+    if (cardAtomMatch) {
+      let cardId = cardAtomMatch[1].trim();
+      nodes.push(schema.nodes.boxel_card_atom.create({ cardId, label: cardId }));
+      remaining = remaining.slice(cardAtomMatch[0].length);
+      continue;
+    }
+
+    // Plain text until next special character
+    let plainMatch = remaining.match(/^[^*`\[:\n]+/);
+    if (plainMatch) {
+      nodes.push(schema.text(plainMatch[0]));
+      remaining = remaining.slice(plainMatch[0].length);
+      continue;
+    }
+
+    // Single special char that didn't match a pattern
+    nodes.push(schema.text(remaining[0]));
+    remaining = remaining.slice(1);
+  }
+
+  return nodes;
+}
+
+function parseMarkdown(text: string): ProseMirrorNode {
+  if (!text || text.trim() === '') {
+    return schema.node('doc', null, [schema.node('paragraph')]);
+  }
+
+  let blocks: ProseMirrorNode[] = [];
+  let lines = text.split('\n');
+  let i = 0;
+
+  while (i < lines.length) {
+    let line = lines[i];
+
+    // Empty line — skip
+    if (line.trim() === '') {
+      i++;
+      continue;
+    }
+
+    // Horizontal rule
+    if (/^(---|\*\*\*|___)$/.test(line.trim())) {
+      blocks.push(schema.node('horizontal_rule'));
+      i++;
+      continue;
+    }
+
+    // Code block
+    if (line.trim().startsWith('```')) {
+      let info = line.trim().slice(3).trim();
+      let codeLines: string[] = [];
+      i++;
+      while (i < lines.length && !lines[i].trim().startsWith('```')) {
+        codeLines.push(lines[i]);
+        i++;
+      }
+      i++; // skip closing ```
+      let codeText = codeLines.join('\n');
+      blocks.push(
+        schema.node(
+          'code_block',
+          { info },
+          codeText ? [schema.text(codeText)] : [],
+        ),
+      );
+      continue;
+    }
+
+    // Heading
+    let headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
+    if (headingMatch) {
+      let level = headingMatch[1].length;
+      let content = parseInlineContent(headingMatch[2]);
+      blocks.push(
+        schema.node('heading', { level }, content.length ? content : undefined),
+      );
+      i++;
+      continue;
+    }
+
+    // Block card: ::card[URL] or ::card[URL | specifier]
+    let blockCardMatch = line.trim().match(/^::card\[([^\]]+)\]/);
+    if (blockCardMatch) {
+      let raw = blockCardMatch[1];
+      let pipeIdx = raw.indexOf('|');
+      let cardId = pipeIdx >= 0 ? raw.substring(0, pipeIdx).trim() : raw.trim();
+      blocks.push(schema.nodes.boxel_card_block.create({ cardId }));
+      i++;
+      continue;
+    }
+
+    // Blockquote
+    if (line.startsWith('> ')) {
+      let quoteLines: string[] = [];
+      while (i < lines.length && lines[i].startsWith('> ')) {
+        quoteLines.push(lines[i].slice(2));
+        i++;
+      }
+      let quoteContent = parseInlineContent(quoteLines.join('\n'));
+      blocks.push(
+        schema.node('blockquote', null, [
+          schema.node(
+            'paragraph',
+            null,
+            quoteContent.length ? quoteContent : undefined,
+          ),
+        ]),
+      );
+      continue;
+    }
+
+    // Bullet list
+    if (/^[-*+]\s/.test(line)) {
+      let items: ProseMirrorNode[] = [];
+      while (i < lines.length && /^[-*+]\s/.test(lines[i])) {
+        let itemText = lines[i].replace(/^[-*+]\s/, '');
+        let itemContent = parseInlineContent(itemText);
+        items.push(
+          schema.node('list_item', null, [
+            schema.node(
+              'paragraph',
+              null,
+              itemContent.length ? itemContent : undefined,
+            ),
+          ]),
+        );
+        i++;
+      }
+      blocks.push(schema.node('bullet_list', null, items));
+      continue;
+    }
+
+    // Ordered list
+    if (/^\d+\.\s/.test(line)) {
+      let items: ProseMirrorNode[] = [];
+      let startOrder = parseInt(line.match(/^(\d+)/)![1], 10);
+      while (i < lines.length && /^\d+\.\s/.test(lines[i])) {
+        let itemText = lines[i].replace(/^\d+\.\s/, '');
+        let itemContent = parseInlineContent(itemText);
+        items.push(
+          schema.node('list_item', null, [
+            schema.node(
+              'paragraph',
+              null,
+              itemContent.length ? itemContent : undefined,
+            ),
+          ]),
+        );
+        i++;
+      }
+      blocks.push(schema.node('ordered_list', { order: startOrder }, items));
+      continue;
+    }
+
+    // Regular paragraph
+    let content = parseInlineContent(line);
+    blocks.push(
+      schema.node('paragraph', null, content.length ? content : undefined),
+    );
+    i++;
+  }
+
+  return schema.node(
+    'doc',
+    null,
+    blocks.length > 0 ? blocks : [schema.node('paragraph')],
+  );
+}
+
+// ── ProseMirror → Markdown ─────────────────────────────────────────────────
+
+function serializeInlineContent(node: ProseMirrorNode): string {
+  let result = '';
+  node.forEach((child) => {
+    if (child.isText) {
+      let text = child.text || '';
+      child.marks.forEach((mark) => {
+        switch (mark.type.name) {
+          case 'strong':
+            text = `**${text}**`;
+            break;
+          case 'em':
+            text = `*${text}*`;
+            break;
+          case 'code':
+            text = `\`${text}\``;
+            break;
+          case 'link':
+            text = `[${text}](${mark.attrs.href})`;
+            break;
+        }
+      });
+      result += text;
+    } else if (child.type.name === 'hard_break') {
+      result += '  \n';
+    } else if (child.type.name === 'boxel_card_atom') {
+      result += `:card[${child.attrs.cardId}]`;
+    }
+  });
+  return result;
+}
+
+function serializeNode(node: ProseMirrorNode): string {
+  switch (node.type.name) {
+    case 'paragraph':
+      return serializeInlineContent(node);
+    case 'heading':
+      return '#'.repeat(node.attrs.level) + ' ' + serializeInlineContent(node);
+    case 'horizontal_rule':
+      return '---';
+    case 'blockquote': {
+      let quoteLines: string[] = [];
+      node.forEach((child) => {
+        quoteLines.push('> ' + serializeNode(child));
+      });
+      return quoteLines.join('\n');
+    }
+    case 'code_block': {
+      let info = node.attrs.info || '';
+      return `\`\`\`${info}\n${node.textContent}\n\`\`\``;
+    }
+    case 'bullet_list': {
+      let items: string[] = [];
+      node.forEach((item) => {
+        item.forEach((child, _offset, idx) => {
+          if (idx === 0) {
+            items.push('- ' + serializeNode(child));
+          } else {
+            items.push('  ' + serializeNode(child));
+          }
+        });
+      });
+      return items.join('\n');
+    }
+    case 'ordered_list': {
+      let items: string[] = [];
+      let num = node.attrs.order || 1;
+      node.forEach((item) => {
+        item.forEach((child, _offset, idx) => {
+          if (idx === 0) {
+            items.push(`${num}. ` + serializeNode(child));
+          } else {
+            items.push('   ' + serializeNode(child));
+          }
+        });
+        num++;
+      });
+      return items.join('\n');
+    }
+    case 'boxel_card_block': {
+      let { cardId } = node.attrs;
+      return `::card[${cardId}]`;
+    }
+    default:
+      return node.textContent || '';
+  }
+}
+
+function serializeMarkdown(doc: ProseMirrorNode): string {
+  let blocks: string[] = [];
+  doc.forEach((node) => {
+    blocks.push(serializeNode(node));
+  });
+  return blocks.join('\n\n');
+}
+
+// ── Exported context ───────────────────────────────────────────────────────
+
+export interface ProseMirrorContext {
+  schema: typeof schema;
+  EditorState: typeof EditorState;
+  EditorView: typeof EditorView;
+  keymap: typeof keymap;
+  baseKeymap: typeof baseKeymap;
+  history: typeof history;
+  undo: typeof undo;
+  redo: typeof redo;
+  toggleMark: typeof toggleMark;
+  setBlockType: typeof setBlockType;
+  wrapIn: typeof wrapIn;
+  lift: typeof lift;
+  wrapInList: typeof wrapInList;
+  splitListItem: typeof splitListItem;
+  liftListItem: typeof liftListItem;
+  sinkListItem: typeof sinkListItem;
+  parseMarkdown: (text: string) => ProseMirrorNode;
+  serializeMarkdown: (doc: ProseMirrorNode) => string;
+}
+
+const prosemirrorContext: ProseMirrorContext = {
+  schema,
+  EditorState,
+  EditorView,
+  keymap,
+  baseKeymap,
+  history,
+  undo,
+  redo,
+  toggleMark,
+  setBlockType,
+  wrapIn,
+  lift,
+  wrapInList,
+  splitListItem,
+  liftListItem,
+  sinkListItem,
+  parseMarkdown,
+  serializeMarkdown,
+};
+
+export default prosemirrorContext;
diff --git a/packages/host/app/routes/application.ts b/packages/host/app/routes/application.ts
index 8783d49b405..b22ec062e3a 100644
--- a/packages/host/app/routes/application.ts
+++ b/packages/host/app/routes/application.ts
@@ -41,6 +41,14 @@ export default class Application extends Route {
         let mod = await import('mermaid');
         return mod.default;
       };
+      // Lazy-load ProseMirror for WYSIWYG editing in RichMarkdownField.
+      // The base package's ProseMirrorEditor component calls this via globalThis.
+      (globalThis as any).__loadProseMirror ??= async () => {
+        let mod = await import(
+          '@cardstack/host/lib/prosemirror-context'
+        );
+        return mod.default;
+      };
     }
   }
 
@@ -50,6 +58,7 @@ export default class Application extends Route {
       delete (globalThis as any).__loadMonacoForMarkdown;
       delete (globalThis as any).__loadKatex;
       delete (globalThis as any).__loadMermaid;
+      delete (globalThis as any).__loadProseMirror;
     }
   }
 }
diff --git a/packages/host/package.json b/packages/host/package.json
index 83e7eda3d72..10677cb640c 100644
--- a/packages/host/package.json
+++ b/packages/host/package.json
@@ -173,6 +173,13 @@
     "prettier": "catalog:",
     "prettier-plugin-ember-template-tag": "catalog:",
     "process": "catalog:",
+    "prosemirror-commands": "catalog:",
+    "prosemirror-history": "catalog:",
+    "prosemirror-keymap": "catalog:",
+    "prosemirror-model": "catalog:",
+    "prosemirror-schema-list": "catalog:",
+    "prosemirror-state": "catalog:",
+    "prosemirror-view": "catalog:",
     "qs": "catalog:",
     "qunit": "catalog:",
     "qunit-dom": "catalog:",
diff --git a/packages/host/tests/integration/components/prosemirror-editor-test.gts b/packages/host/tests/integration/components/prosemirror-editor-test.gts
new file mode 100644
index 00000000000..ad1cdfe8b42
--- /dev/null
+++ b/packages/host/tests/integration/components/prosemirror-editor-test.gts
@@ -0,0 +1,383 @@
+import { render, waitFor, settled } from '@ember/test-helpers';
+import { tracked } from '@glimmer/tracking';
+import { module, test } from 'qunit';
+
+import { setupRenderingTest } from '../../helpers/setup';
+
+// Import the prosemirror-context module directly from host — this is
+// the module that gets lazy-loaded in production via globalThis.__loadProseMirror.
+import pmContext from '@cardstack/host/lib/prosemirror-context';
+
+// We can't import ProseMirrorEditor from @cardstack/base (it's served
+// through the realm, not npm). Instead we render a thin wrapper that
+// exercises the same lazy-load path the real component uses.
+
+module('Integration | prosemirror-context', function (hooks) {
+  setupRenderingTest(hooks);
+
+  // ── Schema tests ──
+
+  test('schema has expected node types', function (assert) {
+    let { schema } = pmContext;
+    let nodeNames = Object.keys(schema.nodes);
+
+    assert.true(nodeNames.includes('doc'), 'has doc');
+    assert.true(nodeNames.includes('paragraph'), 'has paragraph');
+    assert.true(nodeNames.includes('heading'), 'has heading');
+    assert.true(nodeNames.includes('blockquote'), 'has blockquote');
+    assert.true(nodeNames.includes('code_block'), 'has code_block');
+    assert.true(nodeNames.includes('bullet_list'), 'has bullet_list');
+    assert.true(nodeNames.includes('ordered_list'), 'has ordered_list');
+    assert.true(nodeNames.includes('list_item'), 'has list_item');
+    assert.true(nodeNames.includes('horizontal_rule'), 'has horizontal_rule');
+    assert.true(nodeNames.includes('hard_break'), 'has hard_break');
+    assert.true(nodeNames.includes('text'), 'has text');
+    assert.true(nodeNames.includes('boxel_card_atom'), 'has boxel_card_atom');
+    assert.true(nodeNames.includes('boxel_card_block'), 'has boxel_card_block');
+  });
+
+  test('schema has expected mark types', function (assert) {
+    let { schema } = pmContext;
+    let markNames = Object.keys(schema.marks);
+
+    assert.true(markNames.includes('strong'), 'has strong');
+    assert.true(markNames.includes('em'), 'has em');
+    assert.true(markNames.includes('code'), 'has code');
+    assert.true(markNames.includes('link'), 'has link');
+  });
+
+  // ── Parse tests ──
+
+  test('parseMarkdown: heading', function (assert) {
+    let doc = pmContext.parseMarkdown('# Hello World');
+    let firstChild = doc.firstChild;
+    assert.strictEqual(firstChild?.type.name, 'heading', 'parses as heading');
+    assert.strictEqual(firstChild?.attrs.level, 1, 'heading level is 1');
+    assert.strictEqual(
+      firstChild?.textContent,
+      'Hello World',
+      'heading text content',
+    );
+  });
+
+  test('parseMarkdown: paragraph with inline formatting', function (assert) {
+    let doc = pmContext.parseMarkdown('Some **bold** and *italic* text.');
+    let para = doc.firstChild;
+    assert.strictEqual(para?.type.name, 'paragraph', 'parses as paragraph');
+
+    let hasStrong = false;
+    let hasEm = false;
+    para?.descendants((node) => {
+      if (node.isText) {
+        node.marks.forEach((mark) => {
+          if (mark.type.name === 'strong') hasStrong = true;
+          if (mark.type.name === 'em') hasEm = true;
+        });
+      }
+      return true;
+    });
+    assert.true(hasStrong, 'has strong mark');
+    assert.true(hasEm, 'has em mark');
+  });
+
+  test('parseMarkdown: bullet list', function (assert) {
+    let doc = pmContext.parseMarkdown('- Item one\n- Item two\n- Item three');
+    let list = doc.firstChild;
+    assert.strictEqual(
+      list?.type.name,
+      'bullet_list',
+      'parses as bullet_list',
+    );
+    assert.strictEqual(list?.childCount, 3, 'has 3 list items');
+  });
+
+  test('parseMarkdown: ordered list', function (assert) {
+    let doc = pmContext.parseMarkdown('1. First\n2. Second\n3. Third');
+    let list = doc.firstChild;
+    assert.strictEqual(
+      list?.type.name,
+      'ordered_list',
+      'parses as ordered_list',
+    );
+    assert.strictEqual(list?.childCount, 3, 'has 3 list items');
+  });
+
+  test('parseMarkdown: code block', function (assert) {
+    let doc = pmContext.parseMarkdown('```typescript\nconst x = 1;\n```');
+    let block = doc.firstChild;
+    assert.strictEqual(
+      block?.type.name,
+      'code_block',
+      'parses as code_block',
+    );
+    assert.strictEqual(
+      block?.textContent,
+      'const x = 1;',
+      'code block content',
+    );
+  });
+
+  test('parseMarkdown: blockquote', function (assert) {
+    let doc = pmContext.parseMarkdown('> This is a quote');
+    let bq = doc.firstChild;
+    assert.strictEqual(bq?.type.name, 'blockquote', 'parses as blockquote');
+    assert.strictEqual(
+      bq?.firstChild?.textContent,
+      'This is a quote',
+      'blockquote text content',
+    );
+  });
+
+  test('parseMarkdown: card atom inline', function (assert) {
+    let doc = pmContext.parseMarkdown(
+      'See :card[./Author/alice] for details.',
+    );
+    let para = doc.firstChild;
+    assert.strictEqual(para?.type.name, 'paragraph', 'wraps in paragraph');
+
+    let hasAtom = false;
+    para?.descendants((node) => {
+      if (node.type.name === 'boxel_card_atom') {
+        hasAtom = true;
+        assert.strictEqual(
+          node.attrs.cardId,
+          './Author/alice',
+          'card atom has correct cardId',
+        );
+      }
+      return true;
+    });
+    assert.true(hasAtom, 'contains card atom node');
+  });
+
+  test('parseMarkdown: card block', function (assert) {
+    let doc = pmContext.parseMarkdown('::card[./Author/alice]');
+    let block = doc.firstChild;
+    assert.strictEqual(
+      block?.type.name,
+      'boxel_card_block',
+      'parses as boxel_card_block',
+    );
+    assert.strictEqual(
+      block?.attrs.cardId,
+      './Author/alice',
+      'card block has correct cardId',
+    );
+  });
+
+  test('parseMarkdown: horizontal rule', function (assert) {
+    let doc = pmContext.parseMarkdown('Before\n\n---\n\nAfter');
+    let hasHr = false;
+    doc.descendants((node) => {
+      if (node.type.name === 'horizontal_rule') hasHr = true;
+      return true;
+    });
+    assert.true(hasHr, 'contains horizontal_rule node');
+  });
+
+  test('parseMarkdown: empty content', function (assert) {
+    let doc = pmContext.parseMarkdown('');
+    assert.strictEqual(doc.type.name, 'doc', 'returns a doc node');
+    assert.strictEqual(
+      doc.firstChild?.type.name,
+      'paragraph',
+      'has an empty paragraph',
+    );
+  });
+
+  // ── Serialize tests ──
+
+  test('serializeMarkdown: heading', function (assert) {
+    let doc = pmContext.parseMarkdown('# Hello World');
+    let result = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(result.trim(), '# Hello World');
+  });
+
+  test('serializeMarkdown: paragraph with formatting', function (assert) {
+    let doc = pmContext.parseMarkdown('Some **bold** and *italic* text.');
+    let result = pmContext.serializeMarkdown(doc);
+    assert.true(result.includes('**bold**'), 'preserves bold');
+    assert.true(result.includes('*italic*'), 'preserves italic');
+  });
+
+  test('serializeMarkdown: bullet list', function (assert) {
+    let doc = pmContext.parseMarkdown('- Item one\n- Item two');
+    let result = pmContext.serializeMarkdown(doc);
+    assert.true(result.includes('- Item one'), 'preserves first item');
+    assert.true(result.includes('- Item two'), 'preserves second item');
+  });
+
+  test('serializeMarkdown: code block', function (assert) {
+    let doc = pmContext.parseMarkdown('```\nconst x = 1;\n```');
+    let result = pmContext.serializeMarkdown(doc);
+    assert.true(result.includes('const x = 1;'), 'preserves code content');
+    assert.true(result.includes('```'), 'preserves code fences');
+  });
+
+  test('serializeMarkdown: blockquote', function (assert) {
+    let doc = pmContext.parseMarkdown('> This is a quote');
+    let result = pmContext.serializeMarkdown(doc);
+    assert.true(result.includes('> This is a quote'), 'preserves blockquote');
+  });
+
+  test('serializeMarkdown: card atom', function (assert) {
+    let doc = pmContext.parseMarkdown(
+      'See :card[./Author/alice] for details.',
+    );
+    let result = pmContext.serializeMarkdown(doc);
+    assert.true(
+      result.includes(':card[./Author/alice]'),
+      'preserves card atom syntax',
+    );
+  });
+
+  test('serializeMarkdown: card block', function (assert) {
+    let doc = pmContext.parseMarkdown('::card[./Author/alice]');
+    let result = pmContext.serializeMarkdown(doc);
+    assert.true(
+      result.includes('::card[./Author/alice]'),
+      'preserves card block syntax',
+    );
+  });
+
+  test('round-trip: complex document', function (assert) {
+    let input = [
+      '# Title',
+      '',
+      'A paragraph with **bold** and *italic*.',
+      '',
+      '- Item one',
+      '- Item two',
+      '',
+      '> A quote',
+      '',
+      '```',
+      'code here',
+      '```',
+      '',
+      '::card[./SomeCard/1]',
+    ].join('\n');
+
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+
+    assert.true(output.includes('# Title'), 'preserves heading');
+    assert.true(output.includes('**bold**'), 'preserves bold');
+    assert.true(output.includes('*italic*'), 'preserves italic');
+    assert.true(output.includes('- Item one'), 'preserves list');
+    assert.true(output.includes('> A quote'), 'preserves blockquote');
+    assert.true(output.includes('code here'), 'preserves code');
+    assert.true(
+      output.includes('::card[./SomeCard/1]'),
+      'preserves card block',
+    );
+  });
+
+  // ── EditorState / EditorView integration ──
+
+  test('EditorState can be created from parsed document', function (assert) {
+    let doc = pmContext.parseMarkdown('Hello world');
+    let state = pmContext.EditorState.create({ doc });
+
+    assert.ok(state, 'state is created');
+    assert.strictEqual(
+      state.doc.firstChild?.textContent,
+      'Hello world',
+      'state contains the parsed document',
+    );
+  });
+
+  test('EditorView mounts into a DOM element', async function (assert) {
+    let doc = pmContext.parseMarkdown('# Test Heading');
+    let state = pmContext.EditorState.create({
+      doc,
+      plugins: [
+        pmContext.keymap(pmContext.baseKeymap),
+        pmContext.history(),
+      ],
+    });
+
+    await render(<template><div id='pm-mount'></div></template>);
+
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    assert.ok(mountEl, 'mount element exists');
+
+    let view = new pmContext.EditorView(mountEl, { state });
+
+    assert.ok(
+      mountEl.querySelector('.ProseMirror'),
+      'ProseMirror view mounts into element',
+    );
+    assert.ok(
+      mountEl.querySelector('.ProseMirror h1'),
+      'heading renders in the view',
+    );
+    assert.strictEqual(
+      mountEl.querySelector('.ProseMirror h1')?.textContent,
+      'Test Heading',
+      'heading text content is correct',
+    );
+
+    view.destroy();
+  });
+
+  test('EditorView renders card atom placeholder DOM', async function (assert) {
+    let doc = pmContext.parseMarkdown(
+      'See :card[./Author/alice] for details.',
+    );
+    let state = pmContext.EditorState.create({ doc });
+
+    await render(<template><div id='pm-mount'></div></template>);
+
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    let view = new pmContext.EditorView(mountEl, { state });
+
+    assert.ok(
+      mountEl.querySelector('.boxel-card-atom'),
+      'card atom placeholder renders',
+    );
+
+    view.destroy();
+  });
+
+  test('EditorView renders card block placeholder DOM', async function (assert) {
+    let doc = pmContext.parseMarkdown('::card[./Author/alice]');
+    let state = pmContext.EditorState.create({ doc });
+
+    await render(<template><div id='pm-mount'></div></template>);
+
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    let view = new pmContext.EditorView(mountEl, { state });
+
+    assert.ok(
+      mountEl.querySelector('.boxel-card-block'),
+      'card block placeholder renders',
+    );
+
+    view.destroy();
+  });
+
+  // ── Lazy-loading via globalThis (component pattern) ──
+
+  test('globalThis.__loadProseMirror loader works', async function (assert) {
+    let originalLoader = (globalThis as any).__loadProseMirror;
+
+    (globalThis as any).__loadProseMirror = async () => {
+      let mod = await import('@cardstack/host/lib/prosemirror-context');
+      return mod.default;
+    };
+
+    try {
+      let loadProseMirror = (globalThis as any).__loadProseMirror;
+      let pm = await loadProseMirror();
+
+      assert.ok(pm.schema, 'loaded context has schema');
+      assert.ok(pm.EditorState, 'loaded context has EditorState');
+      assert.ok(pm.EditorView, 'loaded context has EditorView');
+      assert.ok(pm.parseMarkdown, 'loaded context has parseMarkdown');
+      assert.ok(pm.serializeMarkdown, 'loaded context has serializeMarkdown');
+    } finally {
+      (globalThis as any).__loadProseMirror = originalLoader;
+    }
+  });
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 25040fae33d..e286e29cec9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -564,6 +564,27 @@ catalogs:
     process:
       specifier: ^0.11.10
       version: 0.11.10
+    prosemirror-commands:
+      specifier: ^1.7.1
+      version: 1.7.1
+    prosemirror-history:
+      specifier: ^1.5.0
+      version: 1.5.0
+    prosemirror-keymap:
+      specifier: ^1.2.3
+      version: 1.2.3
+    prosemirror-model:
+      specifier: ^1.25.4
+      version: 1.25.4
+    prosemirror-schema-list:
+      specifier: ^1.5.1
+      version: 1.5.1
+    prosemirror-state:
+      specifier: ^1.4.4
+      version: 1.4.4
+    prosemirror-view:
+      specifier: ^1.41.8
+      version: 1.41.8
     qs:
       specifier: ^6.13.0
       version: 6.14.1
@@ -2222,6 +2243,27 @@ importers:
       process:
         specifier: 'catalog:'
         version: 0.11.10
+      prosemirror-commands:
+        specifier: 'catalog:'
+        version: 1.7.1
+      prosemirror-history:
+        specifier: 'catalog:'
+        version: 1.5.0
+      prosemirror-keymap:
+        specifier: 'catalog:'
+        version: 1.2.3
+      prosemirror-model:
+        specifier: 'catalog:'
+        version: 1.25.4
+      prosemirror-schema-list:
+        specifier: 'catalog:'
+        version: 1.5.1
+      prosemirror-state:
+        specifier: 'catalog:'
+        version: 1.4.4
+      prosemirror-view:
+        specifier: 'catalog:'
+        version: 1.41.8
       qs:
         specifier: 'catalog:'
         version: 6.14.1
@@ -12208,6 +12250,9 @@ packages:
     resolution: {integrity: sha512-5b6Y85tPxZZ7QytO+BQzysW31HJku27cRIlkbAXaNx+BdcVi+LlRFmVXzeF6a7JCwJpyw5c4b+YSVImQIrBpuQ==}
     engines: {node: '>=10'}
 
+  orderedmap@2.1.1:
+    resolution: {integrity: sha512-TvAWxi0nDe1j/rtMcWcIj94+Ffe6n7zhow33h40SKxmsmozs6dz/e+EajymfoFcHd7sxNn8yHM8839uixMOV6g==}
+
   os-locale@5.0.0:
     resolution: {integrity: sha512-tqZcNEDAIZKBEPnHPlVDvKrp7NzgLi7jRmhKiUoa2NUmhl13FtkAGLUVR+ZsYvApBQdBfYm43A4tXXQ4IrYLBA==}
     engines: {node: '>=10'}
@@ -12757,6 +12802,30 @@ packages:
   proper-lockfile@4.1.2:
     resolution: {integrity: sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==}
 
+  prosemirror-commands@1.7.1:
+    resolution: {integrity: sha512-rT7qZnQtx5c0/y/KlYaGvtG411S97UaL6gdp6RIZ23DLHanMYLyfGBV5DtSnZdthQql7W+lEVbpSfwtO8T+L2w==}
+
+  prosemirror-history@1.5.0:
+    resolution: {integrity: sha512-zlzTiH01eKA55UAf1MEjtssJeHnGxO0j4K4Dpx+gnmX9n+SHNlDqI2oO1Kv1iPN5B1dm5fsljCfqKF9nFL6HRg==}
+
+  prosemirror-keymap@1.2.3:
+    resolution: {integrity: sha512-4HucRlpiLd1IPQQXNqeo81BGtkY8Ai5smHhKW9jjPKRc2wQIxksg7Hl1tTI2IfT2B/LgX6bfYvXxEpJl7aKYKw==}
+
+  prosemirror-model@1.25.4:
+    resolution: {integrity: sha512-PIM7E43PBxKce8OQeezAs9j4TP+5yDpZVbuurd1h5phUxEKIu+G2a+EUZzIC5nS1mJktDJWzbqS23n1tsAf5QA==}
+
+  prosemirror-schema-list@1.5.1:
+    resolution: {integrity: sha512-927lFx/uwyQaGwJxLWCZRkjXG0p48KpMj6ueoYiu4JX05GGuGcgzAy62dfiV8eFZftgyBUvLx76RsMe20fJl+Q==}
+
+  prosemirror-state@1.4.4:
+    resolution: {integrity: sha512-6jiYHH2CIGbCfnxdHbXZ12gySFY/fz/ulZE333G6bPqIZ4F+TXo9ifiR86nAHpWnfoNjOb3o5ESi7J8Uz1jXHw==}
+
+  prosemirror-transform@1.12.0:
+    resolution: {integrity: sha512-GxboyN4AMIsoHNtz5uf2r2Ru551i5hWeCMD6E2Ib4Eogqoub0NflniaBPVQ4MrGE5yZ8JV9tUHg9qcZTTrcN4w==}
+
+  prosemirror-view@1.41.8:
+    resolution: {integrity: sha512-TnKDdohEatgyZNGCDWIdccOHXhYloJwbwU+phw/a23KBvJIR9lWQWW7WHHK3vBdOLDNuF7TaX98GObUZOWkOnA==}
+
   proxy-addr@2.0.7:
     resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
     engines: {node: '>= 0.10'}
@@ -13176,6 +13245,9 @@ packages:
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
     hasBin: true
 
+  rope-sequence@1.3.4:
+    resolution: {integrity: sha512-UT5EDe2cu2E/6O4igUr5PSFs23nvvukicWHx6GnOPlHAiiYbzNuCRQCuiUdHJQcqKalLKlrYJnjY0ySGsXNQXQ==}
+
   roughjs@4.6.6:
     resolution: {integrity: sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==}
 
@@ -14583,6 +14655,9 @@ packages:
   vscode-uri@3.1.0:
     resolution: {integrity: sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==}
 
+  w3c-keyname@2.2.8:
+    resolution: {integrity: sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==}
+
   w3c-xmlserializer@4.0.0:
     resolution: {integrity: sha512-d+BFHzbiCx6zGfz0HyQ6Rg69w9k19nviJspaj4yNscGjrHu94sVP+aRm75yEbCh+r2/yR+7q6hux9LVtbuTGBw==}
     engines: {node: '>=14'}
@@ -26449,6 +26524,8 @@ snapshots:
       strip-ansi: 6.0.1
       wcwidth: 1.0.1
 
+  orderedmap@2.1.1: {}
+
   os-locale@5.0.0:
     dependencies:
       execa: 4.1.0
@@ -26964,6 +27041,50 @@ snapshots:
       retry: 0.12.0
       signal-exit: 3.0.7
 
+  prosemirror-commands@1.7.1:
+    dependencies:
+      prosemirror-model: 1.25.4
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.0
+
+  prosemirror-history@1.5.0:
+    dependencies:
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.0
+      prosemirror-view: 1.41.8
+      rope-sequence: 1.3.4
+
+  prosemirror-keymap@1.2.3:
+    dependencies:
+      prosemirror-state: 1.4.4
+      w3c-keyname: 2.2.8
+
+  prosemirror-model@1.25.4:
+    dependencies:
+      orderedmap: 2.1.1
+
+  prosemirror-schema-list@1.5.1:
+    dependencies:
+      prosemirror-model: 1.25.4
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.0
+
+  prosemirror-state@1.4.4:
+    dependencies:
+      prosemirror-model: 1.25.4
+      prosemirror-transform: 1.12.0
+      prosemirror-view: 1.41.8
+
+  prosemirror-transform@1.12.0:
+    dependencies:
+      prosemirror-model: 1.25.4
+
+  prosemirror-view@1.41.8:
+    dependencies:
+      prosemirror-model: 1.25.4
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.0
+
   proxy-addr@2.0.7:
     dependencies:
       forwarded: 0.2.0
@@ -27522,6 +27643,8 @@ snapshots:
       '@rollup/rollup-win32-x64-msvc': 4.55.1
       fsevents: 2.3.3
 
+  rope-sequence@1.3.4: {}
+
   roughjs@4.6.6:
     dependencies:
       hachure-fill: 0.5.2
@@ -29191,6 +29314,8 @@ snapshots:
 
   vscode-uri@3.1.0: {}
 
+  w3c-keyname@2.2.8: {}
+
   w3c-xmlserializer@4.0.0:
     dependencies:
       xml-name-validator: 4.0.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 224b82dbfc5..c9dc630bc6c 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -206,6 +206,13 @@ catalog:
   prettier: ^3.6.2
   prettier-plugin-ember-template-tag: ^2.0.0
   process: ^0.11.10
+  prosemirror-commands: ^1.7.1
+  prosemirror-history: ^1.5.0
+  prosemirror-keymap: ^1.2.3
+  prosemirror-model: ^1.25.4
+  prosemirror-schema-list: ^1.5.1
+  prosemirror-state: ^1.4.4
+  prosemirror-view: ^1.41.8
   qs: ^6.13.0
   qunit: ^2.24.1
   qunit-dom: ^3.5.0

From ce5f918d1b5f8eaf15497c5317c551c86c695b0f Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Tue, 7 Apr 2026 15:02:16 -0400
Subject: [PATCH 46/50] Add RichMarkdownField playground page to experiments
 realm

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../RichMarkdownPlayground/playground.json    | 30 +++++++
 .../rich-markdown-playground.gts              | 89 +++++++++++++++++++
 2 files changed, 119 insertions(+)
 create mode 100644 packages/experiments-realm/RichMarkdownPlayground/playground.json
 create mode 100644 packages/experiments-realm/rich-markdown-playground.gts

diff --git a/packages/experiments-realm/RichMarkdownPlayground/playground.json b/packages/experiments-realm/RichMarkdownPlayground/playground.json
new file mode 100644
index 00000000000..f982b561c1e
--- /dev/null
+++ b/packages/experiments-realm/RichMarkdownPlayground/playground.json
@@ -0,0 +1,30 @@
+{
+  "data": {
+    "meta": {
+      "adoptsFrom": {
+        "name": "RichMarkdownPlayground",
+        "module": "../rich-markdown-playground"
+      }
+    },
+    "type": "card",
+    "attributes": {
+      "cardInfo": {
+        "notes": null,
+        "name": "Rich Markdown Playground",
+        "summary": "Exercise the RichMarkdownField with its ProseMirror WYSIWYG editor.",
+        "cardThumbnailURL": null
+      },
+      "title": "Rich Markdown Playground",
+      "body": {
+        "content": "# Welcome to the Rich Markdown Playground\n\nThis card uses `RichMarkdownField` which provides a **ProseMirror WYSIWYG editor** in edit mode.\n\n## Features to Try\n\n### Inline Formatting\n\nYou can write **bold text**, *italic text*, and `inline code`.\n\n### Lists\n\n- Bullet list item one\n- Bullet list item two\n- Bullet list item three\n\n1. Ordered list first\n2. Ordered list second\n3. Ordered list third\n\n### Code Block\n\n```typescript\nimport { RichMarkdownField } from 'https://cardstack.com/base/rich-markdown';\n\nclass MyCard extends CardDef {\n  @field body = contains(RichMarkdownField);\n}\n```\n\n### Blockquote\n\n> The ProseMirror editor supports keyboard shortcuts like **Cmd+B** for bold, **Cmd+I** for italic, and **Cmd+Z** for undo.\n\n---\n\n### Card References\n\nInline card atom: :card[./Author/jane-doe]\n\nBlock card:\n\n::card[./Author/jane-doe]\n\nSwitch to **Edit** mode to try the WYSIWYG editor!"
+      }
+    },
+    "relationships": {
+      "cardInfo.theme": {
+        "links": {
+          "self": null
+        }
+      }
+    }
+  }
+}
diff --git a/packages/experiments-realm/rich-markdown-playground.gts b/packages/experiments-realm/rich-markdown-playground.gts
new file mode 100644
index 00000000000..cf8d86d3983
--- /dev/null
+++ b/packages/experiments-realm/rich-markdown-playground.gts
@@ -0,0 +1,89 @@
+import {
+  contains,
+  field,
+  CardDef,
+  Component,
+} from 'https://cardstack.com/base/card-api';
+import StringField from 'https://cardstack.com/base/string';
+import { RichMarkdownField } from 'https://cardstack.com/base/rich-markdown';
+
+export class RichMarkdownPlayground extends CardDef {
+  static displayName = 'Rich Markdown Playground';
+
+  @field title = contains(StringField);
+  @field body = contains(RichMarkdownField);
+
+  static isolated = class Isolated extends Component<typeof this> {
+    <template>
+      <article class='playground'>
+        <header>
+          <h1>{{@model.title}}</h1>
+          <p class='subtitle'>
+            This playground exercises the
+            <code>RichMarkdownField</code>
+            with its ProseMirror WYSIWYG editor. Switch to
+            <strong>Edit</strong>
+            mode to see the editor, or view the rendered markdown below.
+          </p>
+        </header>
+
+        <section class='content'>
+          <h2>Content</h2>
+          <div class='rendered-markdown'>
+            <@fields.body />
+          </div>
+        </section>
+      </article>
+
+      <style scoped>
+        .playground {
+          max-width: 800px;
+          margin: 0 auto;
+          padding: var(--boxel-sp-lg, 24px);
+          font-family: var(--boxel-font-family, sans-serif);
+        }
+
+        .playground header {
+          margin-bottom: var(--boxel-sp-lg, 24px);
+          padding-bottom: var(--boxel-sp, 16px);
+          border-bottom: 1px solid var(--boxel-border-color, #e0e0e0);
+        }
+
+        .playground h1 {
+          margin: 0 0 var(--boxel-sp-xs, 4px);
+          font-size: 1.75rem;
+          font-weight: 700;
+        }
+
+        .subtitle {
+          color: var(--boxel-400, #666);
+          margin: 0;
+          line-height: 1.5;
+        }
+
+        .subtitle code {
+          background: var(--boxel-100, #f5f5f5);
+          padding: 0.1em 0.4em;
+          border-radius: 3px;
+          font-size: 0.9em;
+        }
+
+        .content h2 {
+          font-size: 1.1rem;
+          font-weight: 600;
+          margin-bottom: var(--boxel-sp-sm, 8px);
+          color: var(--boxel-400, #666);
+          text-transform: uppercase;
+          letter-spacing: 0.05em;
+        }
+
+        .rendered-markdown {
+          border: 1px solid var(--boxel-border-color, #e0e0e0);
+          border-radius: var(--boxel-border-radius, 4px);
+          padding: var(--boxel-sp, 16px);
+          min-height: 200px;
+        }
+      </style>
+    </template>
+  };
+}

From 445e5ce9cec31a366d59f8886d916396b1569f87 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Tue, 7 Apr 2026 22:45:03 -0400
Subject: [PATCH 47/50] =?UTF-8?q?Add=20authored=20markdown=20=E2=86=94=20P?=
 =?UTF-8?q?roseMirror=20round-trip=20serialization=20(CS-10573)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Strengthen parser and serializer for proper round-trip fidelity:
- Fix combined bold+italic mark serialization (***text***)
- Add link title support in parse and serialize
- Guard against ::card[URL] being misinterpreted as inline card atom
- Auto-derive card atom labels from URL path segment
- Overhaul blockquote handling: bare > lines, multi-paragraph support
- Fix empty code block serialization
- Add 26 comprehensive round-trip tests covering all standard elements,
  card references with relative/absolute URLs, and edge cases

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/host/app/lib/prosemirror-context.ts  | 122 +++++++---
 .../components/prosemirror-editor-test.gts    | 228 ++++++++++++++++++
 2 files changed, 318 insertions(+), 32 deletions(-)

diff --git a/packages/host/app/lib/prosemirror-context.ts b/packages/host/app/lib/prosemirror-context.ts
index 50c3e2caa73..4a0ada2de90 100644
--- a/packages/host/app/lib/prosemirror-context.ts
+++ b/packages/host/app/lib/prosemirror-context.ts
@@ -290,12 +290,16 @@ function parseInlineContent(text: string): ProseMirrorNode[] {
   let remaining = text;
 
   while (remaining.length > 0) {
-    // Link: [text](url)
-    let linkMatch = remaining.match(/^\[([^\]]+)\]\(([^)]+)\)/);
+    // Link: [text](url) or [text](url "title")
+    let linkMatch = remaining.match(
+      /^\[([^\]]+)\]\((\S+?)(?:\s+"([^"]*)")?\)/,
+    );
     if (linkMatch) {
+      let href = linkMatch[2];
+      let title = linkMatch[3] || null;
       nodes.push(
         schema.text(linkMatch[1], [
-          schema.marks.link.create({ href: linkMatch[2] }),
+          schema.marks.link.create({ href, title }),
         ]),
       );
       remaining = remaining.slice(linkMatch[0].length);
@@ -345,11 +349,20 @@ function parseInlineContent(text: string): ProseMirrorNode[] {
       continue;
     }
 
+    // Block card reference in inline context (::card[URL]) — treat as plain text
+    let blockCardInlineMatch = remaining.match(/^::card\[([^\]]+)\]/);
+    if (blockCardInlineMatch) {
+      nodes.push(schema.text(blockCardInlineMatch[0]));
+      remaining = remaining.slice(blockCardInlineMatch[0].length);
+      continue;
+    }
+
     // Card atom: :card[URL]
     let cardAtomMatch = remaining.match(/^:card\[([^\]]+)\]/);
     if (cardAtomMatch) {
       let cardId = cardAtomMatch[1].trim();
-      nodes.push(schema.nodes.boxel_card_atom.create({ cardId, label: cardId }));
+      let label = cardId.split('/').filter(Boolean).pop() || cardId;
+      nodes.push(schema.nodes.boxel_card_atom.create({ cardId, label }));
       remaining = remaining.slice(cardAtomMatch[0].length);
       continue;
     }
@@ -440,21 +453,51 @@ function parseMarkdown(text: string): ProseMirrorNode {
     }
 
     // Blockquote
-    if (line.startsWith('> ')) {
+    if (line.startsWith('> ') || line === '>') {
       let quoteLines: string[] = [];
-      while (i < lines.length && lines[i].startsWith('> ')) {
-        quoteLines.push(lines[i].slice(2));
+      while (
+        i < lines.length &&
+        (lines[i].startsWith('> ') || lines[i] === '>')
+      ) {
+        quoteLines.push(lines[i] === '>' ? '' : lines[i].slice(2));
         i++;
       }
-      let quoteContent = parseInlineContent(quoteLines.join('\n'));
-      blocks.push(
-        schema.node('blockquote', null, [
+      // Split into paragraphs on empty lines within the blockquote
+      let paragraphs: ProseMirrorNode[] = [];
+      let currentLines: string[] = [];
+      for (let ql of quoteLines) {
+        if (ql === '') {
+          if (currentLines.length > 0) {
+            let paraContent = parseInlineContent(currentLines.join(' '));
+            paragraphs.push(
+              schema.node(
+                'paragraph',
+                null,
+                paraContent.length ? paraContent : undefined,
+              ),
+            );
+            currentLines = [];
+          }
+        } else {
+          currentLines.push(ql);
+        }
+      }
+      if (currentLines.length > 0) {
+        let paraContent = parseInlineContent(currentLines.join(' '));
+        paragraphs.push(
           schema.node(
             'paragraph',
             null,
-            quoteContent.length ? quoteContent : undefined,
+            paraContent.length ? paraContent : undefined,
           ),
-        ]),
+        );
+      }
+      blocks.push(
+        schema.node(
+          'blockquote',
+          null,
+          paragraphs.length > 0 ? paragraphs : [schema.node('paragraph')],
+        ),
       );
       continue;
     }
@@ -524,22 +567,28 @@ function serializeInlineContent(node: ProseMirrorNode): string {
   node.forEach((child) => {
     if (child.isText) {
       let text = child.text || '';
-      child.marks.forEach((mark) => {
-        switch (mark.type.name) {
-          case 'strong':
-            text = `**${text}**`;
-            break;
-          case 'em':
-            text = `*${text}*`;
-            break;
-          case 'code':
-            text = `\`${text}\``;
-            break;
-          case 'link':
-            text = `[${text}](${mark.attrs.href})`;
-            break;
+      let marks = child.marks;
+      let hasStrong = marks.some((m) => m.type.name === 'strong');
+      let hasEm = marks.some((m) => m.type.name === 'em');
+      let hasCode = marks.some((m) => m.type.name === 'code');
+      let link = marks.find((m) => m.type.name === 'link');
+
+      if (hasCode) {
+        text = `\`${text}\``;
+      } else {
+        if (hasStrong && hasEm) {
+          text = `***${text}***`;
+        } else if (hasStrong) {
+          text = `**${text}**`;
+        } else if (hasEm) {
+          text = `*${text}*`;
         }
-      });
+      }
+      if (link) {
+        text = link.attrs.title
+          ? `[${text}](${link.attrs.href} "${link.attrs.title}")`
+          : `[${text}](${link.attrs.href})`;
+      }
       result += text;
     } else if (child.type.name === 'hard_break') {
       result += '  \n';
@@ -559,15 +608,24 @@ function serializeNode(node: ProseMirrorNode): string {
     case 'horizontal_rule':
       return '---';
     case 'blockquote': {
-      let quoteLines: string[] = [];
-      node.forEach((child) => {
-        quoteLines.push('> ' + serializeNode(child));
+      let parts: string[] = [];
+      node.forEach((child, _offset, idx) => {
+        if (idx > 0) {
+          parts.push('>');
+        }
+        let serialized = serializeNode(child);
+        for (let line of serialized.split('\n')) {
+          parts.push('> ' + line);
+        }
       });
-      return quoteLines.join('\n');
+      return parts.join('\n');
     }
     case 'code_block': {
       let info = node.attrs.info || '';
-      return `\`\`\`${info}\n${node.textContent}\n\`\`\``;
+      let content = node.textContent;
+      return content
+        ? `\`\`\`${info}\n${content}\n\`\`\``
+        : `\`\`\`${info}\n\`\`\``;
     }
     case 'bullet_list': {
       let items: string[] = [];
diff --git a/packages/host/tests/integration/components/prosemirror-editor-test.gts b/packages/host/tests/integration/components/prosemirror-editor-test.gts
index ad1cdfe8b42..a6522c087b2 100644
--- a/packages/host/tests/integration/components/prosemirror-editor-test.gts
+++ b/packages/host/tests/integration/components/prosemirror-editor-test.gts
@@ -273,6 +273,234 @@ module('Integration | prosemirror-context', function (hooks) {
     );
   });
 
+  // ── Round-trip: standard markdown elements ──
+
+  test('round-trip: heading levels 1-6', function (assert) {
+    for (let level = 1; level <= 6; level++) {
+      let prefix = '#'.repeat(level);
+      let input = `${prefix} Heading Level ${level}`;
+      let doc = pmContext.parseMarkdown(input);
+      let output = pmContext.serializeMarkdown(doc);
+      assert.strictEqual(output, input, `h${level} round-trips`);
+    }
+  });
+
+  test('round-trip: plain paragraph', function (assert) {
+    let input = 'Just a plain paragraph.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: bold text', function (assert) {
+    let input = 'Some **bold** text.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: italic text', function (assert) {
+    let input = 'Some *italic* text.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: bold italic text', function (assert) {
+    let input = 'Some ***bold italic*** text.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: inline code', function (assert) {
+    let input = 'Use the `console.log` function.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: link', function (assert) {
+    let input = 'Visit [Example](https://example.com) for more.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: bullet list', function (assert) {
+    let input = '- First item\n- Second item\n- Third item';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: ordered list', function (assert) {
+    let input = '1. First item\n2. Second item\n3. Third item';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: ordered list with custom start', function (assert) {
+    let input = '5. Fifth item\n6. Sixth item';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: blockquote', function (assert) {
+    let input = '> This is a quoted paragraph.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: code block without language', function (assert) {
+    let input = '```\nconst x = 1;\n```';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: code block with language', function (assert) {
+    let input = '```typescript\nconst x: number = 1;\n```';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: horizontal rule', function (assert) {
+    let input = 'Before\n\n---\n\nAfter';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: multiple paragraphs', function (assert) {
+    let input = 'First paragraph.\n\nSecond paragraph.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: empty code block', function (assert) {
+    let input = '```\n```';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  // ── Round-trip: card references ──
+
+  test('round-trip: inline card with relative URL', function (assert) {
+    let input = 'See :card[./Author/alice] for details.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: inline card with absolute URL', function (assert) {
+    let input =
+      'See :card[https://example.com/Author/alice] for details.';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: block card with relative URL', function (assert) {
+    let input = '::card[./Author/alice]';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: block card with absolute URL', function (assert) {
+    let input = '::card[https://example.com/Author/alice]';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  // ── Round-trip: edge cases ──
+
+  test('round-trip: adjacent inline cards', function (assert) {
+    let input = ':card[./Author/alice]:card[./Author/bob]';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: card atom inside list item', function (assert) {
+    let input =
+      '- See :card[./Author/alice] here\n- And :card[./Author/bob] there';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: card block after heading', function (assert) {
+    let input = '# Authors\n\n::card[./Author/alice]';
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  test('round-trip: mixed content document', function (assert) {
+    let input = [
+      '# Document Title',
+      '',
+      'A paragraph with **bold**, *italic*, and `code`.',
+      '',
+      '- List item with :card[./Card/1]',
+      '- Another item',
+      '',
+      '> A blockquote',
+      '',
+      '```javascript',
+      'console.log("hello");',
+      '```',
+      '',
+      '::card[./SomeCard/1]',
+    ].join('\n');
+
+    let doc = pmContext.parseMarkdown(input);
+    let output = pmContext.serializeMarkdown(doc);
+    assert.strictEqual(output, input);
+  });
+
+  // ── Parse: label auto-derivation ──
+
+  test('parseMarkdown: card atom label derived from URL path', function (assert) {
+    let doc = pmContext.parseMarkdown('See :card[./Author/alice] here.');
+    let atom: any = null;
+    doc.descendants((node) => {
+      if (node.type.name === 'boxel_card_atom') atom = node;
+      return true;
+    });
+    assert.strictEqual(atom?.attrs.cardId, './Author/alice');
+    assert.strictEqual(
+      atom?.attrs.label,
+      'alice',
+      'label derived from last path segment',
+    );
+  });
+
+  test('parseMarkdown: card atom label from absolute URL', function (assert) {
+    let doc = pmContext.parseMarkdown(
+      ':card[https://example.com/Author/alice]',
+    );
+    let atom: any = null;
+    doc.descendants((node) => {
+      if (node.type.name === 'boxel_card_atom') atom = node;
+      return true;
+    });
+    assert.strictEqual(
+      atom?.attrs.label,
+      'alice',
+      'label derived from last URL segment',
+    );
+  });
+
   // ── EditorState / EditorView integration ──
 
   test('EditorState can be created from parsed document', function (assert) {

From 9f67de699e4eca81e748fc87cdcdba30f727f798 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Tue, 7 Apr 2026 22:45:33 -0400
Subject: [PATCH 48/50] Fix relative card reference paths in
 RichMarkdownPlayground

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../experiments-realm/RichMarkdownPlayground/playground.json    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/experiments-realm/RichMarkdownPlayground/playground.json b/packages/experiments-realm/RichMarkdownPlayground/playground.json
index f982b561c1e..6a9d1d2e6da 100644
--- a/packages/experiments-realm/RichMarkdownPlayground/playground.json
+++ b/packages/experiments-realm/RichMarkdownPlayground/playground.json
@@ -16,7 +16,7 @@
       },
       "title": "Rich Markdown Playground",
       "body": {
-        "content": "# Welcome to the Rich Markdown Playground\n\nThis card uses `RichMarkdownField` which provides a **ProseMirror WYSIWYG editor** in edit mode.\n\n## Features to Try\n\n### Inline Formatting\n\nYou can write **bold text**, *italic text*, and `inline code`.\n\n### Lists\n\n- Bullet list item one\n- Bullet list item two\n- Bullet list item three\n\n1. Ordered list first\n2. Ordered list second\n3. Ordered list third\n\n### Code Block\n\n```typescript\nimport { RichMarkdownField } from 'https://cardstack.com/base/rich-markdown';\n\nclass MyCard extends CardDef {\n  @field body = contains(RichMarkdownField);\n}\n```\n\n### Blockquote\n\n> The ProseMirror editor supports keyboard shortcuts like **Cmd+B** for bold, **Cmd+I** for italic, and **Cmd+Z** for undo.\n\n---\n\n### Card References\n\nInline card atom: :card[./Author/jane-doe]\n\nBlock card:\n\n::card[./Author/jane-doe]\n\nSwitch to **Edit** mode to try the WYSIWYG editor!"
+        "content": "# Welcome to the Rich Markdown Playground\n\nThis card uses `RichMarkdownField` which provides a **ProseMirror WYSIWYG editor** in edit mode.\n\n## Features to Try\n\n### Inline Formatting\n\nYou can write **bold text**, *italic text*, and `inline code`.\n\n### Lists\n\n- Bullet list item one\n- Bullet list item two\n- Bullet list item three\n\n1. Ordered list first\n2. Ordered list second\n3. Ordered list third\n\n### Code Block\n\n```typescript\nimport { RichMarkdownField } from 'https://cardstack.com/base/rich-markdown';\n\nclass MyCard extends CardDef {\n  @field body = contains(RichMarkdownField);\n}\n```\n\n### Blockquote\n\n> The ProseMirror editor supports keyboard shortcuts like **Cmd+B** for bold, **Cmd+I** for italic, and **Cmd+Z** for undo.\n\n---\n\n### Card References\n\nInline card atom: :card[../Author/jane-doe]\n\nBlock card:\n\n::card[../Author/jane-doe]\n\nSwitch to **Edit** mode to try the WYSIWYG editor!"
       }
     },
     "relationships": {

From 945d5f40ffe5d28f3bc8660a37e738babe284119 Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Tue, 7 Apr 2026 23:06:05 -0400
Subject: [PATCH 49/50] Render embedded cards inside ProseMirror editor
 (CS-10574)

Add card nodeView infrastructure that renders live card components inside
the ProseMirror editing surface using custom nodeViews and Glimmer's
{{in-element}}. Card references (:card[URL] / ::card[URL]) now display
as resolved card components when available, with fallback text otherwise.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/prosemirror-editor.gts          | 193 +++++++++++++++-
 packages/base/rich-markdown.gts               |  13 ++
 packages/host/app/lib/prosemirror-context.ts  |  79 +++++++
 .../components/prosemirror-editor-test.gts    | 210 ++++++++++++++++++
 .../components/rich-markdown-field-test.gts   |  12 +-
 5 files changed, 502 insertions(+), 5 deletions(-)

diff --git a/packages/base/prosemirror-editor.gts b/packages/base/prosemirror-editor.gts
index 5638def8a58..9724685847e 100644
--- a/packages/base/prosemirror-editor.gts
+++ b/packages/base/prosemirror-editor.gts
@@ -1,11 +1,30 @@
 import { task } from 'ember-concurrency';
 import GlimmerComponent from '@glimmer/component';
-import { tracked } from '@glimmer/tracking';
+import { cached, tracked } from '@glimmer/tracking';
 import { modifier } from 'ember-modifier';
+import { scheduleOnce } from '@ember/runloop';
+
+import {
+  resolveCardReference,
+  trimJsonExtension,
+} from '@cardstack/runtime-common';
+import { type BaseDef, type CardDef, getComponent } from './card-api';
+import { CardContextConsumer } from './field-component';
 
 // The ProseMirrorContext 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
 // globalThis.__loadProseMirror.
+interface CardNodeViewTarget {
+  element: HTMLElement;
+  cardId: string;
+  format: 'atom' | 'embedded';
+  kind: 'inline' | 'block';
+}
+
+interface CardRenderTarget extends CardNodeViewTarget {
+  card: CardDef | null;
+}
+
 interface ProseMirrorContext {
   schema: any;
   EditorState: any;
@@ -25,20 +44,43 @@ interface ProseMirrorContext {
   sinkListItem: (itemType: any) => any;
   parseMarkdown: (text: string) => any;
   serializeMarkdown: (doc: any) => string;
+  createCardNodeViews: (
+    onChange: (targets: CardNodeViewTarget[]) => void,
+  ) => Record<string, any>;
 }
 
 const SAVE_DEBOUNCE_MS = 500;
 
+function isInline(kind: string): boolean {
+  return kind === 'inline';
+}
+
+function resolveUrl(raw: string, baseUrl: string | null | undefined): string {
+  try {
+    return trimJsonExtension(resolveCardReference(raw, baseUrl || undefined));
+  } catch {
+    return trimJsonExtension(raw);
+  }
+}
+
 interface ProseMirrorEditorSignature {
   Args: {
     content: string | null;
     onUpdate: (markdown: string) => void;
+    linkedCards?: CardDef[] | null;
+    cardReferenceBaseUrl?: string | null;
   };
   Element: HTMLDivElement;
 }
 
 export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEditorSignature> {
   @tracked _pm: ProseMirrorContext | null = null;
+  @tracked _nodeViewTargets: CardNodeViewTarget[] = [];
+
+  // Non-tracked staging area — updated synchronously by nodeView callbacks,
+  // then flushed into the tracked property after rendering to avoid
+  // Glimmer backtracking assertions.
+  private _pendingTargets: CardNodeViewTarget[] = [];
 
   get pm(): ProseMirrorContext | null {
     if (!this._pm) {
@@ -58,6 +100,50 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
   private editorView: any = null;
   private lastExternalContent: string | null = null;
   private saveTimer: ReturnType<typeof setTimeout> | null = null;
+  private _slotUpdatePending = false;
+
+  // ── Card slot resolution ───────────────────────────────────────────────
+
+  @cached
+  get cardRenderTargets(): CardRenderTarget[] {
+    let targets = this._nodeViewTargets;
+    let linkedCards = this.args.linkedCards;
+    let baseUrl = this.args.cardReferenceBaseUrl;
+
+    let cardsByUrl = new Map<string, CardDef>();
+    if (linkedCards?.length) {
+      for (let card of linkedCards) {
+        if (card?.id) {
+          cardsByUrl.set(card.id, card);
+        }
+      }
+    }
+
+    return targets.map((target) => {
+      let resolved = resolveUrl(target.cardId, baseUrl);
+      return {
+        ...target,
+        card: cardsByUrl.get(resolved) ?? null,
+      };
+    });
+  }
+
+  private _handleTargetChange = (targets: CardNodeViewTarget[]) => {
+    this._pendingTargets = targets;
+    if (!this._slotUpdatePending) {
+      this._slotUpdatePending = true;
+      scheduleOnce('afterRender', this, this._applyTargets);
+    }
+  };
+
+  _applyTargets = () => {
+    this._slotUpdatePending = false;
+    this._nodeViewTargets = this._pendingTargets;
+  };
+
+  getCardComponent = (card: BaseDef) => getComponent(card);
+
+  // ── Editor lifecycle ───────────────────────────────────────────────────
 
   mountEditor = modifier(
     (element: HTMLElement, _positional: unknown[]) => {
@@ -128,8 +214,11 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
         ],
       });
 
+      let nodeViews = pm.createCardNodeViews(this._handleTargetChange);
+
       let view = new pm.EditorView(element, {
         state,
+        nodeViews,
         dispatchTransaction: (tr: any) => {
           let newState = view.state.apply(tr);
           view.updateState(newState);
@@ -236,6 +325,51 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
         ...attributes
       >
       </div>
+      {{#each this.cardRenderTargets as |target|}}
+        {{#in-element target.element insertBefore=null}}
+          {{#if target.card}}
+            <CardContextConsumer as |context|>
+              {{#let (this.getCardComponent target.card) as |CardComponent|}}
+                {{#if (isInline target.kind)}}
+                  <span
+                    class='prosemirror-card-slot prosemirror-card-slot--inline'
+                    data-test-prosemirror-card-slot-inline
+                    {{context.cardComponentModifier
+                      card=target.card
+                      format='data'
+                      fieldType=undefined
+                      fieldName=undefined
+                    }}
+                  >
+                    <CardComponent
+                      @format={{target.format}}
+                      @displayContainer={{false}}
+                    />
+                  </span>
+                {{else}}
+                  <div
+                    class='prosemirror-card-slot prosemirror-card-slot--block'
+                    data-test-prosemirror-card-slot-block
+                    {{context.cardComponentModifier
+                      card=target.card
+                      format='data'
+                      fieldType=undefined
+                      fieldName=undefined
+                    }}
+                  >
+                    <CardComponent
+                      @format={{target.format}}
+                      @displayContainer={{false}}
+                    />
+                  </div>
+                {{/if}}
+              {{/let}}
+            </CardContextConsumer>
+          {{else}}
+            <span class='prosemirror-card-fallback'>{{target.cardId}}</span>
+          {{/if}}
+        {{/in-element}}
+      {{/each}}
     {{else}}
       <div class='prosemirror-editor-loading' data-test-prosemirror-loading>
         Loading editor…
@@ -308,7 +442,7 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
           margin: var(--boxel-sp, 16px) 0;
         }
 
-        /* Card node placeholders */
+        /* Card node placeholders (fallback when nodeViews are not active) */
         .prosemirror-editor :deep(.boxel-card-atom) {
           display: inline-flex;
           align-items: center;
@@ -337,6 +471,61 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
           word-break: break-all;
         }
 
+        /* NodeView card containers */
+        .prosemirror-editor :deep(.boxel-card-atom-view) {
+          display: inline;
+          user-select: none;
+        }
+
+        .prosemirror-editor :deep(.boxel-card-block-view) {
+          display: block;
+          margin: var(--boxel-sp-xs, 4px) 0;
+          user-select: none;
+        }
+
+        /* Card slot wrappers rendered via {{in-element}} */
+        .prosemirror-editor :deep(.prosemirror-card-slot) {
+          contain: layout style paint;
+        }
+
+        .prosemirror-editor :deep(.prosemirror-card-slot--inline) {
+          display: inline-flex;
+          align-items: center;
+          gap: 4px;
+          background-color: var(--boxel-100, #f0f0f0);
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          padding: 1px 6px;
+          font-size: 0.85em;
+          cursor: pointer;
+        }
+
+        .prosemirror-editor :deep(.prosemirror-card-slot--block) {
+          display: block;
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          overflow: hidden;
+        }
+
+        /* Selection highlight for atom nodes */
+        .prosemirror-editor :deep(.boxel-card-atom-view.ProseMirror-selectednode),
+        .prosemirror-editor :deep(.boxel-card-block-view.ProseMirror-selectednode) {
+          outline: 2px solid var(--boxel-highlight, #0078d4);
+          border-radius: var(--boxel-border-radius, 4px);
+        }
+
+        /* Fallback for unresolved card references */
+        .prosemirror-editor :deep(.prosemirror-card-fallback) {
+          display: inline-block;
+          padding: 1px 6px;
+          background-color: var(--boxel-100, #f0f0f0);
+          border: 1px dashed var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          font-size: 0.85em;
+          color: var(--boxel-400, #666);
+          word-break: break-all;
+        }
+
         .prosemirror-editor-loading {
           min-height: 120px;
           display: flex;
diff --git a/packages/base/rich-markdown.gts b/packages/base/rich-markdown.gts
index a85ade78254..d890d3160d2 100644
--- a/packages/base/rich-markdown.gts
+++ b/packages/base/rich-markdown.gts
@@ -89,10 +89,23 @@ export class RichMarkdownField extends FieldDef {
     updateContent = (markdown: string) => {
       this.args.model.content = markdown;
     };
+    get baseUrl(): string | null {
+      return this.args.model?.[relativeTo]?.href ?? null;
+    }
+    get linkedCards(): CardDef[] | null {
+      try {
+        return this.args.model?.linkedCards ?? null;
+      } catch {
+        // linksToMany query may fail in environments without a full card store
+        return null;
+      }
+    }
     <template>
       <ProseMirrorEditor
         @content={{@model.content}}
         @onUpdate={{this.updateContent}}
+        @linkedCards={{this.linkedCards}}
+        @cardReferenceBaseUrl={{this.baseUrl}}
       />
     </template>
   };
diff --git a/packages/host/app/lib/prosemirror-context.ts b/packages/host/app/lib/prosemirror-context.ts
index 4a0ada2de90..5a77761b833 100644
--- a/packages/host/app/lib/prosemirror-context.ts
+++ b/packages/host/app/lib/prosemirror-context.ts
@@ -672,6 +672,83 @@ function serializeMarkdown(doc: ProseMirrorNode): string {
   return blocks.join('\n\n');
 }
 
+// ── Card nodeView factories ───────────────────────────────────────────────
+
+export interface CardNodeViewTarget {
+  element: HTMLElement;
+  cardId: string;
+  format: 'atom' | 'embedded';
+  kind: 'inline' | 'block';
+}
+
+function createCardNodeViews(
+  onChange: (targets: CardNodeViewTarget[]) => void,
+): Record<string, (node: ProseMirrorNode) => Record<string, unknown>> {
+  let targets: CardNodeViewTarget[] = [];
+
+  function notify() {
+    onChange([...targets]);
+  }
+
+  return {
+    boxel_card_atom(node: ProseMirrorNode) {
+      let dom = document.createElement('span');
+      dom.classList.add('boxel-card-atom-view');
+      dom.setAttribute('data-card-id', node.attrs.cardId);
+      dom.contentEditable = 'false';
+
+      let target: CardNodeViewTarget = {
+        element: dom,
+        cardId: node.attrs.cardId,
+        format: 'atom',
+        kind: 'inline',
+      };
+      targets.push(target);
+      notify();
+
+      return {
+        dom,
+        ignoreMutation: () => true,
+        destroy() {
+          let idx = targets.indexOf(target);
+          if (idx >= 0) {
+            targets.splice(idx, 1);
+          }
+          notify();
+        },
+      };
+    },
+
+    boxel_card_block(node: ProseMirrorNode) {
+      let dom = document.createElement('div');
+      dom.classList.add('boxel-card-block-view');
+      dom.setAttribute('data-card-id', node.attrs.cardId);
+      dom.contentEditable = 'false';
+
+      let target: CardNodeViewTarget = {
+        element: dom,
+        cardId: node.attrs.cardId,
+        format: 'embedded',
+        kind: 'block',
+      };
+      targets.push(target);
+      notify();
+
+      return {
+        dom,
+        ignoreMutation: () => true,
+        destroy() {
+          let idx = targets.indexOf(target);
+          if (idx >= 0) {
+            targets.splice(idx, 1);
+          }
+          notify();
+        },
+      };
+    },
+  };
+}
+
 // ── Exported context ───────────────────────────────────────────────────────
 
 export interface ProseMirrorContext {
@@ -693,6 +770,7 @@ export interface ProseMirrorContext {
   sinkListItem: typeof sinkListItem;
   parseMarkdown: (text: string) => ProseMirrorNode;
   serializeMarkdown: (doc: ProseMirrorNode) => string;
+  createCardNodeViews: typeof createCardNodeViews;
 }
 
 const prosemirrorContext: ProseMirrorContext = {
@@ -714,6 +792,7 @@ const prosemirrorContext: ProseMirrorContext = {
   sinkListItem,
   parseMarkdown,
   serializeMarkdown,
+  createCardNodeViews,
 };
 
 export default prosemirrorContext;
diff --git a/packages/host/tests/integration/components/prosemirror-editor-test.gts b/packages/host/tests/integration/components/prosemirror-editor-test.gts
index a6522c087b2..6ad1e815d1f 100644
--- a/packages/host/tests/integration/components/prosemirror-editor-test.gts
+++ b/packages/host/tests/integration/components/prosemirror-editor-test.gts
@@ -585,6 +585,216 @@ module('Integration | prosemirror-context', function (hooks) {
     view.destroy();
   });
 
+  // ── Card nodeView tests ──
+
+  test('createCardNodeViews registers atom targets', function (assert) {
+    let receivedTargets: any[] = [];
+    let nodeViews = pmContext.createCardNodeViews((targets: any[]) => {
+      receivedTargets = targets;
+    });
+
+    assert.ok(nodeViews.boxel_card_atom, 'has boxel_card_atom nodeView');
+    assert.ok(nodeViews.boxel_card_block, 'has boxel_card_block nodeView');
+
+    let atomNode = pmContext.schema.nodes.boxel_card_atom.create({
+      cardId: './Author/alice',
+      label: 'alice',
+    });
+    let nv = nodeViews.boxel_card_atom(atomNode);
+
+    assert.ok(nv.dom, 'nodeView has dom element');
+    assert.strictEqual(
+      nv.dom.tagName,
+      'SPAN',
+      'atom nodeView uses span element',
+    );
+    assert.strictEqual(
+      nv.dom.getAttribute('data-card-id'),
+      './Author/alice',
+      'dom has data-card-id attribute',
+    );
+    assert.strictEqual(
+      nv.dom.classList.contains('boxel-card-atom-view'),
+      true,
+      'dom has boxel-card-atom-view class',
+    );
+    assert.strictEqual(receivedTargets.length, 1, 'one target registered');
+    assert.strictEqual(
+      receivedTargets[0].cardId,
+      './Author/alice',
+      'target has correct cardId',
+    );
+    assert.strictEqual(
+      receivedTargets[0].format,
+      'atom',
+      'target has atom format',
+    );
+    assert.strictEqual(
+      receivedTargets[0].kind,
+      'inline',
+      'target has inline kind',
+    );
+
+    nv.destroy();
+    assert.strictEqual(
+      receivedTargets.length,
+      0,
+      'target unregistered on destroy',
+    );
+  });
+
+  test('createCardNodeViews registers block targets', function (assert) {
+    let receivedTargets: any[] = [];
+    let nodeViews = pmContext.createCardNodeViews((targets: any[]) => {
+      receivedTargets = targets;
+    });
+
+    let blockNode = pmContext.schema.nodes.boxel_card_block.create({
+      cardId: './Author/alice',
+    });
+    let nv = nodeViews.boxel_card_block(blockNode);
+
+    assert.ok(nv.dom, 'nodeView has dom element');
+    assert.strictEqual(
+      nv.dom.tagName,
+      'DIV',
+      'block nodeView uses div element',
+    );
+    assert.strictEqual(
+      nv.dom.getAttribute('data-card-id'),
+      './Author/alice',
+      'dom has data-card-id attribute',
+    );
+    assert.strictEqual(
+      receivedTargets.length,
+      1,
+      'one target registered',
+    );
+    assert.strictEqual(
+      receivedTargets[0].format,
+      'embedded',
+      'target has embedded format',
+    );
+    assert.strictEqual(
+      receivedTargets[0].kind,
+      'block',
+      'target has block kind',
+    );
+
+    nv.destroy();
+    assert.strictEqual(
+      receivedTargets.length,
+      0,
+      'target unregistered on destroy',
+    );
+  });
+
+  test('createCardNodeViews tracks multiple targets', function (assert) {
+    let receivedTargets: any[] = [];
+    let nodeViews = pmContext.createCardNodeViews((targets: any[]) => {
+      receivedTargets = targets;
+    });
+
+    let atom1 = pmContext.schema.nodes.boxel_card_atom.create({
+      cardId: './Card/1',
+      label: '1',
+    });
+    let atom2 = pmContext.schema.nodes.boxel_card_atom.create({
+      cardId: './Card/2',
+      label: '2',
+    });
+    let block1 = pmContext.schema.nodes.boxel_card_block.create({
+      cardId: './Card/3',
+    });
+
+    let nv1 = nodeViews.boxel_card_atom(atom1);
+    let nv2 = nodeViews.boxel_card_atom(atom2);
+    let nv3 = nodeViews.boxel_card_block(block1);
+
+    assert.strictEqual(receivedTargets.length, 3, 'three targets registered');
+
+    nv2.destroy();
+    assert.strictEqual(
+      receivedTargets.length,
+      2,
+      'two targets after destroying middle',
+    );
+    assert.strictEqual(
+      receivedTargets[0].cardId,
+      './Card/1',
+      'first target preserved',
+    );
+    assert.strictEqual(
+      receivedTargets[1].cardId,
+      './Card/3',
+      'third target preserved',
+    );
+
+    nv1.destroy();
+    nv3.destroy();
+    assert.strictEqual(receivedTargets.length, 0, 'all targets cleared');
+  });
+
+  test('EditorView with nodeViews renders card containers', async function (assert) {
+    let doc = pmContext.parseMarkdown(
+      'Text with :card[./Author/alice] and\n\n::card[./Post/1]',
+    );
+    let state = pmContext.EditorState.create({ doc });
+
+    await render(<template><div id='pm-mount'></div></template>);
+
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    let targets: any[] = [];
+    let nodeViews = pmContext.createCardNodeViews((t: any[]) => {
+      targets = t;
+    });
+
+    let view = new pmContext.EditorView(mountEl, { state, nodeViews });
+
+    assert.ok(
+      mountEl.querySelector('.boxel-card-atom-view'),
+      'card atom nodeView container renders',
+    );
+    assert.ok(
+      mountEl.querySelector('.boxel-card-block-view'),
+      'card block nodeView container renders',
+    );
+    assert.strictEqual(targets.length, 2, 'two targets registered');
+    assert.strictEqual(
+      targets[0].cardId,
+      './Author/alice',
+      'atom target has correct cardId',
+    );
+    assert.strictEqual(
+      targets[1].cardId,
+      './Post/1',
+      'block target has correct cardId',
+    );
+
+    view.destroy();
+    assert.strictEqual(
+      targets.length,
+      0,
+      'targets cleared after view destroy',
+    );
+  });
+
+  test('nodeView ignoreMutation returns true', function (assert) {
+    let nodeViews = pmContext.createCardNodeViews(() => {});
+    let atomNode = pmContext.schema.nodes.boxel_card_atom.create({
+      cardId: './Card/1',
+      label: '1',
+    });
+    let nv = nodeViews.boxel_card_atom(atomNode);
+
+    assert.true(
+      nv.ignoreMutation(),
+      'ignoreMutation returns true to prevent ProseMirror from handling DOM mutations in card content',
+    );
+
+    nv.destroy();
+  });
+
   // ── Lazy-loading via globalThis (component pattern) ──
 
   test('globalThis.__loadProseMirror loader works', async function (assert) {
diff --git a/packages/host/tests/integration/components/rich-markdown-field-test.gts b/packages/host/tests/integration/components/rich-markdown-field-test.gts
index fdd5203927c..97bb4a73ab9 100644
--- a/packages/host/tests/integration/components/rich-markdown-field-test.gts
+++ b/packages/host/tests/integration/components/rich-markdown-field-test.gts
@@ -78,7 +78,7 @@ module('Integration | RichMarkdownField', function (hooks) {
     assert.dom(root.querySelector('strong')).hasText('bold');
   });
 
-  test('edit template renders textarea for content', async function (assert) {
+  test('edit template renders ProseMirror editor for content', async function (assert) {
     class TestCard extends CardDef {
       @field body = contains(RichMarkdownField);
       static edit = class Edit extends Component<typeof this> {
@@ -97,8 +97,14 @@ module('Integration | RichMarkdownField', function (hooks) {
       body: new RichMarkdownField({ content: 'Edit me' }),
     });
     let root = await renderCard(loader, card, 'edit');
-    assert.dom(root.querySelector('textarea')).exists('textarea is rendered');
-    assert.dom(root.querySelector('textarea')).hasValue('Edit me');
+    // ProseMirrorEditor shows a loading state or the editor depending on
+    // whether the lazy module is available in the test environment
+    let editor = root.querySelector('[data-test-prosemirror-editor]');
+    let loading = root.querySelector('[data-test-prosemirror-loading]');
+    assert.ok(
+      editor || loading,
+      'ProseMirror editor or loading state is rendered',
+    );
   });
 
   test('renders with null content without error', async function (assert) {

From 275b6f2a6b39dda828a698d782d3b4f406ad80fa Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Wed, 8 Apr 2026 07:26:10 -0400
Subject: [PATCH 50/50] Add card insertion UX with slash command in Compose
 mode (CS-10575)

Implement /card slash command in ProseMirror editor that lets users insert
card references. Typing "/" triggers a contextual command menu, selecting
"Card" opens a search/URL-paste popup, then a format picker (inline/block)
inserts the reference at the cursor position. The slash command system is
extensible for future commands.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/base/prosemirror-editor.gts          | 636 ++++++++++++++++++
 packages/base/rich-markdown.gts               |  16 +-
 packages/host/app/lib/prosemirror-context.ts  | 141 +++-
 .../components/prosemirror-editor-test.gts    | 276 ++++++++
 4 files changed, 1062 insertions(+), 7 deletions(-)

diff --git a/packages/base/prosemirror-editor.gts b/packages/base/prosemirror-editor.gts
index 9724685847e..0d9fec2d202 100644
--- a/packages/base/prosemirror-editor.gts
+++ b/packages/base/prosemirror-editor.gts
@@ -2,11 +2,15 @@ import { task } from 'ember-concurrency';
 import GlimmerComponent from '@glimmer/component';
 import { cached, tracked } from '@glimmer/tracking';
 import { modifier } from 'ember-modifier';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
 import { scheduleOnce } from '@ember/runloop';
+import { eq } from '@cardstack/boxel-ui/helpers';
 
 import {
   resolveCardReference,
   trimJsonExtension,
+  maybeRelativeURL,
 } from '@cardstack/runtime-common';
 import { type BaseDef, type CardDef, getComponent } from './card-api';
 import { CardContextConsumer } from './field-component';
@@ -47,8 +51,30 @@ interface ProseMirrorContext {
   createCardNodeViews: (
     onChange: (targets: CardNodeViewTarget[]) => void,
   ) => Record<string, any>;
+  createSlashCommandPlugin: (
+    onStateChange: (state: SlashCommandState | null) => void,
+    onSelectItem: (index: number) => void,
+    onNavigate: (direction: 'up' | 'down') => void,
+  ) => any;
+  slashCommandPluginKey: any;
 }
 
+interface SlashCommandState {
+  active: boolean;
+  query: string;
+  from: number;
+}
+
+interface SlashMenuItem {
+  id: string;
+  label: string;
+  description: string;
+}
+
+const SLASH_COMMANDS: SlashMenuItem[] = [
+  { id: 'card', label: 'Card', description: 'Insert a card reference' },
+];
+
 const SAVE_DEBOUNCE_MS = 500;
 
 function isInline(kind: string): boolean {
@@ -63,12 +89,31 @@ function resolveUrl(raw: string, baseUrl: string | null | undefined): string {
   }
 }
 
+function makeCardRef(cardUrl: string, baseUrl: string | null | undefined): string {
+  if (!baseUrl) return cardUrl;
+  try {
+    return maybeRelativeURL(new URL(cardUrl), new URL(baseUrl), undefined);
+  } catch {
+    return cardUrl;
+  }
+}
+
+function labelFromUrl(url: string): string {
+  let cleaned = trimJsonExtension(url);
+  let parts = cleaned.split('/');
+  return parts[parts.length - 1] || cleaned;
+}
+
 interface ProseMirrorEditorSignature {
   Args: {
     content: string | null;
     onUpdate: (markdown: string) => void;
     linkedCards?: CardDef[] | null;
     cardReferenceBaseUrl?: string | null;
+    getCards?: (
+      parent: object,
+      getQuery: () => Record<string, unknown> | undefined,
+    ) => { instances: CardDef[]; isLoading: boolean } | undefined;
   };
   Element: HTMLDivElement;
 }
@@ -82,6 +127,20 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
   // Glimmer backtracking assertions.
   private _pendingTargets: CardNodeViewTarget[] = [];
 
+  // ── Slash command state ──────────────────────────────────────────────────
+  @tracked _slashState: SlashCommandState | null = null;
+  @tracked _slashMenuIndex = 0;
+  @tracked _menuCoords: { left: number; top: number } | null = null;
+
+  // Card search mode (after selecting /card)
+  @tracked _cardSearchMode = false;
+  @tracked _cardSearchText = '';
+  @tracked _cardSearchIndex = 0;
+
+  // Format picker (after selecting a card from search)
+  @tracked _formatPickerCardUrl: string | null = null;
+  @tracked _formatPickerCardTitle: string | null = null;
+
   get pm(): ProseMirrorContext | null {
     if (!this._pm) {
       this._loadProseMirrorTask.perform();
@@ -102,6 +161,288 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
   private saveTimer: ReturnType<typeof setTimeout> | null = null;
   private _slotUpdatePending = false;
 
+  // ── Slash command logic ────────────────────────────────────────────────
+
+  get slashMenuActive(): boolean {
+    return this._slashState?.active === true && !this._cardSearchMode && !this._formatPickerCardUrl;
+  }
+
+  get filteredSlashCommands(): SlashMenuItem[] {
+    let query = (this._slashState?.query ?? '').toLowerCase();
+    if (!query) return SLASH_COMMANDS;
+    return SLASH_COMMANDS.filter((cmd) => cmd.id.startsWith(query));
+  }
+
+  get slashMenuStyle(): string {
+    let coords = this._menuCoords;
+    if (!coords) return 'display: none';
+    return `left: ${coords.left}px; top: ${coords.top}px;`;
+  }
+
+  private _updateMenuCoords() {
+    let view = this.editorView;
+    let state = this._slashState;
+    if (!view || !state) {
+      this._menuCoords = null;
+      return;
+    }
+    try {
+      let coords = view.coordsAtPos(state.from);
+      let editorRect = view.dom.closest('.prosemirror-editor')?.getBoundingClientRect();
+      if (editorRect) {
+        this._menuCoords = {
+          left: coords.left - editorRect.left,
+          top: coords.bottom - editorRect.top + 4,
+        };
+      }
+    } catch {
+      this._menuCoords = null;
+    }
+  }
+
+  private _handleSlashStateChange = (state: SlashCommandState | null) => {
+    if (!state?.active && this._slashState?.active) {
+      // Slash menu closing — if we're not in card search mode, clean up
+      if (!this._cardSearchMode && !this._formatPickerCardUrl) {
+        this._slashState = null;
+        this._menuCoords = null;
+        this._slashMenuIndex = 0;
+        return;
+      }
+    }
+    this._slashState = state;
+    this._slashMenuIndex = 0;
+    if (state?.active) {
+      this._updateMenuCoords();
+    } else if (!this._cardSearchMode && !this._formatPickerCardUrl) {
+      this._menuCoords = null;
+    }
+  };
+
+  private _handleSlashNavigate = (direction: 'up' | 'down') => {
+    if (this._cardSearchMode) {
+      let results = this.cardSearchResults;
+      let max = results.length;
+      if (max === 0) return;
+      if (direction === 'down') {
+        this._cardSearchIndex = (this._cardSearchIndex + 1) % max;
+      } else {
+        this._cardSearchIndex = (this._cardSearchIndex - 1 + max) % max;
+      }
+      return;
+    }
+    let items = this.filteredSlashCommands;
+    let max = items.length;
+    if (max === 0) return;
+    if (direction === 'down') {
+      this._slashMenuIndex = (this._slashMenuIndex + 1) % max;
+    } else {
+      this._slashMenuIndex = (this._slashMenuIndex - 1 + max) % max;
+    }
+  };
+
+  private _handleSlashSelect = (_index: number) => {
+    if (this._formatPickerCardUrl) {
+      // Enter in format picker defaults to block
+      this._insertCardWithFormat('block');
+      return;
+    }
+    if (this._cardSearchMode) {
+      let results = this.cardSearchResults;
+      let card = results[this._cardSearchIndex];
+      if (card) {
+        this._selectCardResult(card);
+      }
+      return;
+    }
+    let items = this.filteredSlashCommands;
+    let item = items[this._slashMenuIndex];
+    if (item) {
+      this._selectSlashCommand(item);
+    }
+  };
+
+  _selectSlashCommand = (cmd: SlashMenuItem) => {
+    if (cmd.id === 'card') {
+      // Delete the slash command text from the editor
+      let view = this.editorView;
+      let pm = this._pm;
+      let state = this._slashState;
+      if (view && pm && state) {
+        let pluginKey = pm.slashCommandPluginKey;
+        let tr = view.state.tr
+          .delete(state.from, view.state.selection.from)
+          .setMeta(pluginKey, null);
+        view.dispatch(tr);
+      }
+      this._cardSearchMode = true;
+      this._cardSearchText = '';
+      this._cardSearchIndex = 0;
+      // Focus the search input after render
+      scheduleOnce('afterRender', this, this._focusSearchInput);
+    }
+  };
+
+  private _focusSearchInput = () => {
+    let input = document.querySelector('[data-test-card-search-input]') as HTMLInputElement;
+    input?.focus();
+  };
+
+  // ── Card search ──────────────────────────────────────────────────────────
+
+  private _searchResourceCreated = false;
+  private _searchResource: { instances: CardDef[]; isLoading: boolean } | null = null;
+
+  get cardSearchResults(): CardDef[] {
+    if (!this._cardSearchMode) return [];
+    if (!this._searchResourceCreated) {
+      this._searchResourceCreated = true;
+      try {
+        let getCards = this.args.getCards;
+        if (typeof getCards === 'function') {
+          this._searchResource = getCards(
+            this,
+            () => {
+              let text = this._cardSearchText?.trim();
+              if (!text) return undefined;
+              return {
+                filter: { contains: { name: text } },
+                page: { size: 10 },
+              };
+            },
+          ) ?? null;
+        }
+      } catch {
+        // Card search not available
+      }
+    }
+    return this._searchResource?.instances ?? [];
+  }
+
+  get isSearchLoading(): boolean {
+    return this._searchResource?.isLoading ?? false;
+  }
+
+  _handleCardSearchInput = (event: Event) => {
+    this._cardSearchText = (event.target as HTMLInputElement).value;
+    this._cardSearchIndex = 0;
+  };
+
+  _handleCardSearchKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      this._dismissCardSearch();
+      return;
+    }
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      this._handleSlashNavigate('down');
+      return;
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      this._handleSlashNavigate('up');
+      return;
+    }
+    if (event.key === 'Enter') {
+      event.preventDefault();
+      // Check if the input looks like a URL
+      let text = this._cardSearchText.trim();
+      if (text && (text.startsWith('http://') || text.startsWith('https://') || text.startsWith('./'))) {
+        this._formatPickerCardUrl = text;
+        this._formatPickerCardTitle = labelFromUrl(text);
+        this._cardSearchMode = false;
+        return;
+      }
+      // Otherwise select the highlighted search result
+      let results = this.cardSearchResults;
+      let card = results[this._cardSearchIndex];
+      if (card) {
+        this._selectCardResult(card);
+      }
+      return;
+    }
+  };
+
+  _selectCardResult = (card: CardDef) => {
+    if (!card.id) return;
+    this._formatPickerCardUrl = card.id;
+    this._formatPickerCardTitle = card.title ?? labelFromUrl(card.id);
+    this._cardSearchMode = false;
+  };
+
+  _dismissCardSearch = () => {
+    this._cardSearchMode = false;
+    this._cardSearchText = '';
+    this._cardSearchIndex = 0;
+    this._slashState = null;
+    this._menuCoords = null;
+    this.editorView?.focus();
+  };
+
+  // ── Card insertion ───────────────────────────────────────────────────────
+
+  _insertCardWithFormat = (format: string) => {
+    let cardUrl = this._formatPickerCardUrl;
+    if (!cardUrl) return;
+
+    let view = this.editorView;
+    let pm = this._pm;
+    if (!view || !pm) return;
+
+    let baseUrl = this.args.cardReferenceBaseUrl;
+    let ref = makeCardRef(cardUrl, baseUrl);
+
+    if (format === 'inline') {
+      let node = pm.schema.nodes.boxel_card_atom.create({
+        cardId: ref,
+        label: labelFromUrl(ref),
+      });
+      let { from } = view.state.selection;
+      let tr = view.state.tr.insert(from, node);
+      view.dispatch(tr);
+    } else {
+      let node = pm.schema.nodes.boxel_card_block.create({
+        cardId: ref,
+      });
+      let { from } = view.state.selection;
+      let $pos = view.state.doc.resolve(from);
+      // Insert after the current block
+      let insertPos = $pos.after($pos.depth);
+      let tr = view.state.tr.insert(insertPos, node);
+      view.dispatch(tr);
+    }
+
+    // Clean up all popup state
+    this._formatPickerCardUrl = null;
+    this._formatPickerCardTitle = null;
+    this._cardSearchMode = false;
+    this._cardSearchText = '';
+    this._slashState = null;
+    this._menuCoords = null;
+
+    view.focus();
+
+    // Trigger save immediately
+    let onUpdate = this.args.onUpdate;
+    if (onUpdate && pm) {
+      if (this.saveTimer) {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = null;
+      }
+      let markdown = pm.serializeMarkdown(view.state.doc);
+      onUpdate(markdown);
+    }
+  };
+
+  _dismissFormatPicker = () => {
+    this._formatPickerCardUrl = null;
+    this._formatPickerCardTitle = null;
+    this._slashState = null;
+    this._menuCoords = null;
+    this.editorView?.focus();
+  };
+
   // ── Card slot resolution ───────────────────────────────────────────────
 
   @cached
@@ -204,9 +545,16 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
         'Shift-Tab': liftListItem(schema.nodes.list_item),
       };
 
+      let slashPlugin = pm.createSlashCommandPlugin(
+        this._handleSlashStateChange,
+        this._handleSlashSelect,
+        this._handleSlashNavigate,
+      );
+
       let state = pm.EditorState.create({
         doc,
         plugins: [
+          slashPlugin,
           keymapPlugin(formatKeymap),
           keymapPlugin(listKeymap),
           keymapPlugin(baseKeymap),
@@ -325,6 +673,104 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
         ...attributes
       >
       </div>
+
+      {{! ── Slash command menu ── }}
+      {{#if this.slashMenuActive}}
+        <div
+          class='prosemirror-slash-menu'
+          style={{this.slashMenuStyle}}
+          data-test-slash-menu
+        >
+          {{#each this.filteredSlashCommands as |cmd index|}}
+            <button
+              class='prosemirror-slash-menu-item
+                {{if (eq index this._slashMenuIndex) "selected"}}'
+              data-test-slash-menu-item={{cmd.id}}
+              {{on 'mousedown' (fn this._selectSlashCommand cmd)}}
+            >
+              <span class='slash-menu-label'>{{cmd.label}}</span>
+              <span class='slash-menu-description'>{{cmd.description}}</span>
+            </button>
+          {{else}}
+            <div class='prosemirror-slash-menu-empty'>No matching commands</div>
+          {{/each}}
+        </div>
+      {{/if}}
+
+      {{! ── Card search popup ── }}
+      {{#if this._cardSearchMode}}
+        <div
+          class='prosemirror-card-search'
+          style={{this.slashMenuStyle}}
+          data-test-card-search
+        >
+          <input
+            class='prosemirror-card-search-input'
+            placeholder='Search cards or paste URL…'
+            value={{this._cardSearchText}}
+            data-test-card-search-input
+            {{on 'input' this._handleCardSearchInput}}
+            {{on 'keydown' this._handleCardSearchKeydown}}
+          />
+          {{#if this.isSearchLoading}}
+            <div class='prosemirror-card-search-loading'>Searching…</div>
+          {{/if}}
+          {{#if this.cardSearchResults.length}}
+            <div class='prosemirror-card-search-results' data-test-card-search-results>
+              {{#each this.cardSearchResults as |card index|}}
+                <button
+                  class='prosemirror-card-search-result
+                    {{if (eq index this._cardSearchIndex) "selected"}}'
+                  data-test-card-search-result
+                  {{on 'mousedown' (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 ── }}
+      {{#if this._formatPickerCardUrl}}
+        <div
+          class='prosemirror-format-picker'
+          style={{this.slashMenuStyle}}
+          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' (fn this._insertCardWithFormat 'inline')}}
+            >
+              Inline
+            </button>
+            <button
+              class='format-picker-btn format-picker-btn--primary'
+              data-test-format-block
+              {{on 'mousedown' (fn this._insertCardWithFormat 'block')}}
+            >
+              Block
+            </button>
+          </div>
+          <button
+            class='format-picker-dismiss'
+            data-test-format-picker-dismiss
+            {{on 'mousedown' this._dismissFormatPicker}}
+          >
+            Cancel
+          </button>
+        </div>
+      {{/if}}
+
       {{#each this.cardRenderTargets as |target|}}
         {{#in-element target.element insertBefore=null}}
           {{#if target.card}}
@@ -383,6 +829,7 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
           border: 1px solid var(--boxel-border-color, #c4c4c4);
           border-radius: var(--boxel-border-radius, 4px);
           cursor: text;
+          position: relative;
         }
 
         .prosemirror-editor :deep(.ProseMirror) {
@@ -534,6 +981,195 @@ export default class ProseMirrorEditor extends GlimmerComponent<ProseMirrorEdito
           color: var(--boxel-400, #999);
           font-style: italic;
         }
+
+        /* ── Slash command menu ── */
+        .prosemirror-slash-menu {
+          position: absolute;
+          z-index: 100;
+          background: var(--boxel-light, #fff);
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          box-shadow: 0 4px 12px rgb(0 0 0 / 0.15);
+          min-width: 200px;
+          max-width: 300px;
+          padding: 4px;
+        }
+
+        .prosemirror-slash-menu-item {
+          display: flex;
+          flex-direction: column;
+          align-items: flex-start;
+          width: 100%;
+          padding: 8px 12px;
+          border: none;
+          background: transparent;
+          cursor: pointer;
+          border-radius: var(--boxel-border-radius, 4px);
+          text-align: left;
+          font: inherit;
+        }
+
+        .prosemirror-slash-menu-item:hover,
+        .prosemirror-slash-menu-item.selected {
+          background: var(--boxel-highlight-hover, #e8f0fe);
+        }
+
+        .slash-menu-label {
+          font-weight: 600;
+          font-size: 0.9em;
+        }
+
+        .slash-menu-description {
+          font-size: 0.8em;
+          color: var(--boxel-400, #666);
+        }
+
+        .prosemirror-slash-menu-empty {
+          padding: 8px 12px;
+          color: var(--boxel-400, #666);
+          font-size: 0.85em;
+          font-style: italic;
+        }
+
+        /* ── Card search popup ── */
+        .prosemirror-card-search {
+          position: absolute;
+          z-index: 100;
+          background: var(--boxel-light, #fff);
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          box-shadow: 0 4px 12px rgb(0 0 0 / 0.15);
+          min-width: 280px;
+          max-width: 400px;
+          padding: 8px;
+        }
+
+        .prosemirror-card-search-input {
+          width: 100%;
+          padding: 6px 10px;
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          font: inherit;
+          font-size: 0.9em;
+          outline: none;
+          box-sizing: border-box;
+        }
+
+        .prosemirror-card-search-input:focus {
+          border-color: var(--boxel-highlight, #0078d4);
+          box-shadow: 0 0 0 1px var(--boxel-highlight, #0078d4);
+        }
+
+        .prosemirror-card-search-loading {
+          padding: 8px 4px;
+          color: var(--boxel-400, #666);
+          font-size: 0.85em;
+          font-style: italic;
+        }
+
+        .prosemirror-card-search-results {
+          margin-top: 4px;
+          max-height: 240px;
+          overflow-y: auto;
+        }
+
+        .prosemirror-card-search-result {
+          display: flex;
+          flex-direction: column;
+          align-items: flex-start;
+          width: 100%;
+          padding: 6px 10px;
+          border: none;
+          background: transparent;
+          cursor: pointer;
+          border-radius: var(--boxel-border-radius, 4px);
+          text-align: left;
+          font: inherit;
+        }
+
+        .prosemirror-card-search-result:hover,
+        .prosemirror-card-search-result.selected {
+          background: var(--boxel-highlight-hover, #e8f0fe);
+        }
+
+        .search-result-title {
+          font-weight: 500;
+          font-size: 0.9em;
+        }
+
+        .search-result-url {
+          font-size: 0.75em;
+          color: var(--boxel-400, #666);
+          word-break: break-all;
+        }
+
+        /* ── Format picker popup ── */
+        .prosemirror-format-picker {
+          position: absolute;
+          z-index: 100;
+          background: var(--boxel-light, #fff);
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          box-shadow: 0 4px 12px rgb(0 0 0 / 0.15);
+          padding: 12px;
+          min-width: 220px;
+        }
+
+        .format-picker-label {
+          display: block;
+          font-size: 0.85em;
+          color: var(--boxel-400, #666);
+          margin-bottom: 8px;
+          word-break: break-word;
+        }
+
+        .format-picker-buttons {
+          display: flex;
+          gap: 8px;
+          margin-bottom: 8px;
+        }
+
+        .format-picker-btn {
+          flex: 1;
+          padding: 6px 12px;
+          border: 1px solid var(--boxel-border-color, #c4c4c4);
+          border-radius: var(--boxel-border-radius, 4px);
+          background: var(--boxel-light, #fff);
+          cursor: pointer;
+          font: inherit;
+          font-size: 0.9em;
+        }
+
+        .format-picker-btn:hover {
+          background: var(--boxel-highlight-hover, #e8f0fe);
+        }
+
+        .format-picker-btn--primary {
+          background: var(--boxel-highlight, #0078d4);
+          color: white;
+          border-color: var(--boxel-highlight, #0078d4);
+        }
+
+        .format-picker-btn--primary:hover {
+          opacity: 0.9;
+        }
+
+        .format-picker-dismiss {
+          display: block;
+          width: 100%;
+          padding: 4px;
+          border: none;
+          background: transparent;
+          color: var(--boxel-400, #666);
+          cursor: pointer;
+          font: inherit;
+          font-size: 0.8em;
+          text-align: center;
+        }
+
+        .format-picker-dismiss:hover {
+          color: var(--boxel-dark, #333);
+        }
       }
     </style>
   </template>
diff --git a/packages/base/rich-markdown.gts b/packages/base/rich-markdown.gts
index d890d3160d2..385652decf9 100644
--- a/packages/base/rich-markdown.gts
+++ b/packages/base/rich-markdown.gts
@@ -16,6 +16,7 @@ import {
 } from './card-api';
 import MarkdownTemplate from './default-templates/markdown';
 import ProseMirrorEditor from './prosemirror-editor';
+import { CardContextConsumer } from './field-component';
 
 /**
  * A composite FieldDef that stores markdown content and exposes structured
@@ -101,12 +102,15 @@ export class RichMarkdownField extends FieldDef {
       }
     }
     <template>
-      <ProseMirrorEditor
-        @content={{@model.content}}
-        @onUpdate={{this.updateContent}}
-        @linkedCards={{this.linkedCards}}
-        @cardReferenceBaseUrl={{this.baseUrl}}
-      />
+      <CardContextConsumer as |context|>
+        <ProseMirrorEditor
+          @content={{@model.content}}
+          @onUpdate={{this.updateContent}}
+          @linkedCards={{this.linkedCards}}
+          @cardReferenceBaseUrl={{this.baseUrl}}
+          @getCards={{context.getCards}}
+        />
+      </CardContextConsumer>
     </template>
   };
 }
diff --git a/packages/host/app/lib/prosemirror-context.ts b/packages/host/app/lib/prosemirror-context.ts
index 5a77761b833..43d3cdf13e7 100644
--- a/packages/host/app/lib/prosemirror-context.ts
+++ b/packages/host/app/lib/prosemirror-context.ts
@@ -11,7 +11,7 @@ import 'prosemirror-view/style/prosemirror.css';
 
 import { Schema } from 'prosemirror-model';
 import type { Node as ProseMirrorNode } from 'prosemirror-model';
-import { EditorState } from 'prosemirror-state';
+import { EditorState, Plugin, PluginKey } from 'prosemirror-state';
 import { EditorView } from 'prosemirror-view';
 import { keymap } from 'prosemirror-keymap';
 import { baseKeymap, toggleMark, setBlockType, lift } from 'prosemirror-commands';
@@ -749,6 +749,141 @@ function createCardNodeViews(
   };
 }
 
+// ── Slash command plugin ───────────────────────────────────────────────────
+
+export interface SlashCommandState {
+  active: boolean;
+  query: string; // text after "/" (e.g., "car" when user typed "/car")
+  from: number; // document position of the "/" character
+}
+
+export interface SlashMenuItem {
+  id: string;
+  label: string;
+  description: string;
+}
+
+const slashCommandPluginKey = new PluginKey<SlashCommandState | null>(
+  'slashCommand',
+);
+
+function createSlashCommandPlugin(
+  onStateChange: (state: SlashCommandState | null) => void,
+  onSelectItem: (index: number) => void,
+  onNavigate: (direction: 'up' | 'down') => void,
+): Plugin {
+  return new Plugin<SlashCommandState | null>({
+    key: slashCommandPluginKey,
+    state: {
+      init() {
+        return null;
+      },
+      apply(tr, prev, _oldState, newState) {
+        let meta = tr.getMeta(slashCommandPluginKey);
+        if (meta !== undefined) {
+          return meta;
+        }
+        if (!prev) {
+          return null;
+        }
+        if (tr.docChanged || tr.selectionSet) {
+          // Re-derive state from document text
+          let { from: slashFrom } = prev;
+          let mappedFrom = tr.docChanged
+            ? tr.mapping.map(slashFrom)
+            : slashFrom;
+          let cursorPos = newState.selection.from;
+          if (cursorPos <= mappedFrom) {
+            return null;
+          }
+          try {
+            let $pos = tr.doc.resolve(cursorPos);
+            let startOfNode = $pos.start();
+            let offsetInNode = mappedFrom - startOfNode;
+            let cursorOffset = cursorPos - startOfNode;
+            if (offsetInNode < 0 || cursorOffset > $pos.parent.content.size) {
+              return null;
+            }
+            let text = $pos.parent.textBetween(offsetInNode, cursorOffset);
+            if (!text.startsWith('/') || /\s/.test(text.slice(1))) {
+              return null;
+            }
+            let next: SlashCommandState = {
+              active: true,
+              query: text.slice(1),
+              from: mappedFrom,
+            };
+            return next;
+          } catch {
+            return null;
+          }
+        }
+        return prev;
+      },
+    },
+    props: {
+      handleTextInput(view, from, _to, text) {
+        if (text !== '/') {
+          return false;
+        }
+        let $pos = view.state.doc.resolve(from);
+        let textBefore = $pos.parent.textBetween(0, $pos.parentOffset);
+        if (textBefore.length === 0 || /\s$/.test(textBefore)) {
+          // Schedule activation after the "/" is inserted
+          setTimeout(() => {
+            let tr = view.state.tr.setMeta(slashCommandPluginKey, {
+              active: true,
+              query: '',
+              from,
+            } satisfies SlashCommandState);
+            view.dispatch(tr);
+          }, 0);
+        }
+        return false;
+      },
+      handleKeyDown(view, event) {
+        let state = slashCommandPluginKey.getState(view.state);
+        if (!state?.active) {
+          return false;
+        }
+        if (event.key === 'Escape') {
+          // Dismiss and delete the slash text
+          let tr = view.state.tr
+            .delete(state.from, view.state.selection.from)
+            .setMeta(slashCommandPluginKey, null);
+          view.dispatch(tr);
+          return true;
+        }
+        if (event.key === 'ArrowUp') {
+          onNavigate('up');
+          return true;
+        }
+        if (event.key === 'ArrowDown') {
+          onNavigate('down');
+          return true;
+        }
+        if (event.key === 'Enter') {
+          event.preventDefault();
+          onSelectItem(-1); // -1 means "select the currently highlighted item"
+          return true;
+        }
+        return false;
+      },
+    },
+    view() {
+      return {
+        update(view) {
+          let state = slashCommandPluginKey.getState(view.state);
+          onStateChange(state ?? null);
+        },
+        destroy() {
+          onStateChange(null);
+        },
+      };
+    },
+  });
+}
+
 // ── Exported context ───────────────────────────────────────────────────────
 
 export interface ProseMirrorContext {
@@ -771,6 +906,8 @@ export interface ProseMirrorContext {
   parseMarkdown: (text: string) => ProseMirrorNode;
   serializeMarkdown: (doc: ProseMirrorNode) => string;
   createCardNodeViews: typeof createCardNodeViews;
+  createSlashCommandPlugin: typeof createSlashCommandPlugin;
+  slashCommandPluginKey: typeof slashCommandPluginKey;
 }
 
 const prosemirrorContext: ProseMirrorContext = {
@@ -793,6 +930,8 @@ const prosemirrorContext: ProseMirrorContext = {
   parseMarkdown,
   serializeMarkdown,
   createCardNodeViews,
+  createSlashCommandPlugin,
+  slashCommandPluginKey,
 };
 
 export default prosemirrorContext;
diff --git a/packages/host/tests/integration/components/prosemirror-editor-test.gts b/packages/host/tests/integration/components/prosemirror-editor-test.gts
index 6ad1e815d1f..c8b8aaaced0 100644
--- a/packages/host/tests/integration/components/prosemirror-editor-test.gts
+++ b/packages/host/tests/integration/components/prosemirror-editor-test.gts
@@ -795,6 +795,282 @@ module('Integration | prosemirror-context', function (hooks) {
     nv.destroy();
   });
 
+  // ── Slash command plugin tests ──
+
+  test('createSlashCommandPlugin activates on "/" via setMeta', async function (assert) {
+    let doc = pmContext.parseMarkdown('');
+    let stateChanges: any[] = [];
+    let slashPlugin = pmContext.createSlashCommandPlugin(
+      (state: any) => { stateChanges.push(state); },
+      () => {},
+      () => {},
+    );
+    let state = pmContext.EditorState.create({
+      doc,
+      plugins: [slashPlugin],
+    });
+
+    await render(<template><div id='pm-mount'></div></template>);
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    let view = new pmContext.EditorView(mountEl, { state });
+
+    // Activate via setMeta (simulates what handleTextInput does internally)
+    let from = view.state.selection.from;
+    let tr = view.state.tr
+      .insertText('/', from, from)
+      .setMeta(pmContext.slashCommandPluginKey, {
+        active: true,
+        query: '',
+        from,
+      });
+    view.dispatch(tr);
+
+    let pluginState = pmContext.slashCommandPluginKey.getState(view.state);
+    assert.ok(
+      pluginState?.active,
+      'slash command plugin activates via setMeta',
+    );
+    assert.strictEqual(
+      pluginState?.query,
+      '',
+      'query is empty after just "/"',
+    );
+
+    // The view callback should have been called
+    assert.ok(
+      stateChanges.length > 0,
+      'onStateChange callback was called',
+    );
+
+    view.destroy();
+  });
+
+  test('createSlashCommandPlugin tracks query as user types', async function (assert) {
+    let doc = pmContext.parseMarkdown('');
+    let slashPlugin = pmContext.createSlashCommandPlugin(
+      () => {},
+      () => {},
+      () => {},
+    );
+    let state = pmContext.EditorState.create({
+      doc,
+      plugins: [slashPlugin],
+    });
+
+    await render(<template><div id='pm-mount'></div></template>);
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    let view = new pmContext.EditorView(mountEl, { state });
+
+    // Insert "/" and activate via setMeta
+    let from = view.state.selection.from;
+    let tr = view.state.tr
+      .insertText('/', from, from)
+      .setMeta(pmContext.slashCommandPluginKey, {
+        active: true,
+        query: '',
+        from,
+      });
+    view.dispatch(tr);
+
+    // Type "car" after the "/"
+    let pos = view.state.selection.from;
+    tr = view.state.tr.insertText('car', pos, pos);
+    view.dispatch(tr);
+
+    let pluginState = pmContext.slashCommandPluginKey.getState(view.state);
+    assert.strictEqual(
+      pluginState?.query,
+      'car',
+      'query tracks typed text after "/"',
+    );
+
+    view.destroy();
+  });
+
+  test('createSlashCommandPlugin deactivates on Escape', async function (assert) {
+    let doc = pmContext.parseMarkdown('');
+    let slashPlugin = pmContext.createSlashCommandPlugin(
+      () => {},
+      () => {},
+      () => {},
+    );
+    let state = pmContext.EditorState.create({
+      doc,
+      plugins: [slashPlugin],
+    });
+
+    await render(<template><div id='pm-mount'></div></template>);
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    let view = new pmContext.EditorView(mountEl, { state });
+
+    // Insert "/" and activate
+    let from = view.state.selection.from;
+    let tr = view.state.tr
+      .insertText('/', from, from)
+      .setMeta(pmContext.slashCommandPluginKey, {
+        active: true,
+        query: '',
+        from,
+      });
+    view.dispatch(tr);
+
+    assert.ok(
+      pmContext.slashCommandPluginKey.getState(view.state)?.active,
+      'plugin is active before Escape',
+    );
+
+    // Simulate Escape key — ProseMirror's handleKeyDown fires on focus+dispatch
+    view.dom.dispatchEvent(new KeyboardEvent('keydown', {
+      key: 'Escape',
+      bubbles: true,
+      cancelable: true,
+    }));
+
+    let pluginState = pmContext.slashCommandPluginKey.getState(view.state);
+    assert.notOk(
+      pluginState?.active,
+      'plugin deactivates after Escape',
+    );
+
+    view.destroy();
+  });
+
+  test('createSlashCommandPlugin calls onNavigate on ArrowUp/Down', async function (assert) {
+    let doc = pmContext.parseMarkdown('');
+    let navigations: string[] = [];
+    let slashPlugin = pmContext.createSlashCommandPlugin(
+      () => {},
+      () => {},
+      (direction: string) => { navigations.push(direction); },
+    );
+    let state = pmContext.EditorState.create({
+      doc,
+      plugins: [slashPlugin],
+    });
+
+    await render(<template><div id='pm-mount'></div></template>);
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    let view = new pmContext.EditorView(mountEl, { state });
+
+    // Activate slash command
+    let from = view.state.selection.from;
+    let tr = view.state.tr
+      .insertText('/', from, from)
+      .setMeta(pmContext.slashCommandPluginKey, {
+        active: true,
+        query: '',
+        from,
+      });
+    view.dispatch(tr);
+
+    // Simulate ArrowDown and ArrowUp
+    view.dom.dispatchEvent(new KeyboardEvent('keydown', {
+      key: 'ArrowDown',
+      bubbles: true,
+      cancelable: true,
+    }));
+    view.dom.dispatchEvent(new KeyboardEvent('keydown', {
+      key: 'ArrowUp',
+      bubbles: true,
+      cancelable: true,
+    }));
+
+    assert.deepEqual(
+      navigations,
+      ['down', 'up'],
+      'onNavigate called with correct directions',
+    );
+
+    view.destroy();
+  });
+
+  test('createSlashCommandPlugin calls onSelectItem on Enter', async function (assert) {
+    let doc = pmContext.parseMarkdown('');
+    let selections: number[] = [];
+    let slashPlugin = pmContext.createSlashCommandPlugin(
+      () => {},
+      (index: number) => { selections.push(index); },
+      () => {},
+    );
+    let state = pmContext.EditorState.create({
+      doc,
+      plugins: [slashPlugin],
+    });
+
+    await render(<template><div id='pm-mount'></div></template>);
+    let mountEl = document.querySelector('#pm-mount') as HTMLElement;
+    let view = new pmContext.EditorView(mountEl, { state });
+
+    // Activate slash command
+    let from = view.state.selection.from;
+    let tr = view.state.tr
+      .insertText('/', from, from)
+      .setMeta(pmContext.slashCommandPluginKey, {
+        active: true,
+        query: '',
+        from,
+      });
+    view.dispatch(tr);
+
+    // Simulate Enter
+    view.dom.dispatchEvent(new KeyboardEvent('keydown', {
+      key: 'Enter',
+      bubbles: true,
+      cancelable: true,
+    }));
+
+    assert.deepEqual(
+      selections,
+      [-1],
+      'onSelectItem called with -1 (select current item)',
+    );
+
+    view.destroy();
+  });
+
+  test('card node insertion creates correct inline node', function (assert) {
+    let doc = pmContext.parseMarkdown('Hello world');
+    let state = pmContext.EditorState.create({ doc });
+
+    // Insert an inline card atom at position 6 (after "Hello ")
+    let node = pmContext.schema.nodes.boxel_card_atom.create({
+      cardId: './Author/alice',
+      label: 'alice',
+    });
+    let tr = state.tr.insert(6, node);
+    let newState = state.apply(tr);
+    let markdown = pmContext.serializeMarkdown(newState.doc);
+
+    assert.ok(
+      markdown.includes(':card[./Author/alice]'),
+      'inline card reference serialized correctly',
+    );
+  });
+
+  test('card node insertion creates correct block node', function (assert) {
+    let doc = pmContext.parseMarkdown('Hello world');
+    let state = pmContext.EditorState.create({ doc });
+
+    // Insert a block card after the paragraph
+    let node = pmContext.schema.nodes.boxel_card_block.create({
+      cardId: './Post/1',
+    });
+    // Position after the paragraph end
+    let insertPos = state.doc.content.size;
+    let tr = state.tr.insert(insertPos, node);
+    let newState = state.apply(tr);
+    let markdown = pmContext.serializeMarkdown(newState.doc);
+
+    assert.ok(
+      markdown.includes('::card[./Post/1]'),
+      'block card reference serialized correctly',
+    );
+    assert.ok(
+      markdown.includes('Hello world'),
+      'original content preserved',
+    );
+  });
+
   // ── Lazy-loading via globalThis (component pattern) ──
 
   test('globalThis.__loadProseMirror loader works', async function (assert) {