Core: Fix iframe reference for composed Storybook on a subpath

[ghengeveld]

Closes #34094

What I did

With Storybook composition, when one ref is at the root of an origin (e.g. https://example.com/) and another is in a subpath (e.g. https://example.com/sub/), composed iframe URLs were being reused (not updated), causing incorrect references when navigating to a composed story directly.

Because the root URL is a prefix of the subpath URL, a frame that already had the sub URL could be treated as "already set" for the root ref due to a naive startsWith check. The root ref’s iframe then kept the sub URL, so two iframes pointed at the same sub URL. The manager then saw multiple iframes with the same origin/path and couldn’t tell which one sent a message, leading to found multiple candidates for event source and received setGlobals but was unable to determine the source of the event.

To fix this, the startsWith check now includes iframe.html to avoid unexpected matches between different subpaths on the same domain.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

Caution

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This pull request has been released as version 0.0.0-pr-34100-sha-210f2133. Try it out in a new sandbox by running npx storybook@0.0.0-pr-34100-sha-210f2133 sandbox or in an existing project with npx storybook@0.0.0-pr-34100-sha-210f2133 upgrade.

More information

Published version	0.0.0-pr-34100-sha-210f2133
Triggered by	@ghengeveld
Repository	storybookjs/storybook
Branch	fix-composition-on-common-base-url
Commit	210f2133
Datetime	Wed Mar 11 10:35:08 UTC 2026 (1773225308)
Workflow run	22948346645

To request a new release of this pull request, mention the @storybookjs/core team.

core team members can create a new canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=34100

Summary by CodeRabbit

• Bug Fixes
  • Refined frame rendering logic to more accurately compare URLs when determining if frames need to be refreshed, ensuring proper handling of frame loading conditions based on updated URL matching criteria.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 210f213

Command	Status	Duration	Result
nx run-many -t compile -c production --parallel=1	✅ Succeeded	5m 15s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-03-11 10:49:15 UTC

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8251a58f-91e1-48a2-87ca-3eab04208e08

📥 Commits

Reviewing files that changed from the base of the PR and between 2f7360f and 210f213.

📒 Files selected for processing (1)

• code/core/src/manager/components/preview/FramesRenderer.tsx

---

📝 Walkthrough

Walkthrough

Modified the loading guard condition in FramesRenderer.tsx for per-ref frame hrefs. The check now requires the stored URL to start with ref.url normalized to include an iframe.html suffix, rather than just checking the base ref.url. This tightens the condition to ensure proper URL matching with the normalized iframe path.

Changes

Cohort / File(s)	Summary
Frame Loading Guard code/core/src/manager/components/preview/FramesRenderer.tsx	Modified the loading guard condition to check if the stored frame URL starts with ref.url normalized to end with iframe.html, rather than just the base ref.url. This ensures frames are refreshed only when the stored URL doesn't match the normalized iframe.html-suffixed prefix.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Core: Fix previewHref when current path does not end with a slash #33647: Fixes previewHref construction to ensure iframe.html suffix, directly complementary to this loading guard tightening.
• Core: Storybook failed to load iframe.html when publishing #33896: Modifies previewBase generation to append iframe.html for subpaths, aligning with the normalized URL expectations in this guard change.
• Manager: Update logic to use base path instead of full pathname #33686: Addresses URL normalization and comparison logic for refs, sharing the same iframe.html handling pattern.

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}