Release: Prerelease 10.5.0-alpha.2

AGENTS.md

@@ -288,6 +288,18 @@ Avoid `console.log`, `console.warn`, and `console.error` unless the file is isol
 
 These usually start long-running development servers and are the wrong default for agents.
 
+## Code Authoring Principles
+
+These are recurring failure modes in agent-authored changes to this repo. Apply them when writing or reviewing code, not just when asked.
+
+- **Comments are maintenance docs, not an investigation transcript.** Explain *why* for the next maintainer. Do not commit internal ticket / acceptance-criteria codes (`AC-X2`, `Probe B`, `R6`), the narrative of how you figured something out, "verified byte-identical" provenance prose, or cross-file line references (`L125→L131`) — they are noise and they rot. One or two sentences of rationale beats a paragraph of evidence.
+- **Verify environment assumptions empirically before encoding them.** If a design rests on "the bundler strips X" or "this metadata is empty here", prove it with a throwaway probe before building on it (and before writing it into a comment as fact). A 10-line experiment is cheaper than a wrong architecture.
+- **Encode assumptions with static checks first.** If an assumption is expected to always hold, prefer making it impossible via TypeScript types and existing lint rules. When static checks are not practical, add a cheap runtime assertion close to the boundary so violations fail loudly at the source.
+- **Avoid redundant tests already covered elsewhere.** Do not add tests for code patterns already guaranteed by TypeScript or linting, and do not duplicate coverage that already exists in Storybook `play` functions or Playwright tests.
+- **Test contracts (including side effects), not private implementation details.** It is valid to assert side effects when they are part of the public contract. Avoid assertions about internals that are not part of an exported contract, user-visible DOM output, or externally observable behavior.
+- **Bias toward broader coverage for security and migrations.** For security-sensitive code paths and legacy data migration logic, prefer handling more edge cases and documenting evidence for the chosen safeguards. Migration compatibility code should be explicitly version-scoped so it can be removed once the support window ends.
+- **Prefer deletion and simplicity over speculative generality.** No abstraction, fallback, or "flexibility" for a consumer or scenario that does not exist in this codebase today. If a change adds many lines, check whether the right change removes them.
+
 ## Maintenance Rules For Agents
 
 - Use this file as the canonical instruction source

CHANGELOG.prerelease.md

