[Bug]: Controls never load with two Storybooks (refs) if initial page is a ref story

[logindejavu27]

Describe the bug

Controls never load with two Storybooks (refs).

The first time I upgraded to v10, everything was working fine, but I can’t recall the exact version. However, it definitely stopped working in v10.2.7, and since then I’ve been trying all the latest releases, including v10.4.0-alpha.9, and it still never works.

I prepared small monorepo porject where you can reproduce the issue on your side
storybook-refs-issue.zip

Reproduction link

http://127.0.0.1:8080

Reproduction steps

I prepared small monorepo porject where you can reproduce the issue on your side

1. Run the following commands:

yarn install
yarn build
yarn storybook:preview

2. Then navigate to http://127.0.0.1:8080 and Select "Default"(canvas) story from React components section

3. Refresh the browser using F5

4. The Controls panel will load indefinitely! The same happens if you copy current URL and open it in another tab - controls never load. Like http://127.0.0.1:8080/storybook-wc/index.html?path=/story/react_mybutton--default

storybook-refs-issue.zip

System

...is not OS/Browser specific, since same is reproducible in Ubuntu(WSL2)

Storybook Environment Info:

│  System:
│  OS: Windows 11 10.0.22631
│  CPU: (20) x64 13th Gen Intel(R) Core(TM) i7-13800H
│  Binaries:
│  Node: 20.19.5 - C:\Users\xxxxx\AppData\Local\Temp\xfs-6c2f8467\node.CMD
│  Yarn: 4.5.0 - C:\Users\xxxxx\AppData\Local\Temp\xfs-6c2f8467\yarn.CMD <-----
│  active
│  npm: 10.8.2 - C:\Program Files\nodejs\npm.CMD
│  Browsers:
│  Chrome: 147.0.7727.56
│  Edge: Chromium (146.0.3856.97)
│  Firefox: 149.0.2 - C:\Program Files\Mozilla Firefox\firefox.exe

Additional context

No response

[TheSeydiCharyyev]

Reproduced on Storybook 10.4.0-alpha.9 with the attached repro zip and traced the root cause.

Root cause

ControlsPanel.tsx#L69-L78 only listens to the global state.previewInitialized flag:

const { path, previewInitialized } = useStorybookState();
useEffect(() => {
  if (previewInitialized) {
    setIsLoading(false);
  }
}, [previewInitialized]);

For stories from a composed ref (the repro uses extends: true), the previewInitialized flag is set per-ref in state.refs[refId].previewInitialized, while the global state.previewInitialized stays false because the host preview is never loaded for these stories. So isLoading never flips to false and ArgsTable renders skeletons forever.

Empirical confirmation

In the repro, with story react/my-button--default selected:

state.previewInitialized           // false
state.refs.react.previewInitialized // true

const entry = state.refs.react.index['my-button--default'];
// { prepared: true, args: { default: 'Button' }, initialArgs: {...},
//   argTypes: { default, variant, disabled }, ... }
// → ref data is correct, just not consumed by the panel

api.setPreviewInitialized()  // forces the global flag
// → Controls panel immediately renders the 3 real controls

The data flow (SET_INDEX → STORY_PREPARED → updateStory(id, ..., ref) → ref's index entry has args/initialArgs/argTypes/prepared:true) is intact. The only gap is the panel reading the wrong flag.

Suggested fix

In ControlsPanel.tsx, prefer the ref's previewInitialized when the current story belongs to a ref:

const { path, refId, refs, previewInitialized } = useStorybookState();
const isPreviewReady = refId ? refs?.[refId]?.previewInitialized : previewInitialized;

useEffect(() => {
  if (isPreviewReady) {
    setIsLoading(false);
  }
}, [isPreviewReady]);

Want me to open a PR with this fix + a regression test? Or is there a design call I'm missing about ref previewInitialized propagation?

[TheSeydiCharyyev]

@valentinpalkovic — flagging this one for direction. Root cause and a minimal fix are above: ControlsPanel reads the global previewInitialized, but for stories from a composed ref that flag lives in refs[refId].previewInitialized, so the panel stays in the loading state forever. Can open a PR with the fix + a regression test — just want to confirm there's no design reason the panel intentionally ignores per-ref readiness.

[Sidnioulz]

@TheSeydiCharyyev I tested the canary (0.0.0-pr-35050-sha-bd7a5628) against the repro case and it does fix the original bug, BUT, it introduces a new one 😭

If you first load a host story, then all stories' controls work. But if you first load a ref story, then the host stories' controls don't work any more.

Would you be ok to look into this in the coming weeks please? 🙏

[TheSeydiCharyyev]

Looking into the regression — I reproduced it on the 0.0.0-pr-35050-sha-bd7a5628 canary against the storybook-refs-issue repro.

What I'm seeing: after a ref-first load, navigating to a host story leaves the canvas itself stuck ("Couldn't find story matching id …" → spinner), so the host story never prepares and Controls has no argTypes to render — which looks separate from the ControlsPanel change in this PR.

It seems to trace to FramesRenderer: the local preview frame is initialized once, and since v10.3.0 (the getStoryHrefs refactor, 2a864fdb) that init passes the current story's refId:

frames['storybook-preview-iframe'] = api.getStoryHrefs(storyId, { queryParams, refId, viewMode }).previewHref;

For a non-empty refId, getStoryHrefs returns the ref's iframe URL, so on a ref-first load the local frame ends up pointed at the ref's Storybook and is never re-pointed (the if (!frames[...]) guard). Host-first avoids it because the first call has no refId. Before v10.3.0 the local frame was built without refId.

Dropping refId from that one call made ref-first → host render correctly in my testing, with host-first still working.

Does that match your read of it? And would you like me to open a separate PR for the FramesRenderer change with a regression test?

[Sidnioulz]

I am truly not sure why the bug is occurring. I don't know this part very well and I haven't found time to learn it. If you feel confident you've found the issue, https://github.com/Sidnioulz/storybook-35050-repro could act as a repro case. Feel free to open a PR and I'll trigger the workflow to produce a NPM canary for it! (little tip: preserve the PR template to have the section in the description where the canary workflow will write the package name ;-) )