Allow opening linked filedef in the stack by jurgenwerk · Pull Request #4013 · cardstack/boxel

jurgenwerk · 2026-02-18T14:25:34Z

This PR adds the ability to click on a FileDef, which opens as a card in the stack.

Here is an example with a @field featuredImage = linksTo(ImageDef);:

Screen.Recording.2026-02-20.at.10.32.48.mov

github-actions · 2026-02-18T14:33:22Z

Preview deployments

github-actions · 2026-02-18T14:45:07Z

Host Test Results

1 files ±0 1 suites ±0 1h 43m 32s ⏱️ + 3m 25s
1 857 tests +1 1 843 ✅ +1 14 💤 ±0 0 ❌ ±0
1 872 runs +1 1 858 ✅ +1 14 💤 ±0 0 ❌ ±0

Results for commit cb32ae9. ± Comparison against base commit 8d45ff7.

♻️ This comment has been updated with latest results.

…e-should-successfully

Copilot

Pull request overview

This PR adds the ability to click on a linked FileDef in operator mode, which opens it as a card in the stack. The implementation introduces a type system to distinguish between regular cards and file-meta instances throughout the stack handling logic.

Changes:

Introduced StackItemType to track whether stack items are 'card' or 'file-meta' instances
Added optional type parameter to getCard function and CardResource to support loading file-meta instances
Implemented read-only behavior for file-meta cards (no edit mode, always isolated format)

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/runtime-common/index.ts	Added optional `type` parameter to `getCard` function signature
packages/host/app/lib/stack-item.ts	Added `StackItemType` field and type inference logic to stack items
packages/host/app/lib/read-type.ts	New utility function to infer store read type from URL patterns
packages/host/app/resources/card-resource.ts	Extended CardResource to support both card and file-meta types with fallback logic
packages/host/app/services/store.ts	Updated reference management to handle file-meta type wiring
packages/host/app/services/operator-mode-state-service.ts	Added type tracking in serialization/deserialization and prevented editing of file-meta items
packages/host/app/components/operator-mode/stack-item.gts	Added file card detection and forced isolated format for file-meta instances
packages/host/app/components/operator-mode/overlays.gts	Passed CardDef instances (not just URLs) to viewCard handler for type detection
packages/host/app/components/operator-mode/operator-mode-overlays.gts	Disabled edit button for file-meta targets
packages/host/app/components/operator-mode/preview-panel/index.gts	Added type parameter when opening cards in interact mode
packages/host/app/components/operator-mode/interact-submode.gts	Added type inference logic for stack items based on instance or store state
packages/host/app/components/host-mode/*.gts	Added type inference using URL patterns for host mode components
packages/base/links-to-editor.gts	Formatting change only (split hash onto multiple lines)
packages/host/tests/integration/components/operator-mode-ui-test.gts	Added test verifying linked files open in stack with correct type
packages/host/tests/acceptance/file-chooser-test.gts	Updated test expectation to include type field in serialized state

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

Copilot · 2026-02-20T09:57:47Z

packages/host/app/resources/card-resource.ts

+    return this.readType === 'file-meta'
+      ? Boolean(this.store.peek(this.#id, { type: 'file-meta' }))
+      : Boolean(this.store.peek(this.#id));


The isLoaded getter doesn't use the fallback logic that the card getter uses (lines 91-93). This means if the type hint is incorrect, isLoaded could return false even when the card/file-meta instance is actually loaded in the store under the other type. Consider updating this getter to also check the fallback type, similar to how the card getter works.

Suggested change

return this.readType === 'file-meta'

? Boolean(this.store.peek(this.#id, { type: 'file-meta' }))

: Boolean(this.store.peek(this.#id));

let maybeCard =

this.peekForType(this.readType) ??

this.peekForType(this.fallbackReadType);

return isCardInstance(maybeCard) || isFileDefInstance(maybeCard);

Copilot · 2026-02-20T09:57:47Z

packages/host/app/components/operator-mode/interact-submode.gts

+  private getStackItemType(
+    cardOrURL: CardDef | URL | string,
+    cardId: string,
+  ): StackItemType {
+    if (
+      cardOrURL &&
+      typeof cardOrURL === 'object' &&
+      !(cardOrURL instanceof URL)
+    ) {
+      return isFileDefInstance(cardOrURL as CardDef) ? 'file-meta' : 'card';
+    }
+    let fileMetaInstanceOrError =
+      this.store.peek(cardId, { type: 'file-meta' }) ??
+      this.store.peekError(cardId, { type: 'file-meta' });
+    return fileMetaInstanceOrError ? 'file-meta' : 'card';
+  }


When cardOrURL is a URL string that points to a file (has extension, not .json), but the file-meta instance is not yet loaded in the store, this method will return 'card' instead of 'file-meta'. This could cause the wrong type to be used when opening a file via direct navigation. Consider using inferStoreReadType as a fallback when no instance is found in the store to correctly detect file URLs based on their extension pattern.

packages/host/app/components/operator-mode/operator-mode-overlays.gts

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.

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

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cb32ae9e82

ℹ️ 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".

chatgpt-codex-connector · 2026-02-20T10:32:07Z

packages/host/app/resources/card-resource.ts

+    if (this.readType === 'file-meta' && this.peekForType('file-meta')) {
+      return undefined;


Do not suppress file-meta errors in card resource

When readType is 'file-meta', this early return hides real load failures because store.peek(id, { type: 'file-meta' }) can return a CardErrorJSONAPI, not just a successful FileDef. In that case cardError becomes undefined, so consumers that gate on !card && !cardError will show a loading state instead of surfacing the fetch error (e.g., missing/forbidden linked files opened in the stack).

Useful? React with 👍 / 👎.

i think this comment is trying to convey the subtleties of peek returning local state when the server state is in error (as i was mentioning in another comment). consider peekLive() if you need to know the current server state of the instance.

habdelra · 2026-02-20T14:24:29Z

packages/host/app/services/store.ts

      // intentionally not awaiting this. we keep track of the promise in
      // this.newReferencePromises
-      this.wireUpNewReference(id);
+      this.wireUpNewReference(id, readType);


could we add a test for file def reference counting? there are a bunch of reference count balancing tests in the store-test.gts, could we update this to include file def's in the mix too?

habdelra · 2026-02-20T14:29:34Z

packages/host/app/resources/card-resource.ts

+      ? (this.store.peek(this.#id, { type: 'file-meta' }) as unknown)
+      : (this.store.peek(this.#id) as unknown);


be aware there is a very subtle nuance around peeking. if the server state of the instance is in error and the local state is not, then the peek will give u the local state. unsure if this effects what you are trying to do. there is a peekLive() that will give you the server state regardless of whether or not it is in error.

lukemelia · 2026-02-20T14:55:32Z

packages/host/app/lib/read-type.ts

+export function isFileMetaId(id: string | null | undefined): boolean {
+  if (!id) {
+    return false;
+  }
+  return hasExtension(id) && !id.endsWith('.json');
+}
+
+export function inferStoreReadType(
+  id: string | null | undefined,
+): StoreReadType {
+  return isFileMetaId(id) ? 'file-meta' : 'card';
+}


This is an AI anti-pattern that I have had to fight . We should be using more explicit type specification, not inferring stuff from URLs

Note from our call:

consider adding a subprotocol or url annotation/prefix in urls in operator mode state that differentiate between card or file

default should be card

Allow opening linked filedef in the stack

d4be9f0

jurgenwerk added 9 commits February 19, 2026 10:04

Fix tests

dc12037

Merge branch 'main' into cs-10185-clicking-on-filedef-in-interact-mod…

0b9d449

…e-should-successfully

Fix tests

c88c5b3

Simplify figuring out whether it's a card or file

2e51a09

Simplify

918c240

A common function for inferring read type

c0f0c60

Simplify

3c9dcbd

Merge branch 'main' into cs-10185-clicking-on-filedef-in-interact-mod…

17cb08a

…e-should-successfully

Fix import order

9651f9d

jurgenwerk requested a review from Copilot February 20, 2026 09:49

Copilot started reviewing on behalf of jurgenwerk February 20, 2026 09:50 View session

Copilot AI reviewed Feb 20, 2026

View reviewed changes

Extract common logic

cb32ae9

jurgenwerk requested review from a team and Copilot February 20, 2026 10:24

jurgenwerk marked this pull request as ready for review February 20, 2026 10:24

Copilot started reviewing on behalf of jurgenwerk February 20, 2026 10:24 View session

Copilot AI reviewed Feb 20, 2026

View reviewed changes

chatgpt-codex-connector bot reviewed Feb 20, 2026

View reviewed changes

habdelra reviewed Feb 20, 2026

View reviewed changes

lukemelia reviewed Feb 20, 2026

View reviewed changes

-    return this.readType === 'file-meta'
-      ? Boolean(this.store.peek(this.#id, { type: 'file-meta' }))
-      : Boolean(this.store.peek(this.#id));
+    let maybeCard =
+      this.peekForType(this.readType) ??
+      this.peekForType(this.fallbackReadType);
+    return isCardInstance(maybeCard) || isFileDefInstance(maybeCard);

		if (this.readType === 'file-meta' && this.peekForType('file-meta')) {
		return undefined;

		? (this.store.peek(this.#id, { type: 'file-meta' }) as unknown)
		: (this.store.peek(this.#id) as unknown);

Comments

Conversation

jurgenwerk commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 18, 2026

Preview deployments

Uh oh!

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

Uh oh!

Host Test Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

habdelra Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

habdelra Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

habdelra Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lukemelia Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

jurgenwerk Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jurgenwerk commented Feb 18, 2026 •

edited

Loading

github-actions bot commented Feb 18, 2026 •

edited

Loading

habdelra Feb 20, 2026 •

edited

Loading

habdelra Feb 20, 2026 •

edited

Loading