Release: Prerelease 11.0.0-alpha.1

.agents/guidelines/architecture.md

@@ -0,0 +1,108 @@
+# Architecture
+
+This document is canonical for repo structure and architecture: renderer vs builder vs framework, the core package layout, key flows, open services and toolsets, and agent-facing skills. `AGENTS.md` owns the pointer to this file and the kickstart commands.
+
+## Repository Structure
+
+```text
+storybook/
+├── .github/                      # GitHub configs and workflows
+├── .nx/                          # NX workflow state
+├── code/                         # Main codebase
+│   ├── .storybook/               # Internal Storybook UI config
+│   ├── core/                     # Core package published as "storybook"
+│   ├── addons/                   # Core addons
+│   ├── builders/                 # Builder integrations
+│   ├── renderers/                # Renderer integrations
+│   ├── frameworks/               # Framework integrations
+│   ├── lib/                      # Supporting libraries
+│   ├── presets/                  # Webpack-oriented presets
+│   └── sandbox/                  # Internal build artifacts
+├── scripts/                      # Build and development scripts
+├── docs/                         # Documentation
+├── test-storybooks/              # Test repos
+└── ../storybook-sandboxes/       # Generated sandboxes outside repo
+```
+
+## Renderer vs builder vs framework
+
+| Concept   | Role                                  | Example                   |
+| --------- | ------------------------------------- | ------------------------- |
+| Renderer  | Mounts UI framework to the DOM        | `@storybook/react`        |
+| Builder   | Bundles and serves Storybook          | `@storybook/builder-vite` |
+| Framework | Renderer + builder + framework config | `@storybook/react-vite`   |
+
+## Core package
+
+The main package is `code/core/src/`. The most important areas are:
+
+- `core-server/` for dev server, static build, and presets
+- `manager/` and `manager-api/` for the Storybook UI
+- `preview/` and `preview-api/` for story rendering
+- `channels/` for manager <-> preview communication
+- `csf-tools/` for AST-based story indexing
+- `common/` for shared Node.js utilities
+- `test/` and `instrumenter/` for testing support
+
+Public exports include:
+
+- `storybook/actions`
+- `storybook/preview-api`
+- `storybook/manager-api`
+- `storybook/theming`
+- `storybook/test`
+
+Internal exports include:
+
+- `storybook/internal/core-server`
+- `storybook/internal/csf-tools`
+- `storybook/internal/common`
+- `storybook/internal/channels`
+- `storybook/internal/tools` — Node SDK for `storybook tools` (`createTools`)
+
+## Key flow
+
+- `.storybook/main.ts` is loaded at startup
+- `.storybook/preview.ts` is bundled into preview (TSX for React-based frameworks)
+- `.storybook/manager.ts` is bundled into manager
+- `*.stories.*` files are indexed by AST before runtime
+- Story selection loads the module, prepares the story, and renders it
+
+AST indexing keeps the sidebar fast and prevents one broken story file from breaking the whole UI.
+
+For AST mutations, use `CsfFile.objects()` for stories and `ConfigFile` directly for preview or main
+configuration. Both expose `get`, `getValue`, `set`, `transform`, `remove`, `rename`, `move`, and `group`, with automatic
+empty-parent cleanup. `set` accepts AST expressions and plain values, including nested arrays and objects.
+`getValue` reads plain values statically; unresolved expressions produce diagnostics without executing code.
+Use the file's `changed` and `mutationDiagnostics` to decide whether to write
+the result. Named variable and function exports in config files share one logical root for these operations.
+Use `ConfigFile.callArguments()` for object arguments to imported method calls such as
+`addons.setConfig(...)`. Use `group(path, names)` when nesting sibling fields must preserve expression
+evaluation order. Keep AST discovery, mutation, and safety checks in `csf-tools`; automigrations declare
+the fields to change and provide migration-specific error guidance.
+
+## Open services and toolsets
+
+- Open services own internal state, synchronization, queries, commands, and loading. Toolsets expose
+  capabilities to agents through MCP and the `storybook tools` CLI.
+- Definitions live under `code/core/src/shared/open-service/`; addons may own and register their own
+  toolsets, as addon-vitest does for `test`.
+- Register services and toolsets from the same `services` preset hook and behind the same feature
+  gate. Missing or duplicate registrations fail loudly.
+- The tools CLI consumes `storybook/internal/tools` (`createTools`). Default mode is
+  attach-preferred (`auto`): join a running instance as a delegated leaf, or load locally on gate
+  failure. `--attach` requires attachment; `--no-attach` forces local. When several running
+  instances match the project, attach picks the invoking agent's most recently started one and
+  warns on stderr; `-p, --port` targets a specific instance. Local `createTools` never
+  `chdir`s: a foreign `cwd` starts a project-local child host.
+- Read `code/core/src/shared/open-service/README.md` before changing the contract, adapters,
+  registration, docs access, or transport rendering. Read `code/core/src/cli/tools/README.md` and
+  `code/core/src/cli/tools/architecture.md` before changing attachment, the SDK, or the tools CLI.
+
+## Agent-facing skills
+
+- `storybook skills` serves the `stories`, `write-story`, and `setup` documents as Markdown.
+- Pure content lives in `code/core/src/cli/skills/content/` and is exported through
+  `storybook/internal/skills`; addon-mcp consumes the same builders.
+- Keep `cli/skills/**` independent of `cli/ai/**`, and keep `cli/skills/content/**` independent of
+  `core-server`. Lint rules enforce both boundaries.

