Release: Prerelease 10.5.0-alpha.6

.github/workflows/trigger-circle-ci-workflow.yml

@@ -94,21 +94,37 @@ jobs:
       - id: trusted-author
         env:
           EVENT_NAME: ${{ github.event_name }}
-          ASSOCIATION: ${{ github.event.pull_request.author_association }}
           USER_TYPE: ${{ github.event.pull_request.user.type }}
           USER_LOGIN: ${{ github.event.pull_request.user.login }}
+          GITHUB_API_TOKEN: ${{ secrets.STORYBOOKJS_ORG_MEMBERSHIP_TOKEN }}
         run: |
           # You can only push to `main` and `next` as a core team member, so the content is trustworthy.
           if [ "$EVENT_NAME" = "push" ]; then
             echo "result=true" >> "$GITHUB_OUTPUT"
           # These commits are made by the release actions, which are gated to core team members.
           elif [ "$USER_LOGIN" = "github-actions[bot]" ] && [ "$USER_TYPE" = "Bot" ]; then
             echo "result=true" >> "$GITHUB_OUTPUT"
-          # Trusted members of the organization can also write to cache (core team, DX, and a few maintainers)
-          elif { [ "$ASSOCIATION" = "OWNER" ] || [ "$ASSOCIATION" = "MEMBER" ]; } && [ "$USER_TYPE" != "Bot" ]; then
-            echo "result=true" >> "$GITHUB_OUTPUT"
           else
-            echo "result=false" >> "$GITHUB_OUTPUT"
+            # Explicitly trust only members of specific Storybook teams.
+            # Team slugs for: Maintainers, Core, Developer Experience.
+            TRUSTED_TEAMS="maintainers core developer-experience"
+            IS_TRUSTED=false
+
+            for TEAM in $TRUSTED_TEAMS; do
+              STATE=$(curl -fsSL \
+                -H "Authorization: Bearer $GITHUB_API_TOKEN" \
+                -H "Accept: application/vnd.github+json" \
+                -H "X-GitHub-Api-Version: 2022-11-28" \
+                "https://api.github.com/orgs/storybookjs/teams/$TEAM/memberships/$USER_LOGIN" \
+                | jq -r '.state' 2>/dev/null || true)
+
+              if [ "$STATE" = "active" ]; then
+                IS_TRUSTED=true
+                break
+              fi
+            done
+
+            echo "result=$IS_TRUSTED" >> "$GITHUB_OUTPUT"
           fi
     outputs:
       workflow: ${{ steps.normal.outputs.workflow || steps.docs.outputs.workflow || steps.merged.outputs.workflow || steps.daily.outputs.workflow }}
@@ -129,12 +145,14 @@ jobs:
           WORKFLOW: ${{ needs.get-parameters.outputs.workflow }}
           GH_BASE_BRANCH: ${{ needs.get-parameters.outputs.ghBaseBranch }}
           GH_PR_NUMBER: ${{ needs.get-parameters.outputs.ghPrNumber }}
+          GH_TRUSTED_AUTHOR: ${{ needs.get-parameters.outputs.ghTrustedAuthor }}
         run: |
           PARAMETERS=$(jq -nc \
             --arg workflow "$WORKFLOW" \
             --arg ghBaseBranch "$GH_BASE_BRANCH" \
             --arg ghPrNumber "$GH_PR_NUMBER" \
-            '{workflow: $workflow, ghBaseBranch: $ghBaseBranch, ghPrNumber: $ghPrNumber}')
+            --arg ghTrustedAuthor "$GH_TRUSTED_AUTHOR" \
+            '{workflow: $workflow, ghBaseBranch: $ghBaseBranch, ghPrNumber: $ghPrNumber, ghTrustedAuthor: $ghTrustedAuthor}')
           PAYLOAD=$(jq -nc --arg branch "$BRANCH" --argjson parameters "$PARAMETERS" \
             '{branch: $branch, parameters: $parameters}')
           curl -sS --fail-with-body -X POST \

AGENTS.md

