From 95bd7af844d960d466d85b9b6bf3bed1b6372faf Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Fri, 19 Jun 2026 09:35:21 -0400
Subject: [PATCH 1/3] Migrate experiments-realm card source to the v2 search
 surface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move the first-party realm card source off the deprecated
`@context.prerenderedCardSearchComponent` and onto the v2
`@context.searchResultsComponent` (`<SearchResults>`) surface, via the
`@context` search codemod plus hand-fixes for the shapes it cannot
transform mechanically.

Only experiments-realm carries prerendered-card-search usages: base
declares the (deprecated) `@context` member itself, and catalog /
skills-realm have none.

- components/grid.gts — codemod-migrated: the query is adapted through
  `searchEntryWireQueryFromQuery`, `<:response>` becomes
  `{{#each results.entries}}`, and rows are addressed by `id`.
- components/card-list.gts — its loop yields each row to a `:meta` block,
  so it has no direct `{{#each}}` the codemod can reshape. The block now
  yields a `RenderableSearchEntryLike`; the `embedded` format is bound
  through the query's `htmlQuery` field.
- app-card.gts — the result list is handed to the local `TableView` /
  `CardsGrid` components, so it is not a direct `{{#each}}` either. Those
  components now take `RenderableSearchEntryLike[]` and address rows by
  `id`.
- blog-app.gts — its `CardList` `:meta` consumer reads the yielded row's
  `id`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/experiments-realm/app-card.gts       | 55 +++++++++++--------
 packages/experiments-realm/blog-app.gts       | 10 ++--
 .../components/card-list.gts                  | 52 +++++++++++-------
 .../experiments-realm/components/grid.gts     | 37 +++++++------
 4 files changed, 89 insertions(+), 65 deletions(-)

diff --git a/packages/experiments-realm/app-card.gts b/packages/experiments-realm/app-card.gts
index bacfa80556..ffa91162dc 100644
--- a/packages/experiments-realm/app-card.gts
+++ b/packages/experiments-realm/app-card.gts
@@ -20,7 +20,9 @@ import { and, bool, cn } from '@cardstack/boxel-ui/helpers';
 import {
   type Query,
   baseRealm,
-  type PrerenderedCardLike,
+  type RenderableSearchEntryLike,
+  type SearchEntryWireQuery,
+  searchEntryWireQueryFromQuery,
 } from '@cardstack/runtime-common';
 import { hash } from '@ember/helper';
 import { on } from '@ember/modifier';