.agents/guidelines/nx-and-yarn-task.md

@@ -0,0 +1,44 @@
+# NX and `yarn task`
+
+This document is canonical for NX and the `yarn task` runner: caching, task dependencies, sandbox and CI-parity flags, and the environment variable reference. `AGENTS.md` owns the pointer to this file and the common commands.
+
+Use NX when you want better caching and dependency tracking. Prefer these faster defaults first, and only add `-c production` or `--no-link` when you specifically need sandbox parity or CI-like behavior.
+
+```bash
+# Compile all packages
+yarn task compile
+yarn nx run-many -t compile
+
+# Check all packages
+yarn task check
+yarn nx run-many -t check
+
+# Run E2E tests for a template
+yarn task e2e-tests-dev --template react-vite/default-ts --start-from auto
+yarn nx e2e-tests-dev react-vite/default-ts -c production
+
+# Jump to a later step
+yarn task e2e-tests-dev --start-from e2e-tests --template react-vite/default-ts
+yarn nx e2e-tests-dev -c production --exclude-task-dependencies
+```
+
+Key points:
+
+- `-c production` is required for sandbox-related NX commands and CI-parity runs
+- `react-vite/default-ts` is the default sandbox template
+- `--no-link` is opt-in, not the default
+- NX handles task dependencies via `nx.json`
+- NX target commands use Nx project names (from `project.json` / Nx graph), not `package.json` names
+- Example: `yarn nx compile core` (project `core` is published as package `storybook`)
+- NX Cloud remote-cache auth failures (e.g. HTTP 401 "insufficient access") degrade to the local cache, so they are expected on local runs where `NX_CLOUD_ACCESS_TOKEN` is unset. CI always sets that token, so a 401 there means an invalid or expired token and should be investigated rather than ignored. A read-only token enables cache reads but cannot store artifacts, so the "wasn't able to store" warning is still expected with one
+
+## 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                            |
+| `FIX_ON_COMMIT`               | Force autofix for fmt & lint in pre-commit hook |
+| `NX_CLOUD_ACCESS_TOKEN`       | Authenticate the NX Cloud remote cache          |

.agents/guidelines/sandboxes.md

@@ -0,0 +1,29 @@
+# Sandbox Notes
+
+This document is canonical for sandbox generation and use: where sandboxes live, the sandbox command shape, and the common templates. `AGENTS.md` owns the pointer to this file and the sandbox-failure fallback.
+
+Sandboxes are generated outside the repository at `../storybook-sandboxes/` by default.
+
+- `STORYBOOK_SANDBOX_ROOT=./sandbox` forces local output, but is usually not preferred
+- `./sandbox` inside the repo mainly exists for NX outputs, not CI sandboxes
+- If sandbox generation fails, fall back to `cd code && yarn storybook:ui`
+
+Generate and use a sandbox with the same `sandbox` command shape used elsewhere in this file:
+
+```bash
+yarn task sandbox --template react-vite/default-ts --start-from auto
+# Same sandbox step via NX
+yarn nx sandbox react-vite/default-ts -c production
+cd ../storybook-sandboxes/react-vite-default-ts
+yarn install
+yarn storybook
+```
+
+Common templates:
+
+- `react-vite/default-ts`
+- `react-webpack/default-ts`
+- `angular-cli/default-ts`
+- `svelte-vite/default-ts`
+- `vue3-vite/default-ts`
+- `nextjs/default-ts`