@@ -1,3 +1,23 @@
+## 10.5.0-alpha.2
+
+- A11y-Addon: Preserve disabled a11y rules with runOnly - [#34649](https://github.com/storybookjs/storybook/pull/34649), thanks @cyphercodes!
+- A11y: Fix MDX heading anchors not keyboard accessible - [#34368](https://github.com/storybookjs/storybook/pull/34368), thanks @TheSeydiCharyyev!
+- Add an optional TypeScript peer to react-vite - [#34627](https://github.com/storybookjs/storybook/pull/34627), thanks @wojtekmaj!
+- Addon-Docs: Resolve CSF4 module exports without a default export - [#34834](https://github.com/storybookjs/storybook/pull/34834), thanks @TheSeydiCharyyev!
+- Angular: Detect model() signal outputs (type inference + compodoc autodocs + runtime binding) - [#34833](https://github.com/storybookjs/storybook/pull/34833), thanks @valentinpalkovic!
+- Build: Upgrade type-fest to latest version 5.6.0 - [#34791](https://github.com/storybookjs/storybook/pull/34791), thanks @tobiasdiez!
+- CLI: Support `peerDependencies` in framework detection for component libraries - [#34516](https://github.com/storybookjs/storybook/pull/34516), thanks @zhyd1997!
+- CSF-Next: Add tags type support for  - [#34819](https://github.com/storybookjs/storybook/pull/34819), thanks @unional!
+- Core: Add runtime instance registry - [#34863](https://github.com/storybookjs/storybook/pull/34863), thanks @kasperpeulen!
+- Core: Categorize UniversalStore follower timeout error - [#34592](https://github.com/storybookjs/storybook/pull/34592), thanks @justismailmemon!
+- Docs: Add ariaLabel support to ActionItem interface - [#34749](https://github.com/storybookjs/storybook/pull/34749), thanks @TheSeydiCharyyev!
+- Docs: Scope control input ids to each <Controls /> block instance - [#34793](https://github.com/storybookjs/storybook/pull/34793), thanks @TheSeydiCharyyev!
+- Docs: Support explicit id prop on <Meta> for standalone MDX - [#34808](https://github.com/storybookjs/storybook/pull/34808), thanks @TheSeydiCharyyev!
+- Maintenance: Replace `resolve` and `resolve.exports` with `oxc-resolver` - [#34692](https://github.com/storybookjs/storybook/pull/34692), thanks @valentinpalkovic!
+- Next.js-Vite: Bump vite-plugin-storybook-nextjs to ^3.3.0 - [#34838](https://github.com/storybookjs/storybook/pull/34838), thanks @yatishgoel!
+- Vitest: Reset playwright cursor position to avoid hover bug - [#34765](https://github.com/storybookjs/storybook/pull/34765), thanks @Sidnioulz!
+- Vue3: Specify a specific version for non-dev dependency - [#34794](https://github.com/storybookjs/storybook/pull/34794), thanks @ScopeyNZ!
+
 ## 10.5.0-alpha.1
 
 - Angular: Fix custom paths for stats.json on angular - [#34551](https://github.com/storybookjs/storybook/pull/34551), thanks @mrginglymus!

code/addons/a11y/src/a11yRunner.test.ts

@@ -1,21 +1,62 @@
+import type { AxeResults } from 'axe-core';
 import type { Mock } from 'vitest';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { addons } from 'storybook/preview-api';
 
 import { EVENTS } from './constants.ts';
 
+const { axeMock, documentMock } = vi.hoisted(() => {
+  const documentMock = {
+    body: {},
+    getElementById: vi.fn(),
+    location: { pathname: '/iframe.html' },
+  };
+
+  return {
+    documentMock,
+    axeMock: {
+      reset: vi.fn(),
+      configure: vi.fn(),
+      run: vi.fn(),
+    },
+  };
+});
+
+vi.mock('@storybook/global', () => ({
+  global: {
+    document: documentMock,
+  },
+}));
+
+vi.mock('axe-core', () => ({
+  default: axeMock,
+}));
+
 vi.mock('storybook/preview-api');
 const mockedAddons = vi.mocked(addons);
 
+const axeResults = {
+  violations: [],
+  passes: [],
+  incomplete: [],
+  inapplicable: [],
+} as Partial<AxeResults> as AxeResults;
+
 describe('a11yRunner', () => {
   let mockChannel: { on: Mock; emit?: Mock };
 
   beforeEach(() => {
-    mockedAddons.getChannel.mockReset();
+    vi.resetModules();
+    vi.clearAllMocks();
+
+    documentMock.getElementById.mockReturnValue(null);
+    axeMock.run.mockResolvedValue(axeResults);
 
     mockChannel = { on: vi.fn(), emit: vi.fn() };
-    mockedAddons.getChannel.mockReturnValue(mockChannel as any);
+    mockedAddons.getChannel.mockReturnValue(
+      mockChannel as unknown as ReturnType<typeof addons.getChannel>
+    );
   });
 
   it('should listen to events', async () => {
@@ -24,4 +65,67 @@ describe('a11yRunner', () => {
     expect(mockedAddons.getChannel).toHaveBeenCalled();
     expect(mockChannel.on).toHaveBeenCalledWith(EVENTS.MANUAL, expect.any(Function));
   });
+
+  it('passes disabled configured rules to axe.run when runOnly is present', async () => {
+    const { run } = await import('./a11yRunner.ts');
+    const input = {
+      config: {
+        rules: [
+          { id: 'target-size', enabled: false },
+          { id: 'color-contrast', enabled: true },
+        ],
+      },
+      options: {
+        runOnly: ['wcag2a'],
+        rules: {
+          'button-name': { enabled: false },
+        },
+      },
+    };
+
+    await run(input, 'example-story');
+
+    expect(axeMock.configure).toHaveBeenCalledWith({
+      rules: [
+        { id: 'region', enabled: false },
+        { id: 'target-size', enabled: false },
+        { id: 'color-contrast', enabled: true },
+      ],
+    });
+    expect(axeMock.run).toHaveBeenCalledWith(expect.any(Object), {
+      runOnly: ['wcag2a'],
+      rules: {
+        region: { enabled: false },
+        'target-size': { enabled: false },
+        'button-name': { enabled: false },
+      },
+    });
+    expect(axeMock.run.mock.calls[0][1]).not.toBe(input.options);
+    expect(input.options).toEqual({
+      runOnly: ['wcag2a'],
+      rules: {
+        'button-name': { enabled: false },
+      },
+    });
+  });
+
+  it('respects configured rule overrides when collecting disabled rules', async () => {
+    const { run } = await import('./a11yRunner.ts');
+
+    await run(
+      {
+        config: {
+          rules: [{ id: 'region', enabled: true }],
+        },
+        options: {
+          runOnly: ['wcag2a'],
+        },
+      },
+      'example-story'
+    );
+
+    expect(axeMock.run).toHaveBeenCalledWith(expect.any(Object), {
+      runOnly: ['wcag2a'],
+    });
+  });
 });

code/addons/a11y/src/a11yRunner.ts

@@ -2,7 +2,7 @@ import { ElementA11yParameterError } from 'storybook/internal/preview-errors';
 
 import { global } from '@storybook/global';
 
-import type { AxeResults, ContextProp, ContextSpec } from 'axe-core';
+import type { AxeResults, ContextProp, ContextSpec, RunOptions, Spec } from 'axe-core';
 import { addons, waitForAnimations } from 'storybook/preview-api';
 
 import { withLinkPaths } from './a11yRunnerUtils.ts';
@@ -21,6 +21,47 @@ const DISABLED_RULES = [
   'region',
 ] as const;
 
+const getDisabledRules = (rules: Spec['rules'] = []) => {
+  const disabledRules: NonNullable<RunOptions['rules']> = {};
+
+  // Rules are applied in order, so a later entry overrides an earlier one for the same id.
+  for (const { id, enabled } of rules) {
+    if (!id || typeof enabled !== 'boolean') {
+      continue;
+    }
+
+    if (enabled) {
+      delete disabledRules[id];
+    } else {
+      disabledRules[id] = { enabled: false };
+    }
+  }
+
+  return disabledRules;
+};
+
+const mergeDisabledRulesIntoRunOptions = (options: RunOptions, config: Spec): RunOptions => {
+  // axe.run({ runOnly }) can re-enable tagged rules, so mirror configured disables into
+  // the same run options object without mutating the user's parameters.
+  if (!options.runOnly) {
+    return options;
+  }
+
+  const disabledRules = getDisabledRules(config.rules);
+
+  if (Object.keys(disabledRules).length === 0) {
+    return options;
+  }
+
+  return {
+    ...options,
+    rules: {
+      ...disabledRules,
+      ...options.rules,
+    },
+  };
+};
+
 // A simple queue to run axe-core in sequence
 // This is necessary because axe-core is not designed to run in parallel
 const queue: (() => Promise<void>)[] = [];
@@ -92,6 +133,8 @@ export const run = async (input: A11yParameters = DEFAULT_PARAMETERS, storyId: s
 
   axe.configure(configWithDefault);
 
+  const optionsWithDisabledRules = mergeDisabledRulesIntoRunOptions(options, configWithDefault);
+
   return new Promise<AxeResults>((resolve, reject) => {
     const highlightsRoot = document?.getElementById('storybook-highlights-root');
     if (highlightsRoot) {
@@ -100,7 +143,7 @@ export const run = async (input: A11yParameters = DEFAULT_PARAMETERS, storyId: s
 
     const task = async () => {
       try {
-        const result = await axe.run(context, options);
+        const result = await axe.run(context, optionsWithDisabledRules);
         const resultWithLinks = withLinkPaths(result, storyId);
         resolve(resultWithLinks);
       } catch (error) {

code/core/package.json

@@ -380,7 +380,8 @@
     "tinyspy": "^3.0.2",
     "ts-dedent": "^2.0.0",
     "tsconfig-paths": "^4.2.0",
-    "type-fest": "^4.18.1",
+    "type-fest": "^5.6.0",
+    "type-plus": "^8.0.0-beta.8",
     "typescript": "^5.8.3",
     "unique-string": "^3.0.0",
     "use-resize-observer": "^9.1.0",

code/core/src/cli/dev.ts

@@ -49,7 +49,7 @@ export const dev = async (cliOptions: CLIOptions) => {
     configType: 'DEVELOPMENT',
     ignorePreview: !!cliOptions.previewUrl && !cliOptions.forceBuildPreview,
     cache: cache as any,
-    packageJson: packageJson as unknown as PackageJson, // type-fest types are wrong here because we're on an outdated version of the package
+    packageJson: packageJson,
   } as Options;
 
   await withTelemetry(

code/core/src/cli/eslintPlugin.ts

@@ -315,16 +315,15 @@ export async function configureEslintPlugin({
     }
   } else {
     logger.debug('No ESLint config file found, configuring in package.json instead');
-    const { packageJson } = packageManager.primaryPackageJson;
+    const { packageJson, operationDir } = packageManager.primaryPackageJson;
     const existingExtends = normalizeExtends(packageJson.eslintConfig?.extends).filter(Boolean);
 
-    packageManager.writePackageJson({
-      ...packageJson,
-      eslintConfig: {
-        ...packageJson.eslintConfig,
-        extends: [...existingExtends, 'plugin:storybook/recommended'],
-      },
-    });
+    packageJson.eslintConfig = {
+      ...packageJson.eslintConfig,
+      extends: [...existingExtends, 'plugin:storybook/recommended'],
+    };
+
+    packageManager.writePackageJson(packageJson, operationDir);
   }
 }
 

code/core/src/common/js-package-manager/JsPackageManager.ts

@@ -271,12 +271,10 @@ export abstract class JsPackageManager {
 
     // Update cache with the written content
     // Ensure dependencies and devDependencies exist (even if empty) to match PackageJsonWithDepsAndDevDeps type
-    const cachedPackageJson: PackageJsonWithIndent = {
-      ...packageJsonToWrite,
-      dependencies: { ...(packageJsonToWrite.dependencies || {}) },
-      devDependencies: { ...(packageJsonToWrite.devDependencies || {}) },
-      peerDependencies: { ...(packageJsonToWrite.peerDependencies || {}) },
-    };
+    const cachedPackageJson = packageJsonToWrite as PackageJsonWithIndent;
+    cachedPackageJson.dependencies = { ...(packageJsonToWrite.dependencies || {}) };
+    cachedPackageJson.devDependencies = { ...(packageJsonToWrite.devDependencies || {}) };
+    cachedPackageJson.peerDependencies = { ...(packageJsonToWrite.peerDependencies || {}) };
     cachedPackageJson[indentSymbol] = indent;
     JsPackageManager.packageJsonCache.set(packageJsonPath, cachedPackageJson);
   }
@@ -612,16 +610,11 @@ export abstract class JsPackageManager {
   public addScripts(scripts: Record<string, string>) {
     const { operationDir, packageJson } = this.#getPrimaryPackageJson();
 
-    this.writePackageJson(
-      {
-        ...packageJson,
-        scripts: {
-          ...packageJson.scripts,
-          ...scripts,
-        },
-      },
-      operationDir
-    );
+    packageJson.scripts = {
+      ...packageJson.scripts,
+      ...scripts,
+    };
+    this.writePackageJson(packageJson, operationDir);
   }
 
   public addPackageResolutions(versions: Record<string, string>) {

code/core/src/core-server/build-dev.ts

@@ -35,6 +35,11 @@ import { getManagerBuilder, getPreviewBuilder } from './utils/get-builders.ts';
 import { getServerChannel } from './utils/get-server-channel.ts';
 import { outputStartupInformation } from './utils/output-startup-information.ts';
 import { outputStats } from './utils/output-stats.ts';
+import {
+  getMcpMetadataFromMainConfig,
+  type RuntimeInstanceRecord,
+  writeStorybookRuntimeInstanceRecord,
+} from './utils/runtime-instance-registry.ts';
 import { getServerAddresses, getServerChannelUrl, getServerPort } from './utils/server-address.ts';
 import { getServer } from './utils/server-init.ts';
 import { stripCommentsAndStrings } from './utils/strip-comments-and-strings.ts';
@@ -303,6 +308,18 @@ export async function buildDevStandalone(
     storybookDevServer(fullOptions, server)
   );
 
+  const mcp: RuntimeInstanceRecord['mcp'] = getMcpMetadataFromMainConfig(config);
+
+  await writeStorybookRuntimeInstanceRecord({
+    address: localAddress,
+    mcp,
+    port,
+    storybookVersion,
+  }).catch((error: unknown) => {
+    logger.warn('Storybook failed to write its runtime instance registry record.');
+    logger.debug(error instanceof Error ? (error.stack ?? error.message) : String(error));
+  });
+
   const previewTotalTime = previewResult?.totalTime;
   const managerTotalTime = managerResult?.totalTime;
   const previewStats = previewResult?.stats;