From 1dba7a99b4330a73bfc21ce990fdb10fbe2d1e6f Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Thu, 2 Jul 2026 16:32:14 -0500
Subject: [PATCH 1/2] refactor: resolve markdown pill slots without
 VirtualNetwork (CS-11734)

With the realm serving instance ids in canonical form (CS-11458), card.id /
file.id are canonical, so the base MarkdownTemplate can resolve BFM reference
slots in RRI space (resolveRRIReference) and match its loaded-instance map keys
without a VirtualNetwork. Drops rich-markdown's per-component virtualNetwork
getter and the @cardReferenceVirtualNetwork thread, simplifies baseUrl to the
canonical id as-is (no toURL), and removes the last virtualNetworkFor consumer
in the markdown display path.

Stacked on the CS-11458 serve change; not valid without it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/base/default-templates/markdown.gts | 39 +++++++-------------
 packages/base/rich-markdown.gts              | 32 +++++-----------
 2 files changed, 23 insertions(+), 48 deletions(-)

diff --git a/packages/base/default-templates/markdown.gts b/packages/base/default-templates/markdown.gts
index c7e0bf55bf..c2ca883c55 100644
--- a/packages/base/default-templates/markdown.gts
+++ b/packages/base/default-templates/markdown.gts
@@ -16,8 +16,9 @@ import {
   extractMermaidBlocks,
   processKatexPlaceholders,
   replaceMermaidSvgs,
+  resolveRRIReference,
+  rri,
   trimJsonExtension,
-  type VirtualNetwork,
 } from '@cardstack/runtime-common';
 import {
   hasCodeBlocks,
@@ -79,24 +80,16 @@ interface RenderSlot {
   typeName?: string; // present when state === 'unresolved'
 }
 
-function resolveUrl(
-  raw: string,
-  baseUrl: string | null | undefined,
-  virtualNetwork: VirtualNetwork | undefined,
-): string {
-  // With a VN, resolve through it so prefix-form bases and registered
-  // prefix-form refs round-trip correctly. Without a VN, plain
-  // `new URL(raw, baseUrl)` still handles the common case — URL-form
-  // refs (with or without a base) and relative refs against a URL-form
-  // base. Prefix-form bases need a VN; `new URL()` throws on those and
-  // we fall back to the raw ref.
+function resolveUrl(raw: string, baseUrl: string | null | undefined): string {
+  // Resolve in RRI space (no VirtualNetwork), the same way the reference
+  // extractors resolve the refs behind `linkedCards`/`linkedFiles`. Instance
+  // ids are canonical (the realm serves prefix form for mapped realms, URL for
+  // unmapped), so this produces the same form as a loaded card's `id` — the
+  // slot key (`card.id` / `file.id`) matches without a VirtualNetwork.
   try {
-    if (virtualNetwork) {
-      return trimJsonExtension(
-        virtualNetwork.resolveURL(raw, baseUrl || undefined).href,
-      );
-    }
-    return trimJsonExtension(new URL(raw, baseUrl || undefined).href);
+    return trimJsonExtension(
+      resolveRRIReference(raw, baseUrl ? rri(baseUrl) : undefined),
+    );
   } catch {
     return trimJsonExtension(raw);
   }
@@ -108,7 +101,6 @@ export default class MarkDownTemplate extends GlimmerComponent<{
     linkedCards?: CardDef[] | null;
     linkedFiles?: FileDef[] | null;
     cardReferenceBaseUrl?: string | null;
-    cardReferenceVirtualNetwork?: VirtualNetwork;
   };
 }> {
   @tracked monacoContextInternal: any = undefined;
@@ -208,7 +200,6 @@ export default class MarkDownTemplate extends GlimmerComponent<{
       let linkedCards = this.args.linkedCards;
       let linkedFiles = this.args.linkedFiles;
       let baseUrl = this.args.cardReferenceBaseUrl;
-      let virtualNetwork = this.args.cardReferenceVirtualNetwork;
       let pendingUpdate = false;
       let pendingToken: unknown = undefined;
       // On the very first modifier run the linked instances are likely still
@@ -278,7 +269,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
             );
           }
 
-          let resolvedUrl = resolveUrl(rawUrl, baseUrl, virtualNetwork);
+          let resolvedUrl = resolveUrl(rawUrl, baseUrl);
 
           let instance =
             refType === 'file'
@@ -569,8 +560,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
               />
             {{else}}
               <span
-                class='markdown-bfm-loading markdown-bfm-loading--inline-embed
-                  markdown-bfm-loading--{{slot.format}}'
+                class='markdown-bfm-loading markdown-bfm-loading--inline-embed markdown-bfm-loading--{{slot.format}}'
                 style={{slot.style}}
                 aria-hidden='true'
                 data-test-markdown-bfm-loading-inline
@@ -599,8 +589,7 @@ export default class MarkDownTemplate extends GlimmerComponent<{
               </span>
             {{else}}
               <span
-                class='markdown-bfm-broken markdown-bfm-broken--inline-embed
-                  markdown-bfm-broken--{{slot.format}}'
+                class='markdown-bfm-broken markdown-bfm-broken--inline-embed markdown-bfm-broken--{{slot.format}}'
                 style={{slot.style}}
                 title={{slot.url}}
                 data-test-markdown-bfm-unresolved-inline
diff --git a/packages/base/rich-markdown.gts b/packages/base/rich-markdown.gts
index 83729eb10e..193e6e7999 100644
--- a/packages/base/rich-markdown.gts
+++ b/packages/base/rich-markdown.gts
@@ -18,7 +18,6 @@ import {
   containsMany,
   field,
   linksToMany,
-  virtualNetworkFor,
 } from './card-api';
 import MarkdownTemplate from './default-templates/markdown';
 import CodeMirrorEditor from './codemirror-editor';
@@ -112,18 +111,15 @@ export class RichMarkdownField extends FieldDef {
     get content() {
       return this.args.model?.content ?? null;
     }
-    get virtualNetwork() {
-      return this.args.model ? virtualNetworkFor(this.args.model) : undefined;
-    }
     get baseUrl(): string | null {
       let model = this.args.model;
       let rel = model?.[relativeTo];
       if (!model || !rel) {
         return null;
       }
-      return typeof rel === 'string'
-        ? (virtualNetworkFor(model)?.toURL(rel).href ?? rel)
-        : rel.href;
+      // Instance ids are canonical (prefix form for mapped realms, URL for
+      // unmapped), so the reference base is the id as-is — no VirtualNetwork.
+      return typeof rel === 'string' ? rel : rel.href;
     }
     <template>
       <MarkdownTemplate
@@ -131,7 +127,6 @@ export class RichMarkdownField extends FieldDef {
         @linkedCards={{@model.linkedCards}}
         @linkedFiles={{@model.linkedFiles}}
         @cardReferenceBaseUrl={{this.baseUrl}}
-        @cardReferenceVirtualNetwork={{this.virtualNetwork}}
       />
     </template>
   };
@@ -140,18 +135,15 @@ export class RichMarkdownField extends FieldDef {
     get content() {
       return this.args.model?.content ?? null;
     }
-    get virtualNetwork() {
-      return this.args.model ? virtualNetworkFor(this.args.model) : undefined;
-    }
     get baseUrl(): string | null {
       let model = this.args.model;
       let rel = model?.[relativeTo];
       if (!model || !rel) {
         return null;
       }
-      return typeof rel === 'string'
-        ? (virtualNetworkFor(model)?.toURL(rel).href ?? rel)
-        : rel.href;
+      // Instance ids are canonical (prefix form for mapped realms, URL for
+      // unmapped), so the reference base is the id as-is — no VirtualNetwork.
+      return typeof rel === 'string' ? rel : rel.href;
     }
     <template>
       <MarkdownTemplate
@@ -159,7 +151,6 @@ export class RichMarkdownField extends FieldDef {
         @linkedCards={{@model.linkedCards}}
         @linkedFiles={{@model.linkedFiles}}
         @cardReferenceBaseUrl={{this.baseUrl}}
-        @cardReferenceVirtualNetwork={{this.virtualNetwork}}
       />
     </template>
   };
@@ -186,18 +177,15 @@ export class RichMarkdownField extends FieldDef {
     updateContent = (markdown: string) => {
       this.args.model.content = markdown;
     };
-    get virtualNetwork() {
-      return this.args.model ? virtualNetworkFor(this.args.model) : undefined;
-    }
     get baseUrl(): string | null {
       let model = this.args.model;
       let rel = model?.[relativeTo];
       if (!model || !rel) {
         return null;
       }
-      return typeof rel === 'string'
-        ? (virtualNetworkFor(model)?.toURL(rel).href ?? rel)
-        : rel.href;
+      // Instance ids are canonical (prefix form for mapped realms, URL for
+      // unmapped), so the reference base is the id as-is — no VirtualNetwork.
+      return typeof rel === 'string' ? rel : rel.href;
     }
     get linkedCards(): CardDef[] | null {
       try {
@@ -235,7 +223,6 @@ export class RichMarkdownField extends FieldDef {
               @linkedCards={{@model.linkedCards}}
               @linkedFiles={{@model.linkedFiles}}
               @cardReferenceBaseUrl={{this.baseUrl}}
-              @cardReferenceVirtualNetwork={{this.virtualNetwork}}
             />
           </div>
         {{else}}
@@ -246,7 +233,6 @@ export class RichMarkdownField extends FieldDef {
               @linkedCards={{this.linkedCards}}
               @linkedFiles={{this.linkedFiles}}
               @cardReferenceBaseUrl={{this.baseUrl}}
-              @cardReferenceVirtualNetwork={{this.virtualNetwork}}
               @livePreview={{eq this._mode 'compose'}}
               @getCards={{context.getCards}}
             >

From e05e90906810bb89799f5d22d99473800df96c86 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Fri, 3 Jul 2026 17:39:43 -0500
Subject: [PATCH 2/2] fix: resolve compose-preview card refs without
 VirtualNetwork (CS-11734)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The RichMarkdownField edit view stopped passing @cardReferenceVirtualNetwork
and now hands CodeMirrorEditor a prefix-form RRI base, but CodeMirrorEditor's
resolveUrl still used new URL(raw, baseUrl) without a VN — which throws on a
prefix base, so a relative embed like :card[./Pet/mango] fell through to the
raw ref. The compose-mode getCards in:{id} query then matched nothing and the
live preview showed unresolved widgets (the isolated/display MarkDownTemplate
path already resolved correctly).

Resolve refs in RRI space via resolveRRIReference, matching the MarkDownTemplate
path: a prefix base yields RRI, a URL base yields URL, and either matches the
indexed card since in:{id} expands prefix ids to their URL forms index-side.
Drops the now-unused cardReferenceVirtualNetwork prop.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/base/codemirror-editor.gts | 42 +++++++++++++----------------
 1 file changed, 18 insertions(+), 24 deletions(-)

diff --git a/packages/base/codemirror-editor.gts b/packages/base/codemirror-editor.gts
index 3930196dc2..dfd066084d 100644
--- a/packages/base/codemirror-editor.gts
+++ b/packages/base/codemirror-editor.gts
@@ -11,7 +11,8 @@ import {
   baseRealm,
   trimJsonExtension,
   maybeRelativeReference,
-  type VirtualNetwork,
+  resolveRRIReference,
+  rri,
 } from '@cardstack/runtime-common';
 import {
   type BfmRefRange,
@@ -98,24 +99,17 @@ function isInline(kind: string): boolean {
   return kind === 'inline';
 }
 
-function resolveUrl(
-  raw: string,
-  baseUrl: string | null | undefined,
-  virtualNetwork: VirtualNetwork | undefined,
-): string {
-  // With a VN, resolve through it so prefix-form bases and registered
-  // prefix-form refs round-trip correctly. Without a VN, plain
-  // `new URL(raw, baseUrl)` still handles the common case — URL-form
-  // refs (with or without a base) and relative refs against a URL-form
-  // base. Prefix-form bases need a VN; `new URL()` throws on those and
-  // we fall back to the raw ref.
+function resolveUrl(raw: string, baseUrl: string | null | undefined): string {
+  // Resolve in RRI space (no VirtualNetwork), matching the MarkDownTemplate
+  // display path. Instance ids are canonical (prefix form for mapped realms,
+  // URL for unmapped), so a prefix-form base resolves relative refs to RRI and
+  // a URL-form base to URL — either way the `in:{ id }` reference query below
+  // matches the indexed card (prefix ids are expanded to their URL forms
+  // index-side).
   try {
-    if (virtualNetwork) {
-      return trimJsonExtension(
-        virtualNetwork.resolveURL(raw, baseUrl || undefined).href,
-      );
-    }
-    return trimJsonExtension(new URL(raw, baseUrl || undefined).href);
+    return trimJsonExtension(
+      resolveRRIReference(raw, baseUrl ? rri(baseUrl) : undefined),
+    );
   } catch {
     return trimJsonExtension(raw);
   }
@@ -163,7 +157,6 @@ interface CodeMirrorEditorSignature {
     linkedCards?: CardDef[] | null;
     linkedFiles?: FileDef[] | null;
     cardReferenceBaseUrl?: string | null;
-    cardReferenceVirtualNetwork?: VirtualNetwork;
     /** When false, all syntax markers are visible (source mode). Default true. */
     livePreview?: boolean;
     getCards?: (
@@ -854,11 +847,10 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
 
   private resolvedUrlsForRefType(refType: 'card' | 'file'): string[] {
     let baseUrl = this.args.cardReferenceBaseUrl;
-    let vn = this.args.cardReferenceVirtualNetwork;
     let urls = new Set<string>();
     for (let target of this._widgetTargets) {
       if (target.refType === refType) {
-        urls.add(resolveUrl(target.cardId, baseUrl, vn));
+        urls.add(resolveUrl(target.cardId, baseUrl));
       }
     }
     return [...urls];
@@ -911,7 +903,6 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
   get cardRenderTargets(): CardRenderTarget[] {
     let targets = this._widgetTargets;
     let baseUrl = this.args.cardReferenceBaseUrl;
-    let vn = this.args.cardReferenceVirtualNetwork;
 
     // Resolve cards and files by URL from every available source. linkedCards /
     // linkedFiles work when a store is present; the getCards resources resolve
@@ -936,7 +927,7 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
     addInstances(this.resolvedFiles);
 
     return targets.map((target) => {
-      let resolvedUrl = resolveUrl(target.cardId, baseUrl, vn);
+      let resolvedUrl = resolveUrl(target.cardId, baseUrl);
       return {
         ...target,
         instance: instancesByUrl.get(resolvedUrl) ?? null,
@@ -1123,7 +1114,10 @@ export default class CodeMirrorEditor extends GlimmerComponent<CodeMirrorEditorS
                 {{on 'click' this._toggleEmbedPopover}}
               ><PlusIcon width='16' height='16' /></button>
               {{#if this._embedPopoverOpen}}
-                <div class='toolbar-embed-popover' data-test-toolbar-embed-popover>
+                <div
+                  class='toolbar-embed-popover'
+                  data-test-toolbar-embed-popover
+                >
                   <button
                     type='button'
                     class='toolbar-embed-popover__item'