.agents/guidelines/testing.md

@@ -0,0 +1,49 @@
+# Testing Expectations
+
+This document is canonical for detailed testing practice: watch-mode commands, component and unit test guidance, `memfs` filesystem tests, and global stubbing rules. `AGENTS.md` owns the pointer to this file and the core testing expectations.
+
+Watch-mode commands:
+
+```bash
+yarn test:watch
+yarn storybook:vitest
+```
+
+When writing tests for components:
+
+- Add or update `<Component>.stories.tsx` with stories covering each behavior; use `play` functions with `expect`, `userEvent`, `within` from `storybook/test`
+- Mock external context (e.g. `ManagerContext.Provider`) inside story decorators or `beforeEach`
+- Run `vitest --config code/vitest.config.storybook.ts <story-file>` to verify play assertions
+
+When writing unit tests (utilities, hooks, non-React modules):
+
+- Export functions that need direct tests
+- Test real behavior, not just syntax patterns
+- Use coverage when useful: `yarn vitest run --coverage <test-file>`
+- Mock external dependencies like file system access and loggers
+- Use Node's path.resolve to wrap expected FS paths when writing path-related tests, so they work on Windows
+
+## 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.
+
+## Globals in tests: never assign `globalThis.*` directly
+
+> [!IMPORTANT]
+> Under no circumstances may a test mutate a global by assigning it directly (e.g. `globalThis.FEATURES = {...}`, `globalThis.window = ...`, `global.fetch = ...`). Direct assignment leaks across tests and files — Vitest does not restore it — so it silently changes behavior in unrelated tests and creates order-dependent flakiness.
+
+Use Vitest's global stubbing instead, which is tracked and restorable:
+
+- Set a global with `vi.stubGlobal('FEATURES', { experimentalDocgenServer: true })`.
+- Restore in `afterEach(() => vi.unstubAllGlobals())` (or enable `unstubGlobals: true` in the Vitest config so it resets before each test automatically).
+- For a value used by every test in a file, stub it in `beforeEach` and unstub in `afterEach`; for a one-off override, call `vi.stubGlobal` inside that single test.
+- Never capture-and-restore by hand (`const original = globalThis.X; ... globalThis.X = original`); `vi.stubGlobal` + `vi.unstubAllGlobals()` does this correctly, including deleting keys that did not previously exist.
+
+This applies to all ambient globals, not just `FEATURES` (e.g. `window`, `document`, `navigator`, `fetch`, `IS_REACT_ACT_ENVIRONMENT`).

.agents/skills/canary/SKILL.md

@@ -2,6 +2,8 @@
 name: canary
 description: Finds or publishes a pkg.pr.new canary release for a Storybook branch. Use when the user wants the canary package specifier for a branch or needs to trigger the canary workflow manually.
 allowed-tools: Bash
+metadata:
+  internal: true
 ---
 
 # Find Or Publish Canary Release

.agents/skills/docs-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: docs-review
 description: Review, improve, rewrite, author, or plan Storybook documentation in /docs. Use this when asked to review docs, improve a page, rewrite documentation, draft new docs, or advise on docs strategy.
+metadata:
+  internal: true
 ---
 
 # Documentation Review

.agents/skills/fix-linting-types-on-pr/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: fix-linting-types-on-pr
 description: Checks out a PR (including fork PRs), fixes all linting and TypeScript errors, then pushes the changes back. Use when asked to fix lint, types, or TS errors on a PR.
+metadata:
+  internal: true
 ---
 
 # Fix Linting and TypeScript Issues on a PR

.agents/skills/github-qa-labels/SKILL.md

