Realm-index opt-in for prerendered isolated HTML#4769
Open
habdelra wants to merge 6 commits into
Open
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f542487809
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
4 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a realm-level opt-in to keep (or skip) prerendered isolated HTML for the default CardsGrid realm-index card, allowing the host to substitute boilerplate and avoid expensive grid fan-out renders when not needed.
Changes:
- Introduces
includePrerenderedDefaultRealmIndexon RealmConfig/RealmInfo and parses it from both disk and index overlays. - Adds host-side detection of the default CardsGrid index isolated render and passes a
useRealmIndexBoilerplateflag through the render route model. - Short-circuits prerendering to return a new
REALM_INDEX_BOILERPLATE_HTMLconstant when the flag is set.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/runtime-common/realm.ts | Adds/propagates the opt-in field into RealmInfo and realm config parsing to inform host behavior. |
| packages/host/app/utils/realm-index-boilerplate.ts | Introduces the static boilerplate HTML returned when isolated render is skipped. |
| packages/host/app/routes/render/html.ts | Detects the default CardsGrid realm index isolated render and sets useRealmIndexBoilerplate in the route model. |
| packages/host/app/components/card-prerender.gts | Returns boilerplate HTML instead of running Glimmer when useRealmIndexBoilerplate is set. |
| packages/base/realm-config.gts | Adds the opt-in field to the RealmConfig card schema. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Preview deploymentsHost Test Results 1 files ±0 1 suites ±0 2h 6m 25s ⏱️ + 2m 46s Results for commit fedf974. ± Comparison against earlier commit 86eaecf. For more details on these errors, see this check. Realm Server Test Results 1 files ±0 1 suites ±0 12m 46s ⏱️ -9s Results for commit fedf974. ± Comparison against earlier commit 86eaecf. |
Adds an `includePrerenderedDefaultRealmIndex` field to RealmConfig that controls whether the host's render route produces a full prerendered isolated HTML for the realm's default CardsGrid index card. When the field is unset (the default), the host substitutes a small boilerplate placeholder for the isolated render of that specific card and skips the (expensive) grid fan-out render of every card in the realm. Why this matters: the CardsGrid isolated render is the second-largest single cost in a from-scratch reindex — its isolated template renders a fitted view of every card in the realm, so cost scales linearly with realm size (17.3s on a 100-card realm, proportionally bigger on 500+ cards). Today nothing in the search-result hot path actually consumes the realm-index isolated HTML; the only production consumers are the published-realm SSR injection (`retrieveIsolatedHTML` in server.ts) and the `lastKnownGoodHtml` error fallback. Unpublished realms never need it. The field stays as a future-lever for now. No production realm sets it. The published-realm path that genuinely needs the full render is addressed in a follow-on PR that writes the field on the published realm snapshot at publish time. Detection lives in `packages/host/app/routes/render/html.ts`: when `format === 'isolated'` AND the card is the realm's index AND the type chain begins with base CardsGrid AND `RealmInfo.includePrerenderedDefaultRealmIndex !== true`, the route's model carries a `useRealmIndexBoilerplate` flag. The orchestrator in `card-prerender.gts` honours the flag by returning the boilerplate constant directly, bypassing Glimmer rendering entirely. The boilerplate matches the `<section data-prerender>...</section>` shape that real renders capture, so downstream consumers (the SSR injection slot, error-page fallback, anything reading `isolated_html` directly) see structurally consistent content. The placeholder text calls out that the lever is configurable in realm.json so an operator who lands on it knows where to flip it. The new `RealmInfo.includePrerenderedDefaultRealmIndex` is optional in the type so the dozens of `RealmInfo` fixtures across the host / runtime-common test suites don't all have to update. `parseRealmInfo` reads the field from both the disk-overlay and indexed-overlay paths that already exist for `name` / `backgroundURL` / `iconURL`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Covers the three meaningful branches of the host's render-route detection: 1. Default CardsGrid realm-index card with no opt-in → isolated HTML row equals the boilerplate constant; embedded / fitted HTML maps still render normally. 2. Default CardsGrid realm-index card with the opt-in set via realm.json → isolated HTML is fully rendered (not the boilerplate). Exercises the future-lever code path even though no production realm uses it today. 3. Realm whose index.json is a custom (non-CardsGrid) card → isolated HTML renders normally regardless of the opt-in. Confirms the detection only triggers for the default-grid case. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… cast Two Copilot review findings on the realm-index detection: - `BASE_CARD_INTERNAL_KEY` guard in `routes/render/html.ts#isDefaultRealmCardsGridIndex` was unreachable. After the previous check confirms `topKey === CARDS_GRID_INTERNAL_KEY`, asking again whether it equals the (different) base-card key can never fire. Removed the guard and the unused constant. - The inline cast on `routeInfo.attributes` in `card-prerender.gts` weakened type safety. Import the html sub-route's `Model` type directly and cast through it instead, so the route model and the consumer can't silently drift apart. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
habdelra
force-pushed
the
indexer-perf/realm-index-opt-in
branch
from
7cde395 to
5a2fa61
Compare
Contributor
Author
|
[Claude Code] Rebased this PR onto This PR is now structurally simple — it's purely the realm-index opt-in lever. Files changed: No |
5 tasks
testRealmInfo (both runtime-common/helpers/const.ts for host tests and realm-server/tests/helpers/index.ts for realm-server tests), plus every inline realmInfo fixture in realm-indexing-test.gts and realm-test.gts, now carries includePrerenderedDefaultRealmIndex: false. The realm-config card's BooleanField defaults to false, so that's the value the /_info handler emits when the opt-in is unset — and assertion targets need to match that. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
A test realm with no realm.json (RealmConfig card) and no .realm.json sidecar leaves includePrerenderedDefaultRealmIndex at the initial null value parseRealmInfo seeds — none of the three overlays (sidecar, on-disk card, indexed card) fires when the underlying file is absent. The earlier fixture-update commit read the BooleanField emptyValue and used false, but that value is only observable when an actual RealmConfig card is indexed. For the integration tests' setupIntegrationTestRealm contents that omit realm.json, the response carries null, so realmInfo assertions need to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The realm-server test realm (tests/cards/) ships with a realm.json RealmConfig card on disk that gets indexed before tests run, so the indexed-card overlay in parseRealmInfo emits the BooleanField's emptyValue (false) for includePrerenderedDefaultRealmIndex. The host integration tests in runtime-common/helpers/const.ts stay at null because those realms have neither a sidecar nor a RealmConfig card, so none of the parseRealmInfo overlays touch the seeded null. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a realm-level opt-in for keeping the prerendered isolated HTML of the default CardsGrid realm-index card. When the opt-in is not set, the host substitutes a small boilerplate placeholder for the isolated render of that specific card and skips the (expensive) grid fan-out render of every card in the realm. Stands alone — strictly does less work, no parallelism.
includePrerenderedDefaultRealmIndexon the RealmConfig CardDef and onRealmInfo.parseRealmInfoextracts the field from both the disk-overlay and indexed-overlay paths that already populatename/backgroundURL/iconURL.packages/host/app/routes/render/html.tsflagsuseRealmIndexBoilerplateon its model when:format === 'isolated',ancestor_level === 0isRealmIndexCardId)CardsGridref (viainternalKeyForcomparison)RealmInfo.includePrerenderedDefaultRealmIndex !== truepackages/host/app/components/card-prerender.gtsshort-circuits the Glimmer render when the flag is set and returns a static boilerplate constant instead.REALM_INDEX_BOILERPLATE_HTMLinpackages/host/app/utils/realm-index-boilerplate.ts. Wrapped in a<section data-prerender>...</section>so it's structurally consistent with whatwithTimeoutcaptures from a real render. The placeholder text names the configuration knob so anyone who lands on it knows where to flip it.Why this matters
The CardsGrid isolated render is a significant single cost in a from-scratch reindex on
/prudent-octopus(about 10s of the 190s baseline) and scales linearly with realm size — its isolated template renders a fitted view of every card in the realm. Today nothing in the search-result hot path consumes the realm-index isolated HTML; the only production readers are:retrieveIsolatedHTMLinpackages/realm-server/server.ts:483).lastKnownGoodHtmlerror fallback for an erroring realm-index card.Both are narrow paths. Unpublished realms never need the isolated render at all.
The field stays unused for now
No production realm currently sets
includePrerenderedDefaultRealmIndex: true. The field is a future-lever and is wired up automatically for published realms by the next PR in the stack (#4770 — publish handler writes the field into the published snapshot'srealm.jsonwhen its index is the default CardsGrid).The boilerplate
Goals:
RealmInfo field is optional
RealmInfo.includePrerenderedDefaultRealmIndexis typed asboolean | null | undefinedto avoid forcing every fixture across runtime-common / host / realm-server test suites to add the field. Production code never relies on its presence — only on=== true.Test plan
pnpm lint:typesclean in@cardstack/runtime-commonand@cardstack/hostand@cardstack/realm-server.pnpm lint:jsclean for files this PR touches.index.jsonis default CardsGrid →isolated_htmlrow equalsREALM_INDEX_BOILERPLATE_HTML; other formats render normally.includePrerenderedDefaultRealmIndex: trueinrealm.json→isolated_htmlcontains a full rendered grid (verifies the lever works even though no production realm uses it today).isolated_htmlrenders normally regardless of the field.🤖 Generated with Claude Code