RichMarkdown playground, card-embedding tests, and unresolved card reference UX by lukemelia · Pull Request #4362 · cardstack/boxel

lukemelia · 2026-04-08T19:02:11Z

Summary

Adds a RichMarkdown playground card in experiments-realm for testing BFM card embedding
Adds integration tests for inline/block card embedding, relative references, and linked card resolution
Adds visual states for unresolved card references: CSS shimmer while loading, muted Pill with broken-link icon and type name when not found

Unresolved card reference UX

When a :card[URL] or ::card[URL] reference can't be resolved, it now shows a styled Pill indicator instead of raw URL text:

Loading — CSS skeleton shimmer (:empty pseudo-class, no JS needed)
Not found — muted Pill with LinkOff icon and card type name (e.g. "Pet", "BlogPost"), raw URL in tooltip -- I'm going to ask @cmgardella to improve how this looks
Resolved — actual card component (unchanged)

Test plan

Unit tests for cardTypeName utility (realm-server test runner)
Acceptance test: unresolved inline and block card refs show Pill with correct type name and URL tooltip
Integration test: unresolved refs render muted Pill indicators
Existing card-embedding tests continue to pass
Manual: open a markdown card with :card[...] refs, verify shimmer → resolved card or Pill

🤖 Generated with Claude Code

Screen.Recording.2026-04-08.at.7.08.58.PM.mov

…ding Add a playground card in the experiments realm exercising the RichMarkdown field (standard markdown, GFM alerts, card references, math, mermaid, tables, code blocks, footnotes). Add two integration tests covering the full card-in-markdown rendering pipeline: one with absolute URLs and one with relative paths, both verifying that referenced cards actually render inside the markdown (not just that placeholders exist). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-04-08T19:10:21Z

Preview deployments

github-actions · 2026-04-08T19:26:05Z

Host Test Results

2 189 tests +4 2 174 ✅ +4 2h 23m 23s ⏱️ + 2m 33s
1 suites ±0 15 💤 ±0
1 files ±0 0 ❌ ±0

Results for commit a7afbfd. ± Comparison against base commit 861c03b.

♻️ This comment has been updated with latest results.

github-actions · 2026-04-08T19:27:13Z

Realm Server Test Results

1 files ±0 1 suites ±0 13m 41s ⏱️ -30s
843 tests +7 843 ✅ +7 0 💤 ±0 0 ❌ ±0
914 runs +7 914 ✅ +7 0 💤 ±0 0 ❌ ±0

Results for commit a7afbfd. ± Comparison against base commit 861c03b.

♻️ This comment has been updated with latest results.

Unresolved :card[URL] and ::card[URL] references now show a muted Pill with a broken-link icon and the card type name instead of raw URL text. A CSS shimmer animation displays while linkedCards is still loading. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…states Merge resolved and unresolved slots into a single RenderSlot array to eliminate dual #in-element race. Add deferred setTimeout fallback for _modifierHasRun so in-app navigation correctly transitions from loading shimmer to error Pill. Remove vestigial el.firstChild.remove() calls that broke Glimmer text node markers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

@height

…en Pills - Replace setTimeout(0) fallback with linkedCards.length > 0 check to avoid flashing broken Pills before cards resolve on fresh page load - Fix LinkOffIcon @width/@height to plain HTML attributes (TS2554) - Fix store.get<BaseDef> to untyped + as BaseDef cast (TS2344/TS2749) - Fix cardTypeName to filter '.' segments from relative paths like './Foo' - Add link-off icon to realm-indexing-test expected card references - Use MutationObserver in loading shimmer test for better regression detection Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR improves the RichMarkdown/BFM card-reference experience by adding a playground card, expanding coverage around card embedding/link resolution, and introducing a clearer unresolved-reference UI (loading shimmer → muted “broken link” Pill).

Changes:

Add cardTypeName() helper + shared tests, and wire those into realm-server’s test runner.
Update the base markdown template to render unresolved card refs as shimmer/loading placeholders and “not found” Pills (with LinkOff icon + type label).
Add host integration/acceptance tests for inline/block embedding, relative references, and unresolved UX; add an experiments-realm playground card + sample content.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/runtime-common/tests/bfm-card-references-test.ts	Shared tests for `cardTypeName()` behavior.
packages/runtime-common/bfm-card-references.ts	Introduces `cardTypeName()` utility used by unresolved-ref UI.
packages/realm-server/tests/index.ts	Registers the new shared-test wrapper for realm-server runs.
packages/realm-server/tests/bfm-card-references-test.ts	Runs runtime-common shared tests in realm-server QUnit suite.
packages/host/tests/integration/realm-indexing-test.gts	Adds `link-off` icon to the integration test allowlist.
packages/host/tests/integration/components/rich-markdown-field-test.gts	Adds integration coverage for resolved/unresolved refs + loading transition behavior.
packages/host/tests/acceptance/markdown-file-def-test.gts	Updates acceptance expectations to assert new unresolved Pill UI.
packages/experiments-realm/rich-markdown-playground.gts	Adds a playground card for manual BFM/RichMarkdown testing.
packages/experiments-realm/rich-markdown-playground-1.json	Adds seeded playground content showcasing many markdown features.
packages/base/default-templates/markdown.gts	Implements shimmer loading + unresolved Pill rendering for card references.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/runtime-common/bfm-card-references.ts

packages/experiments-realm/rich-markdown-playground-1.json

backspace

I ran this locally, all worked as described

packages/host/tests/integration/components/rich-markdown-field-test.gts

packages/experiments-realm/rich-markdown-playground.gts

Parse absolute URLs via new URL() in cardTypeName to correctly handle query strings, fragments, and URLs without an id segment. Filter out ".." segments for relative paths. Fix missing space in playground title. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lukemelia changed the title ~~Add RichMarkdown playground card and card-embedding integration tests~~ RichMarkdown playground, card-embedding tests, and unresolved card reference UX Apr 8, 2026

lukemelia and others added 4 commits April 8, 2026 18:21

Revert bfm-showcase.md to main branch version

af352d2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix prettier formatting in bfm-card-references-test

0a63e4e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lukemelia requested review from a team, backspace and Copilot April 9, 2026 01:20

Copilot started reviewing on behalf of lukemelia April 9, 2026 01:20 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

packages/runtime-common/bfm-card-references.ts Outdated Show resolved Hide resolved

packages/experiments-realm/rich-markdown-playground-1.json Outdated Show resolved Hide resolved

backspace approved these changes Apr 9, 2026

View reviewed changes

packages/host/tests/integration/components/rich-markdown-field-test.gts Show resolved Hide resolved

packages/experiments-realm/rich-markdown-playground.gts Show resolved Hide resolved

lukemelia and others added 2 commits April 8, 2026 22:31

Fix prettier formatting in bfm-card-references-test

a7afbfd

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lukemelia merged commit a928897 into main Apr 9, 2026
64 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RichMarkdown playground, card-embedding tests, and unresolved card reference UX#4362

RichMarkdown playground, card-embedding tests, and unresolved card reference UX#4362
lukemelia merged 8 commits intomainfrom
rich-markdown-playground-and-tests

lukemelia commented Apr 8, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 8, 2026

Uh oh!

github-actions bot commented Apr 8, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 8, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

backspace left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

lukemelia commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Unresolved card reference UX

Test plan

Uh oh!

github-actions bot commented Apr 8, 2026

Preview deployments

Uh oh!

github-actions bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Host Test Results

Uh oh!

github-actions bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Realm Server Test Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

backspace left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lukemelia commented Apr 8, 2026 •

edited

Loading

github-actions bot commented Apr 8, 2026 •

edited

Loading

github-actions bot commented Apr 8, 2026 •

edited

Loading