Remove global prefix mappings (#5081)

Author: backspace

packages/base/card-api.gts

@@ -90,7 +90,6 @@ import {
   runtimeNonQueryDependencyContext,
   runtimeQueryDependencyContext,
   type RuntimeDependencyTrackingContext,
-  resolveCardReference,
   rri,
   type RealmResourceIdentifier,
   type VirtualNetwork,
@@ -471,8 +470,8 @@ export type GetSearchResourceFunc<T extends CardDef | FileDef = CardDef> = (
 export interface CardStore {
   // The VirtualNetwork that owns this store's realm mappings, used for
   // prefix/RRI resolution during (de)serialization. Optional so test doubles
-  // don't need to implement it; resolution sites fall back to the deprecated
-  // module-level resolver when it's absent.
+  // don't need to implement it; resolution sites degrade — URL-form refs
+  // still URL-join, prefix-form refs pass through unchanged.
   virtualNetwork?: VirtualNetwork;
   getCard(url: string): CardDef | undefined;
   getFileMeta(url: string): FileDef | undefined;
@@ -4647,25 +4646,46 @@ function getStore(instance: BaseDef): CardStore {
 
 // The VirtualNetwork associated with an instance's store, for prefix/RRI
 // resolution outside this module. Returns undefined when the store can't
-// supply one, so callers fall back to the deprecated module-level resolver.
+// supply one — callers handle that by degrading to URL math or throwing.
 export function virtualNetworkFor(
   instance: BaseDef,
 ): VirtualNetwork | undefined {
   return getStore(instance).virtualNetwork;
 }
 
 // Resolve a (possibly prefix-form or relative) reference to an absolute URL
-// string through the store's VirtualNetwork when available, falling back to
-// the deprecated module-level resolver when it's absent.
+// string through the store's VirtualNetwork. When the store doesn't carry
+// a VN (test stubs, detached instances), fall back to plain URL math: it
+// covers URL-form refs and relative refs against URL-form bases. Prefix-form
+// refs and refs against prefix-form bases can't be resolved without a VN —
+// `new URL()` throws on those, so we return the raw reference unchanged
+// instead of bubbling the error to callers (e.g. relationship deserialize
+// uses the returned string as a "did this resolve?" signal).
 function resolveRef(
   store: CardStore | undefined,
   reference: string,
   relativeTo: RealmResourceIdentifier | URL | undefined,
 ): string {
   let vn = store?.virtualNetwork;
-  return vn
-    ? vn.resolveURL(reference, relativeTo).href
-    : resolveCardReference(reference, relativeTo);
+  if (vn) {
+    return vn.resolveURL(reference, relativeTo).href;
+  }
+  let base: URL | string | undefined;
+  if (relativeTo instanceof URL) {
+    base = relativeTo;
+  } else if (typeof relativeTo === 'string') {
+    if (
+      relativeTo.startsWith('http://') ||
+      relativeTo.startsWith('https://')
+    ) {
+      base = relativeTo;
+    }
+  }
+  try {
+    return new URL(reference, base).href;
+  } catch {
+    return reference;
+  }
 }
 
 function myLoader(): Loader {
@@ -4747,7 +4767,13 @@ class FallbackCardStore implements CardStore {
     opts?: { dependencyTrackingContext?: RuntimeDependencyTrackingContext },
   ) {
     trackRuntimeInstanceDependency(url, opts?.dependencyTrackingContext);
-    let promise = loadCardDocument(fetch, url, this.virtualNetwork);
+    let vn = this.virtualNetwork;
+    if (!vn) {
+      throw new Error(
+        `CardStore.loadCardDocument requires a Loader with a VirtualNetwork`,
+      );
+    }
+    let promise = loadCardDocument(fetch, url, vn);
     this.trackLoad(promise);
     return await promise;
   }
@@ -4757,7 +4783,13 @@ class FallbackCardStore implements CardStore {
     opts?: { dependencyTrackingContext?: RuntimeDependencyTrackingContext },
   ) {
     trackRuntimeFileDependency(url, opts?.dependencyTrackingContext);
-    let promise = loadFileMetaDocument(fetch, url, this.virtualNetwork);
+    let vn = this.virtualNetwork;
+    if (!vn) {
+      throw new Error(
+        `CardStore.loadFileMetaDocument requires a Loader with a VirtualNetwork`,
+      );
+    }
+    let promise = loadFileMetaDocument(fetch, url, vn);
     this.trackLoad(promise);
     return await promise;
   }

packages/base/card-serialization.ts

@@ -30,8 +30,6 @@ import {
   getSerializer,
   humanReadable,
   identifyCard,
-  isRegisteredPrefix,
-  cardIdToURL,
   isSingleCardDocument,
   isSingleFileMetaDocument,
   loadCardDef,
@@ -75,8 +73,9 @@ export interface SerializeOpts {
   maybeRelativeReference?: (possibleReference: string) => string;
   overrides?: Map<string, typeof BaseDef>;
   // The VirtualNetwork to consult for prefix/RRI resolution during
-  // serialization. Optional; sites fall back to the deprecated module-level
-  // resolver when absent.
+  // serialization. Optional: when absent, the `maybeRelativeReference`
+  // closures degrade — prefix-form refs pass through unchanged and only
+  // URL-form bases support URL math.
   virtualNetwork?: VirtualNetwork;
 }
 
@@ -227,23 +226,36 @@ export function serializeCard(
     ...opts,
     ...{
       maybeRelativeReference(possibleReference: string) {
+        let vn = opts?.virtualNetwork;
         // Registered prefix refs (e.g. @cardstack/catalog/foo) are already
-        // in their canonical portable form — return as-is
-        if (
-          opts?.virtualNetwork
-            ? opts.virtualNetwork.isRegisteredPrefix(possibleReference)
-            : isRegisteredPrefix(possibleReference)
-        ) {
+        // in their canonical portable form — return as-is. Without a VN
+        // we can't know which prefixes are registered, so the most we can
+        // do for prefix-form refs is pass them through unchanged.
+        if (vn ? vn.isRegisteredPrefix(possibleReference) : false) {
           return possibleReference;
         }
-        let modelRelativeToForURL =
-          typeof modelRelativeTo === 'string'
-            ? opts?.virtualNetwork
-              ? opts.virtualNetwork.toURL(modelRelativeTo)
-              : cardIdToURL(modelRelativeTo)
-            : modelRelativeTo;
+        let modelRelativeToForURL: URL | undefined;
+        if (typeof modelRelativeTo === 'string') {
+          if (vn) {
+            modelRelativeToForURL = vn.toURL(modelRelativeTo);
+          } else if (
+            modelRelativeTo.startsWith('http://') ||
+            modelRelativeTo.startsWith('https://')
+          ) {
+            modelRelativeToForURL = new URL(modelRelativeTo);
+          }
+        } else {
+          modelRelativeToForURL = modelRelativeTo;
+        }
         let url = maybeURL(possibleReference, modelRelativeToForURL);
         if (!url) {
+          if (!vn) {
+            // Without a VN we can't resolve a prefix-form reference. Pass
+            // through unchanged so callers that don't need relativization
+            // (e.g. test adapters serializing same-realm cards by URL)
+            // don't blow up on portable refs.
+            return possibleReference;
+          }
           throw new Error(
             `could not determine url from '${possibleReference}' relative to ${modelRelativeTo}`,
           );
@@ -335,23 +347,33 @@ export function serializeFileDef(
       ...opts,
       ...{
         maybeRelativeReference(possibleReference: string) {
-          // Registered prefix refs (e.g. @cardstack/catalog/foo) are already
-          // in their canonical portable form — return as-is
-          if (
-            opts?.virtualNetwork
-              ? opts.virtualNetwork.isRegisteredPrefix(possibleReference)
-              : isRegisteredPrefix(possibleReference)
-          ) {
+          let vn = opts?.virtualNetwork;
+          // Registered prefix refs (e.g. @cardstack/catalog/foo) are
+          // already in their canonical portable form — return as-is.
+          // Without a VN we can't know which prefixes are registered,
+          // so the most we can do for prefix-form refs is pass them
+          // through unchanged.
+          if (vn ? vn.isRegisteredPrefix(possibleReference) : false) {
             return possibleReference;
           }
-          let modelRelativeToForURL =
-            typeof modelRelativeTo === 'string'
-              ? opts?.virtualNetwork
-                ? opts.virtualNetwork.toURL(modelRelativeTo)
-                : cardIdToURL(modelRelativeTo)
-              : modelRelativeTo;
+          let modelRelativeToForURL: URL | undefined;
+          if (typeof modelRelativeTo === 'string') {
+            if (vn) {
+              modelRelativeToForURL = vn.toURL(modelRelativeTo);
+            } else if (
+              modelRelativeTo.startsWith('http://') ||
+              modelRelativeTo.startsWith('https://')
+            ) {
+              modelRelativeToForURL = new URL(modelRelativeTo);
+            }
+          } else {
+            modelRelativeToForURL = modelRelativeTo;
+          }
           let url = maybeURL(possibleReference, modelRelativeToForURL);
           if (!url) {
+            if (!vn) {
+              return possibleReference;
+            }
             throw new Error(
               `could not determine url from '${possibleReference}' relative to ${modelRelativeTo}`,
             );

packages/base/cards-grid.gts

@@ -16,7 +16,6 @@ import AllFilesIcon from '@cardstack/boxel-icons/files';
 import FileIcon from '@cardstack/boxel-icons/file';
 
 import {
-  cardIdToURL,
   chooseCard,
   specRef,
   baseRealm,
@@ -308,13 +307,15 @@ class Isolated extends Component<typeof CardsGrid> {
     }
 
     if (spec && isCardInstance<Spec>(spec)) {
-      await this.args.createCard?.(
-        spec.ref,
-        virtualNetworkFor(spec)?.toURL(spec.id!) ?? cardIdToURL(spec.id!),
-        {
-          realmURL: this.args.model[realmURL],
-        },
-      );
+      let vn = virtualNetworkFor(spec);
+      if (!vn) {
+        throw new Error(
+          `cards-grid createCard requires a VirtualNetwork on the spec's store`,
+        );
+      }
+      await this.args.createCard?.(spec.ref, vn.toURL(spec.id!), {
+        realmURL: this.args.model[realmURL],
+      });
     } else if (activeFilterRef) {
       // No spec exists for the active type filter — create an instance of
       // the type directly. `activeFilterRef` is an absolute CodeRef sourced

packages/base/codemirror-editor.gts

@@ -8,7 +8,6 @@ import { scheduleOnce } from '@ember/runloop';
 import { eq } from '@cardstack/boxel-ui/helpers';
 
 import {
-  resolveCardReference,
   trimJsonExtension,
   maybeRelativeReference,
   type VirtualNetwork,
@@ -90,14 +89,21 @@ function isInline(kind: string): boolean {
 function resolveUrl(
   raw: string,
   baseUrl: string | null | undefined,
-  virtualNetwork?: VirtualNetwork,
+  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.
   try {
-    return trimJsonExtension(
-      virtualNetwork
-        ? virtualNetwork.resolveURL(raw, baseUrl || undefined).href
-        : resolveCardReference(raw, baseUrl || undefined),
-    );
+    if (virtualNetwork) {
+      return trimJsonExtension(
+        virtualNetwork.resolveURL(raw, baseUrl || undefined).href,
+      );
+    }
+    return trimJsonExtension(new URL(raw, baseUrl || undefined).href);
   } catch {
     return trimJsonExtension(raw);
   }

packages/base/default-templates/markdown.gts

@@ -15,7 +15,6 @@ import {
   extractMermaidBlocks,
   processKatexPlaceholders,
   replaceMermaidSvgs,
-  resolveCardReference,
   trimJsonExtension,
   type VirtualNetwork,
 } from '@cardstack/runtime-common';
@@ -68,14 +67,21 @@ interface RenderSlot {
 function resolveUrl(
   raw: string,
   baseUrl: string | null | undefined,
-  virtualNetwork?: VirtualNetwork,
+  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.
   try {
-    return trimJsonExtension(
-      virtualNetwork
-        ? virtualNetwork.resolveURL(raw, baseUrl || undefined).href
-        : resolveCardReference(raw, baseUrl || undefined),
-    );
+    if (virtualNetwork) {
+      return trimJsonExtension(
+        virtualNetwork.resolveURL(raw, baseUrl || undefined).href,
+      );
+    }
+    return trimJsonExtension(new URL(raw, baseUrl || undefined).href);
   } catch {
     return trimJsonExtension(raw);
   }

packages/base/markdown-file-def.gts

@@ -1,6 +1,7 @@
 import {
   byteStreamToUint8Array,
   extractCardReferenceUrls,
+  VirtualNetwork,
 } from '@cardstack/runtime-common';
 import MarkdownIcon from '@cardstack/boxel-icons/align-box-left-middle';
 import {
@@ -454,7 +455,7 @@ export class MarkdownDef extends FileDef {
       return extractCardReferenceUrls(
         this.content,
         this.id ?? '',
-        virtualNetworkFor(this),
+        virtualNetworkFor(this) ?? new VirtualNetwork(),
       );
     },
   });
@@ -520,7 +521,11 @@ export class MarkdownDef extends FileDef {
       title: extractTitle(markdown, fallbackTitle),
       excerpt: extractExcerpt(markdown),
       content: markdown,
-      cardReferenceUrls: extractCardReferenceUrls(markdown, url),
+      cardReferenceUrls: extractCardReferenceUrls(
+        markdown,
+        url,
+        new VirtualNetwork(),
+      ),
     };
   }
 }

packages/base/menu-items.ts

@@ -1,4 +1,5 @@
 import type { BaseDef, CardCrudFunctions, CardDef } from './card-api';
+import { virtualNetworkFor } from './card-api';
 import {
   copyCardURLToClipboard,
   type MenuItemOptions,
@@ -76,6 +77,7 @@ export function getDefaultCardMenuItems(
 ): MenuItemOptions[] {
   let cardId = card.id as unknown as string;
   let menuItems: MenuItemOptions[] = [];
+  let vnForCard = virtualNetworkFor(card);
   if (
     ['interact', 'code-mode-preview', 'code-mode-playground'].includes(
       params.menuContext,
@@ -130,7 +132,8 @@ export function getDefaultCardMenuItems(
       );
     }
     if (
-      !isRealmIndexCard(card) && // workspace index card cannot be deleted
+      vnForCard &&
+      !isRealmIndexCard(card, vnForCard) && // workspace index card cannot be deleted
       cardId &&
       params.canEdit
     ) {
@@ -212,11 +215,15 @@ export function getDefaultCardMenuItems(
       disabled: !cardId,
     });
     menuItems = [...menuItems, ...getSampleDataMenuItems(card, params)];
-    if (!isRealmIndexCard(card)) {
+    if (vnForCard && !isRealmIndexCard(card, vnForCard)) {
       menuItems.push({
         label: `Create Listing`,
         action: async () => {
-          const codeRef = resolveAdoptsFrom(card);
+          let vn = vnForCard;
+          if (!vn) {
+            throw new Error('No VirtualNetwork available to resolve codeRef');
+          }
+          const codeRef = resolveAdoptsFrom(card, vn);
           if (!codeRef) {
             throw new Error('Unable to resolve codeRef from card');
           }