@@ -2,6 +2,8 @@
 name: github-qa-labels
 description: Label GitHub issues and PRs found during QA testing. Use when organizing QA findings with proper labels.
 allowed-tools: Bash
+metadata:
+  internal: true
 ---
 
 # GitHub QA Labels

.agents/skills/handle-pr-comments/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: handle-pr-comments
 description: Triage and resolve GitHub PR review comments one by one, interactively. Use when the user asks to handle, address, respond to, or resolve PR review comments, or mentions reviewer feedback on a pull request.
+metadata:
+  internal: true
 ---
 
 # Handle PR Comments
@@ -19,4 +21,4 @@ Evaluate review comments on the PR (from the current branch, or a PR number/URL
 
 - Handle real-user comments before addressing AI agents' (Copilot, CodeRabbit).
 - Group duplicate comments; when the same/similar issue is mentioned multiple times, handle them all at once.
-- Make a separate commit for each change.
+- Make a separate commit for each change.

.agents/skills/minor-release/SKILL.md

@@ -2,6 +2,8 @@
 name: minor-release
 description: Write the changelog entry for a new minor or major Storybook release. Use when preparing a CHANGELOG.md entry for a X.Y.0 version.
 allowed-tools: Bash, Read, Write, Edit
+metadata:
+  internal: true
 ---
 
 # Write Minor/Major Release Changelog

.agents/skills/open-pr/SKILL.md

@@ -2,6 +2,8 @@
 name: open-pr
 description: Opens a pull request from the current branch using the PR template. Use when the user asks to open a PR, create a pull request, or invokes /open-pr.
 allowed-tools: Bash, Read, AskQuestion
+metadata:
+  internal: true
 ---
 
 # Open Pull Request

.agents/skills/pr/SKILL.md

@@ -2,6 +2,8 @@
 name: pr
 description: Creates a pull request following Storybook conventions. Use when creating PRs, opening pull requests, or submitting changes for review.
 allowed-tools: Bash, Read
+metadata:
+  internal: true
 ---
 
 # Create Pull Request

.agents/skills/principle-encode-lessons-in-structure/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: principle-encode-lessons-in-structure
 description: "Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text."
+metadata:
+  internal: true
 ---
 
 # Encode Lessons in Structure

.agents/skills/rebuild-restart-storybook/SKILL.md

@@ -2,6 +2,8 @@
 name: rebuild-restart-storybook
 description: Rebuild and restart the internal Storybook UI after changes to internal Storybook code (core, addons, frameworks, renderers, libs, etc.), then optionally display a UI review. Use after editing any package in the Storybook monorepo's code/ directory, or when the user asks to rebuild and/or restart Storybook.
 allowed-tools: Bash, Read
+metadata:
+  internal: true
 ---
 
 # Rebuild and Restart Storybook

.agents/skills/storybook-startup-benchmark/SKILL.md

@@ -2,6 +2,8 @@
 name: storybook-startup-benchmark
 description: Measure Storybook startup time from spawning `storybook dev` until the first story renders in the browser. Use when the user asks about Storybook boot time, server-ready timing, first story render timing, startup regressions, benchmarking with repeat runs, or comparing Storybook versions or feature flags.
 allowed-tools: Bash, Read
+metadata:
+  internal: true
 ---
 
 # Storybook Startup Benchmark

.agents/skills/storybook-upgrade/SKILL.md

@@ -2,6 +2,8 @@
 name: storybook-upgrade
 description: Upgrade Storybook to a specific version (canary or release). Use this when upgrading Storybook packages in an external app, reproduction, or test project.
 allowed-tools: Bash
+metadata:
+  internal: true
 ---
 
 # Storybook Upgrade

.agents/skills/update-pr-description/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: update-pr-description
 description: Evaluate a PR's title and description against its actual implementation, then iteratively suggest and apply updates. Use when the user asks to check, fix, or update a PR title or description.
+metadata:
+  internal: true
 ---
 
 # Update PR Description
@@ -23,4 +25,4 @@ description: Evaluate a PR's title and description against its actual implementa
 - Don't rewrite a description that's already accurate.
 - Update the state of checkboxes where appropriate.
 - Remove section placeholders/reminders when filling out a section.
-- Do not remove the canary release section.
+- Do not remove the canary release section.