@@ -9,7 +9,7 @@ This file is the canonical instruction source for coding agents. Files like `CLA
 Storybook is a large TypeScript monorepo. The git root is the repo root, the main code lives in `code/`, and build tooling lives in `scripts/`. The default branch is `next`.
 
 - **Base branch**: `next` (all PRs should target `next`, not `main`)
-- **Node.js**: `22.12+` (see `.nvmrc`) — supports `.ts` natively via type stripping (no loader needed)
+- **Node.js**: `22.22.3` (see `.nvmrc`) — supports `.ts` natively via type stripping (no loader needed)
 - **Package Manager**: Yarn Berry
 - **Task orchestration**: NX plus the custom `yarn task` runner
 - **CI environment**: Linux and Windows
@@ -243,6 +243,17 @@ When writing unit tests (utilities, hooks, non-React modules):
 - Use coverage when useful: `yarn vitest run --coverage <test-file>`
 - Mock external dependencies like file system access and loggers
 
+### Filesystem tests with `memfs`
+
+For unit tests that touch `node:fs` / `node:fs/promises`, use [`memfs`](https://github.com/streamich/memfs) instead of real temp directories or wholesale `node:fs` mocks:
+
+- Import `vol` from `memfs` and call `vol.reset()` in `beforeEach`
+- Seed virtual files with `vol.fromNestedJSON({ '/absolute/path/file.json': '...' })` or memfs `writeFile` after redirecting spies
+- Use `vi.mock('node:fs/promises', { spy: true })` and, in `beforeEach`, point `mkdir` / `writeFile` / `readFile` at `memfs.fs.promises` (see `code/core/src/shared/open-service/server.test.ts`)
+- Assert disk state with `vol.toJSON()` when helpful
+
+Do **not** use `/tmp` paths or replace `node:fs/promises` with a full async factory mock unless a test file already standardizes on the spy redirect pattern above.
+
 ## Quality and Logging
 
 After changing files:
@@ -273,12 +284,12 @@ Avoid `console.log`, `console.warn`, and `console.error` unless the file is isol
 
 ## Environment Variables
 
-| Variable                      | Purpose                     |
-| ----------------------------- | --------------------------- |
-| `IN_STORYBOOK_SANDBOX`        | Set during sandbox creation |
-| `STORYBOOK_DISABLE_TELEMETRY` | Disable telemetry           |
-| `STORYBOOK_TELEMETRY_DEBUG`   | Log telemetry events        |
-| `DEBUG`                       | Enable debug logging        |
+| Variable                      | Purpose                                         |
+| ----------------------------- | ----------------------------------------------- |
+| `IN_STORYBOOK_SANDBOX`        | Set during sandbox creation                     |
+| `STORYBOOK_DISABLE_TELEMETRY` | Disable telemetry                               |
+| `STORYBOOK_TELEMETRY_DEBUG`   | Log telemetry events                            |
+| `DEBUG`                       | Enable debug logging                            |
 | `FIX_ON_COMMIT`               | Force autofix for fmt & lint in pre-commit hook |
 
 ## Commands To Avoid

CHANGELOG.prerelease.md

@@ -1,3 +1,22 @@
+## 10.5.0-alpha.6
+
+- Controls: Guard normalizeOptions against array labels and prototype chain lookups - [#34664](https://github.com/storybookjs/storybook/pull/34664), thanks @creazyfrog!
+- Core: Add ref-based components manifest index backed by docgen open service - [#35063](https://github.com/storybookjs/storybook/pull/35063), thanks @JReinhold!
+- Core: Fix resolveImport TSX fallback - [#34815](https://github.com/storybookjs/storybook/pull/34815), thanks @cyphercodes!
+- Core: Rework AI checklist feature gate - [#35053](https://github.com/storybookjs/storybook/pull/35053), thanks @Sidnioulz!
+- Docs: Deprecate ExternalDocs - [#35074](https://github.com/storybookjs/storybook/pull/35074), thanks @Sidnioulz!
+- Interactions: Prevent debugger controls from stealing focus - [#35073](https://github.com/storybookjs/storybook/pull/35073), thanks @BrenoSI03!
+- Manager: Keep local preview iframe on host URL when a ref story loads first - [#35078](https://github.com/storybookjs/storybook/pull/35078), thanks @TheSeydiCharyyev!
+- Module Graph: Refactor from StoryDependencyService to open service-based ModuleGraphService - [#35048](https://github.com/storybookjs/storybook/pull/35048), thanks @JReinhold!
+- Open Service: Add `internal` property to control visibility - [#35057](https://github.com/storybookjs/storybook/pull/35057), thanks @JReinhold!
+- Open Service: Add sync between server, manager and preview - [#35017](https://github.com/storybookjs/storybook/pull/35017), thanks @ndelangen!
+- Open Service: Call remote commands in load functions - [#35106](https://github.com/storybookjs/storybook/pull/35106), thanks @JReinhold!
+- Preview: Stop mixed CSF3+4 stories getting core annotations injected twice - [#35094](https://github.com/storybookjs/storybook/pull/35094), thanks @JReinhold!
+- React: Fix subcomponent prop extraction without JSX usage - [#35107](https://github.com/storybookjs/storybook/pull/35107), thanks @JReinhold!
+- Telemetry: Add timeout to event-log POST to prevent build hang - [#35085](https://github.com/storybookjs/storybook/pull/35085), thanks @badams!
+- Viewport: Highlight toolbar button when custom viewport is active - [#35075](https://github.com/storybookjs/storybook/pull/35075), thanks @derinbarutcu17!
+- Webpack: Gate lazy-compilation import pipeline on webpack version - [#34931](https://github.com/storybookjs/storybook/pull/34931), thanks @copilot-swe-agent!
+
 ## 10.5.0-alpha.5
 
 - Addon Docs: DocsContent not filling available width when TOC is enabled - [#35043](https://github.com/storybookjs/storybook/pull/35043), thanks @k-utsumi!

MIGRATION.md

@@ -1,8 +1,10 @@
 <h1>Migration</h1>
 
+- [From version 10.4.0 to 10.5.0](#from-version-1040-to-1050)
+  - [ExternalDocs and ExternalDocsContainer are deprecated](#externaldocs-and-externaldocscontainer-are-deprecated)
 - [From version 10.3.0 to 10.4.0](#from-version-1030-to-1040)
   - [React Native: on-device addons moved to `deviceAddons`](#react-native-on-device-addons-moved-to-deviceaddons)
-  - [TanStack React: migrate from `@storybook/react-vite` to `@storybook/tanstack-react`](#tanstack-router-projects-migrate-from-storybookreact-vite-to-storybooktanstack-react)
+  - [TanStack Router projects: migrate from `@storybook/react-vite` to `@storybook/tanstack-react`](#tanstack-router-projects-migrate-from-storybookreact-vite-to-storybooktanstack-react)
 - [From version 10.0.0 to 10.1.0](#from-version-1000-to-1010)
   - [API and Component Changes](#api-and-component-changes)
     - [Button Component API Changes](#button-component-api-changes)
@@ -523,6 +525,14 @@
   - [Packages renaming](#packages-renaming)
   - [Deprecated embedded addons](#deprecated-embedded-addons)
 
+## From version 10.4.0 to 10.5.0
+
+### ExternalDocs and ExternalDocsContainer are deprecated
+
+The `ExternalDocs` and `ExternalDocsContainer` components from `@storybook/addon-docs` are deprecated and will be removed in Storybook 11. These components allowed rendering Storybook docs pages outside of the Storybook UI, but the approach was never stabilized and is redundant with other embedding options.
+
+If you are currently using `ExternalDocs` or `ExternalDocsContainer`, please open an issue describing your use case so the team can consider alternative solutions.
+
 ## From version 10.3.0 to 10.4.0
 
 ### React Native: on-device addons moved to `deviceAddons`

code/.storybook/main.ts

@@ -37,6 +37,10 @@ const config = defineMain({
       directory: '../core/src/preview',
       titlePrefix: 'preview',
     },
+    {
+      directory: '../core/src/shared',
+      titlePrefix: 'core/shared',
+    },
     {
       directory: '../core/src/components/brand',
       titlePrefix: 'brand',
@@ -184,7 +188,13 @@ const config = defineMain({
       server: {
         watch: {
           // Something odd happens with tsconfig and nx which causes Storybook to keep reloading, so we ignore them
-          ignored: ['**/.nx/cache/**', '**/tsconfig.json'],
+          ignored: [
+            '**/.nx/cache/**',
+            '**/tsconfig.json',
+            // Internal e2e writes traces under code/playwright-results while the dev server is running.
+            '**/playwright-results/**',
+            '**/playwright-report/**',
+          ],
         },
       },
     } satisfies typeof viteConfig);

code/.storybook/manager.tsx

@@ -6,3 +6,5 @@ addons.setConfig({
     renderLabel: ({ name, type }) => (type === 'story' ? name : startCase(name)),
   },
 });
+
+import '../core/src/shared/open-service/sync-test/manager.tsx';

code/.storybook/open-service-debug-service.ts

@@ -3,7 +3,7 @@ import * as v from 'valibot';
 import { logger } from 'storybook/internal/node-logger';
 import type { StoryIndexGenerator } from '../core/src/core-server/utils/StoryIndexGenerator.ts';
 
-import { defineService } from '../core/src/shared/open-service/index.ts';
+import { defineService } from 'storybook/open-service';
 import { describeService, registerService } from '../core/src/shared/open-service/server.ts';
 
 const DEBUG_SERVICE_ID = 'storybook/internal/open-service-debug';

code/.storybook/preview.tsx

@@ -51,6 +51,8 @@ sb.mock(import('lodash-es/sum'));
 sb.mock(import('uuid'));
 /* eslint-enable depend/ban-dependencies */
 
+import '../core/src/shared/open-service/sync-test/preview.ts';
+
 const { document } = global;
 globalThis.CONFIG_TYPE = 'DEVELOPMENT';
 

code/.storybook/services-preset.ts

@@ -1,15 +1,16 @@
 import type { Options, StorybookConfigRaw } from 'storybook/internal/types';
 
+import { registerOpenServiceSyncDemos } from '../core/src/shared/open-service/sync-test/server.ts';
 import { registerOpenServiceDebugService } from './open-service-debug-service.ts';
 
 /**
- * Preset hook that registers the internal open-service debug service.
+ * Preset hook that registers internal open-service examples and the opt-in debug service.
  *
- * Lives in its own preset file so the `services` slot stays out of the public `StorybookConfig`
- * surface while still letting the internal Storybook self-test the registration path. Set
- * `STORYBOOK_OPEN_SERVICE_DEBUG=true` to opt in.
+ * Set `STORYBOOK_OPEN_SERVICE_DEBUG=true` to additionally register the debug service.
  */
 export const services = async (_value: void, options: Options): Promise<void> => {
+  registerOpenServiceSyncDemos();
+
   if (process.env.STORYBOOK_OPEN_SERVICE_DEBUG === 'true') {
     await registerOpenServiceDebugService(
       options.presets.apply<NonNullable<StorybookConfigRaw['storyIndexGenerator']>>(

code/.storybook/storybook.setup.ts

@@ -5,6 +5,7 @@ import { setProjectAnnotations } from '@storybook/react';
 import { userEvent as storybookEvent, expect as storybookExpect } from 'storybook/test';
 
 import '../core/src/shared/utils/toHaveLiveRegion.ts';
+
 import preview from './preview.tsx';
 
 vi.spyOn(console, 'warn').mockImplementation((...args) => console.log(...args));

code/.storybook/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["**/*"]
+}

code/addons/docs/src/blocks/blocks/external/ExternalDocs.tsx

@@ -1,6 +1,7 @@
 import type { PropsWithChildren } from 'react';
 import React, { useRef } from 'react';
 
+import { deprecate } from 'storybook/internal/client-logger';
 import type { ProjectAnnotations, Renderer } from 'storybook/internal/types';
 
 import { composeConfigs } from 'storybook/preview-api';
@@ -27,6 +28,7 @@ export function ExternalDocs<TRenderer extends Renderer = Renderer>({
   projectAnnotationsList,
   children,
 }: PropsWithChildren<ExternalDocsProps<TRenderer>>) {
+  deprecate(`ExternalDocs is deprecated and will be removed in Storybook 11.`);
   const projectAnnotations = composeConfigs<TRenderer>(projectAnnotationsList);
   const preview = usePreview<TRenderer>(projectAnnotations);
   const docsParameter = {

code/addons/docs/src/blocks/blocks/external/ExternalDocsContainer.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 
+import { deprecate } from 'storybook/internal/client-logger';
 import type { Renderer } from 'storybook/internal/types';
 
 import { ThemeProvider, ensure, themes } from 'storybook/theming';
@@ -12,6 +13,7 @@ let preview: ExternalPreview<Renderer>;
 export const ExternalDocsContainer: React.FC<
   React.PropsWithChildren<{ projectAnnotations: any }>
 > = ({ projectAnnotations, children }) => {
+  deprecate(`ExternalDocsContainer is deprecated and will be removed in Storybook 11.`);
   if (!preview) {
     preview = new ExternalPreview(projectAnnotations);
   }

code/addons/docs/src/blocks/controls/options/CheckOptions.stories.tsx

@@ -10,6 +10,12 @@ const labels = {
   Cat: 'Catwoman',
   Rat: 'Ratwoman',
 };
+// Only `Bat` is labelled; `Cat` and `Rat` should fall back to String(item).
+const partialLabels = {
+  Bat: 'Batwoman',
+};
+// Options that collide with Array.prototype method names — the regression case.
+const prototypeCollisionOptions = ['reverse', 'map', 'filter'];
 const objectOptions = {
   A: { id: 'Aardvark' },
   B: { id: 'Bat' },
@@ -70,6 +76,57 @@ export const ArrayInlineLabels: Story = {
   },
 };
 
+// Partial labels: only 'Bat' is mapped; 'Cat' and 'Rat' fall back to String(item).
+export const ArrayLabelsPartial: Story = {
+  args: {
+    value: [arrayOptions[0]],
+    labels: partialLabels,
+  },
+};
+
+export const ArrayInlineLabelsPartial: Story = {
+  args: {
+    type: 'inline-check',
+    value: [arrayOptions[1], arrayOptions[2]],
+    labels: partialLabels,
+  },
+};
+
+// Regression: when `labels` is emitted as an array by docgen (e.g. Svelte),
+// options whose names match Array.prototype methods previously showed
+// `function reverse() { [native code] }` instead of the option's string value.
+// With the fix, each option must display as String(item) — 'reverse', 'map', 'filter'.
+export const ArrayLabelsIsArray: Story = {
+  name: 'Array Labels (docgen array — prototype-collision fix)',
+  args: {
+    value: [prototypeCollisionOptions[0]],
+    argType: { options: prototypeCollisionOptions },
+    labels: ['Reverse', 'Map', 'Filter'] as any,
+  },
+  argTypes: {
+    value: {
+      control: { type: 'check' },
+      options: prototypeCollisionOptions,
+    },
+  },
+};
+
+export const ArrayInlineLabelsIsArray: Story = {
+  name: 'Array Inline Labels (docgen array — prototype-collision fix)',
+  args: {
+    type: 'inline-check',
+    value: [prototypeCollisionOptions[0], prototypeCollisionOptions[1]],
+    argType: { options: prototypeCollisionOptions },
+    labels: ['Reverse', 'Map', 'Filter'] as any,
+  },
+  argTypes: {
+    value: {
+      control: { type: 'inline-check' },
+      options: prototypeCollisionOptions,
+    },
+  },
+};
+
 export const ArrayUndefined: Story = {
   args: {
     value: undefined,

code/addons/docs/src/blocks/controls/options/Options.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import { normalizeOptions } from './Options';
+
+describe('normalizeOptions', () => {
+  it('uses String(item) as label when no labels map is provided', () => {
+    expect(normalizeOptions(['a', 'b', 'c'])).toEqual({ a: 'a', b: 'b', c: 'c' });
+  });
+
+  it('uses labels map when provided with matching keys', () => {
+    const labels = { a: 'Option A', b: 'Option B' };
+    expect(normalizeOptions(['a', 'b'], labels)).toEqual({
+      'Option A': 'a',
+      'Option B': 'b',
+    });
+  });
+
+  it('falls back to String(item) for items missing from labels map', () => {
+    const labels = { a: 'Option A' };
+    expect(normalizeOptions(['a', 'b'], labels)).toEqual({
+      'Option A': 'a',
+      b: 'b',
+    });
+  });
+
+  it('falls back to String(item) when a label key exists but its value is undefined', () => {
+    // Regression guard: { reverse: undefined } previously printed "undefined" as the label
+    // because Object.hasOwn found the key before we checked the value type.
+    const labels = { Bat: undefined as any, Cat: 'Catwoman' };
+    expect(normalizeOptions(['Bat', 'Cat'], labels)).toEqual({
+      Bat: 'Bat',
+      Catwoman: 'Cat',
+    });
+  });
+
+  it('does not resolve Array.prototype methods when labels is an array (issue #30142)', () => {
+    // When Svelte docgen incorrectly passes an array as `labels`, items whose name
+    // matches an Array prototype method (e.g. 'reverse') must NOT resolve to the
+    // native function — they should fall back to String(item).
+    const labelsAsArray: any = ['first', 'second', 'third'];
+    const options = ['reverse', 'map', 'filter'];
+    const result = normalizeOptions(options, labelsAsArray);
+    expect(result).toEqual({ reverse: 'reverse', map: 'map', filter: 'filter' });
+    expect(Object.keys(result as object)).not.toContain('function reverse() { [native code] }');
+  });
+
+  it('returns the options object unchanged when options is not an array', () => {
+    const obj = { 'Option A': 'a', 'Option B': 'b' };
+    expect(normalizeOptions(obj as any)).toBe(obj);
+  });
+});