@@ -64,7 +66,7 @@ export class Tab extends FieldDef {
 }
 
 class TableView extends GlimmerComponent<{
-  Args: { cards: PrerenderedCardLike[]; context?: CardContext };
+  Args: { cards: RenderableSearchEntryLike[]; context?: CardContext };
 }> {
   <template>
     {{#if this.isLoaded}}
@@ -127,7 +129,7 @@ class TableView extends GlimmerComponent<{
   // a possibility it might be initialized as undefined
   @tracked private cardCollection = this.args.context?.getCardCollection(
     this,
-    () => this.args.cards.map((c) => c.url),
+    () => this.args.cards.map((c) => c.id),
   );
 
   private get isLoaded() {
@@ -170,22 +172,18 @@ class DefaultTabTemplate extends GlimmerComponent<DefaultTabSignature> {
   <template>
     <div class='app-card-content'>
       {{#if this.activeTabRef}}
-        {{#if this.query}}
-          <@context.prerenderedCardSearchComponent
-            @query={{this.query}}
-            @format='fitted'
-            @realms={{@realms}}
-            @isLive={{true}}
+        {{#if this.searchResultsQuery}}
+          <@context.searchResultsComponent
+            @query={{this.searchResultsQuery}}
+            as |results|
           >
-            <:loading>Loading...</:loading>
-            <:response as |cards|>
-              {{#if @activeTab.isTable}}
-                <TableView @cards={{cards}} @context={{@context}} />
-              {{else}}
-                <CardsGrid @cards={{cards}} @context={{@context}} />
-              {{/if}}
-            </:response>
-          </@context.prerenderedCardSearchComponent>
+            {{#if results.isLoading}}Loading...{{/if}}
+            {{#if @activeTab.isTable}}
+              <TableView @cards={{results.entries}} @context={{@context}} />
+            {{else}}
+              <CardsGrid @cards={{results.entries}} @context={{@context}} />
+            {{/if}}
+          </@context.searchResultsComponent>
         {{/if}}
       {{else}}
         <p>No cards available</p>
@@ -330,6 +328,19 @@ class DefaultTabTemplate extends GlimmerComponent<DefaultTabSignature> {
     } as Query;
   }
 
+  // The v2 `search-entry`-rooted query, adapted from the v1 `query` above.
+  // `fitted` is the default rendering, so no `htmlQuery` binding is needed.
+  // Undefined (no active tab ref) leaves the search component idle.
+  get searchResultsQuery(): SearchEntryWireQuery | undefined {
+    if (!this.query) {
+      return undefined;
+    }
+    return {
+      ...searchEntryWireQueryFromQuery(this.query),
+      realms: this.args.realms,
+    };
+  }
+
   @action createNew(value: unknown) {
     let cardDoc = isSingleCardDocument(value) ? value : undefined;
     this.createCard.perform(cardDoc);
@@ -492,7 +503,7 @@ export class AppCard extends CardDef {
 
 export class CardsGrid extends GlimmerComponent<{
   Args: {
-    cards: PrerenderedCardLike[];
+    cards: RenderableSearchEntryLike[];
     context?: CardContext;
     isListFormat?: boolean;
   };
@@ -505,14 +516,14 @@ export class CardsGrid extends GlimmerComponent<{
           <li
             class='cards-grid-item'
             {{@context.cardComponentModifier
-              cardId=card.url
+              cardId=card.id
               format='data'
               fieldType=undefined
               fieldName=undefined
             }}
-            data-test-cards-grid-item={{removeFileExtension card.url}}
+            data-test-cards-grid-item={{removeFileExtension card.id}}
             {{! In order to support scrolling cards into view we use a selector that is not pruned out in production builds }}
-            data-cards-grid-item={{removeFileExtension card.url}}
+            data-cards-grid-item={{removeFileExtension card.id}}
           >
             <CardContainer class='card' @displayBoundaries={{true}}>
               {{card.component}}
diff --git a/packages/experiments-realm/blog-app.gts b/packages/experiments-realm/blog-app.gts
index d8f43cda7e..623687c77c 100644
--- a/packages/experiments-realm/blog-app.gts
+++ b/packages/experiments-realm/blog-app.gts
@@ -234,7 +234,7 @@ class BlogAppTemplate extends Component<typeof BlogApp> {
               <:meta as |card|>
                 {{#if this.showAdminData}}
                   <BlogAdminData
-                    @cardId={{card.url}}
+                    @cardId={{card.id}}
                     @context={{this.context}}
                   />
                 {{/if}}
@@ -307,10 +307,10 @@ class BlogAppTemplate extends Component<typeof BlogApp> {
       displayName === 'Blog Posts'
         ? 'blog-posts-grid'
         : displayName === 'Author Bios'
-        ? 'author-bios-grid'
-        : displayName === 'Categories'
-        ? 'categories-grid'
-        : '';
+          ? 'author-bios-grid'
+          : displayName === 'Categories'
+            ? 'categories-grid'
+            : '';
     return gridName ? `bordered-items ${gridName}` : '';
   }
 
diff --git a/packages/experiments-realm/components/card-list.gts b/packages/experiments-realm/components/card-list.gts
index 53d210d2ac..8608c52560 100644
--- a/packages/experiments-realm/components/card-list.gts
+++ b/packages/experiments-realm/components/card-list.gts
@@ -4,7 +4,9 @@ import { type CardContext } from 'https://cardstack.com/base/card-api';
 
 import {
   type Query,
-  type PrerenderedCardLike,
+  type RenderableSearchEntryLike,
+  type SearchEntryWireQuery,
+  searchEntryWireQueryFromQuery,
 } from '@cardstack/runtime-common';
 
 interface CardListSignature {
@@ -14,36 +16,44 @@ interface CardListSignature {
     context?: CardContext;
   };
   Blocks: {
-    meta: [card: PrerenderedCardLike];
+    meta: [card: RenderableSearchEntryLike];
   };
   Element: HTMLElement;
 }
 export class CardList extends GlimmerComponent<CardListSignature> {
+  // The v2 `search-entry`-rooted query, adapted from the incoming v1 `Query`.
+  // `embedded` is bound through the query's `htmlQuery` field (the v2 way to
+  // select a prerendered format); a bare `eq.format` would be read as an
+  // `item.` field path and rejected.
+  get searchResultsQuery(): SearchEntryWireQuery {
+    let query = searchEntryWireQueryFromQuery(this.args.query);
+    return {
+      ...query,
+      realms: this.args.realms,
+      filter: {
+        ...query.filter,
+        eq: { ...query.filter?.eq, htmlQuery: { eq: { format: 'embedded' } } },
+      },
+    };
+  }
   <template>
     <ul class='card-list' ...attributes>
       {{#let
-        (component @context.prerenderedCardSearchComponent)
+        (component @context.searchResultsComponent)
         as |PrerenderedCardSearch|
       }}
-        <PrerenderedCardSearch
-          @query={{@query}}
-          @format='embedded'
-          @realms={{@realms}}
-          @isLive={{true}}
-        >
-          <:loading>
+        <PrerenderedCardSearch @query={{this.searchResultsQuery}} as |results|>
+          {{#if results.isLoading}}
             Loading...
-          </:loading>
-          <:response as |cards|>
-            {{#each cards key='url' as |card|}}
-              <li class='card-list-item'>
-                <card.component class='card' />
-                {{#if (has-block 'meta')}}
-                  {{yield card to='meta'}}
-                {{/if}}
-              </li>
-            {{/each}}
-          </:response>
+          {{/if}}
+          {{#each results.entries key='id' as |card|}}
+            <li class='card-list-item'>
+              <card.component class='card' />
+              {{#if (has-block 'meta')}}
+                {{yield card to='meta'}}
+              {{/if}}
+            </li>
+          {{/each}}
         </PrerenderedCardSearch>
       {{/let}}
     </ul>
diff --git a/packages/experiments-realm/components/grid.gts b/packages/experiments-realm/components/grid.gts
index d8b56055b7..1ed2e79bd7 100644
--- a/packages/experiments-realm/components/grid.gts
+++ b/packages/experiments-realm/components/grid.gts
@@ -2,7 +2,11 @@ import GlimmerComponent from '@glimmer/component';
 
 import { type CardContext } from 'https://cardstack.com/base/card-api';
 
-import { type Query } from '@cardstack/runtime-common';
+import {
+  type Query,
+  searchEntryWireQueryFromQuery,
+  type SearchEntryWireQuery,
+} from '@cardstack/runtime-common';
 
 interface CardsGridSignature {
   Args: {
@@ -14,6 +18,12 @@ interface CardsGridSignature {
   Element: HTMLElement;
 }
 export class CardsGrid extends GlimmerComponent<CardsGridSignature> {
+  get searchResultsQuery(): SearchEntryWireQuery {
+    return {
+      ...searchEntryWireQueryFromQuery(this.args.query),
+      realms: this.args.realms,
+    };
+  }
   <template>
     <ul
       class='cards {{@selectedView}}-view'
@@ -21,25 +31,18 @@ export class CardsGrid extends GlimmerComponent<CardsGridSignature> {
       ...attributes
     >
       {{#let
-        (component @context.prerenderedCardSearchComponent)
+        (component @context.searchResultsComponent)
         as |PrerenderedCardSearch|
       }}
-        <PrerenderedCardSearch
-          @query={{@query}}
-          @format='fitted'
-          @realms={{@realms}}
-          @isLive={{true}}
-        >
-          <:loading>
+        <PrerenderedCardSearch @query={{this.searchResultsQuery}} as |results|>
+          {{#if results.isLoading}}
             Loading...
-          </:loading>
-          <:response as |cards|>
-            {{#each cards key='url' as |card|}}
-              <li class='{{@selectedView}}-view-container'>
-                <card.component class='card' />
-              </li>
-            {{/each}}
-          </:response>
+          {{/if}}
+          {{#each results.entries key='id' as |card|}}
+            <li class='{{@selectedView}}-view-container'>
+              <card.component class='card' />
+            </li>
+          {{/each}}
         </PrerenderedCardSearch>
       {{/let}}
     </ul>

From ef40954ddfc3224de9114d39ab5cbebc6c616c09 Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Fri, 19 Jun 2026 10:04:03 -0400
Subject: [PATCH 2/3] experiments-realm app-card: render results only once
 entries are present

Gate the table/grid on results.entries.length so the loading state and an
empty children render (CardsGrid's "No cards available") aren't shown at the
same time during the initial load; show the loading affordance only while the
first results are still empty. Stale entries continue to render during a live
re-fetch.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/experiments-realm/app-card.gts | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/packages/experiments-realm/app-card.gts b/packages/experiments-realm/app-card.gts
index ffa91162dc..db572e0fae 100644
--- a/packages/experiments-realm/app-card.gts
+++ b/packages/experiments-realm/app-card.gts
@@ -177,11 +177,14 @@ class DefaultTabTemplate extends GlimmerComponent<DefaultTabSignature> {
             @query={{this.searchResultsQuery}}
             as |results|
           >
-            {{#if results.isLoading}}Loading...{{/if}}
-            {{#if @activeTab.isTable}}
-              <TableView @cards={{results.entries}} @context={{@context}} />
-            {{else}}
-              <CardsGrid @cards={{results.entries}} @context={{@context}} />
+            {{#if results.entries.length}}
+              {{#if @activeTab.isTable}}
+                <TableView @cards={{results.entries}} @context={{@context}} />
+              {{else}}
+                <CardsGrid @cards={{results.entries}} @context={{@context}} />
+              {{/if}}
+            {{else if results.isLoading}}
+              Loading...
             {{/if}}
           </@context.searchResultsComponent>
         {{/if}}

From b3fe9872b691850971f5e57d274a78fbd2aab8e9 Mon Sep 17 00:00:00 2001
From: Hassan Abdel-Rahman <hassan.abdelrahman@gmail.com>
Date: Fri, 19 Jun 2026 10:05:17 -0400
Subject: [PATCH 3/3] experiments-realm: name the v2 search binding
 SearchResults

Rename the local component alias from PrerenderedCardSearch to SearchResults so
it reflects the v2 `@context.searchResultsComponent` surface it now points at,
rather than the deprecated v1 name.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/experiments-realm/components/card-list.gts | 6 +++---
 packages/experiments-realm/components/grid.gts      | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/experiments-realm/components/card-list.gts b/packages/experiments-realm/components/card-list.gts
index 8608c52560..3a513d2772 100644
--- a/packages/experiments-realm/components/card-list.gts
+++ b/packages/experiments-realm/components/card-list.gts
@@ -40,9 +40,9 @@ export class CardList extends GlimmerComponent<CardListSignature> {
     <ul class='card-list' ...attributes>
       {{#let
         (component @context.searchResultsComponent)
-        as |PrerenderedCardSearch|
+        as |SearchResults|
       }}
-        <PrerenderedCardSearch @query={{this.searchResultsQuery}} as |results|>
+        <SearchResults @query={{this.searchResultsQuery}} as |results|>
           {{#if results.isLoading}}
             Loading...
           {{/if}}
@@ -54,7 +54,7 @@ export class CardList extends GlimmerComponent<CardListSignature> {
               {{/if}}
             </li>
           {{/each}}
-        </PrerenderedCardSearch>
+        </SearchResults>
       {{/let}}
     </ul>
     <style scoped>
diff --git a/packages/experiments-realm/components/grid.gts b/packages/experiments-realm/components/grid.gts
index 1ed2e79bd7..5ea1fe27e3 100644
--- a/packages/experiments-realm/components/grid.gts
+++ b/packages/experiments-realm/components/grid.gts
@@ -32,9 +32,9 @@ export class CardsGrid extends GlimmerComponent<CardsGridSignature> {
     >
       {{#let
         (component @context.searchResultsComponent)
-        as |PrerenderedCardSearch|
+        as |SearchResults|
       }}
-        <PrerenderedCardSearch @query={{this.searchResultsQuery}} as |results|>
+        <SearchResults @query={{this.searchResultsQuery}} as |results|>
           {{#if results.isLoading}}
             Loading...
           {{/if}}
@@ -43,7 +43,7 @@ export class CardsGrid extends GlimmerComponent<CardsGridSignature> {
               <card.component class='card' />
             </li>
           {{/each}}
-        </PrerenderedCardSearch>
+        </SearchResults>
       {{/let}}
     </ul>
     <style scoped>