Merge branch 'main' into fix/501-svelte-adapter-exports

Author: kolaworld

.changeset/calm-buses-connect.md

@@ -146,26 +146,26 @@ The devtools shell is a Solid.js application that renders the entire devtools UI
 - **`setConfig(config)`** -- Updates configuration and plugins at runtime. Plugins are reactive: adding or removing them updates the tab bar immediately.
 
 The shell renders:
-- A **trigger button** (the floating devtools toggle, customizable or replaceable)
+- A **trigger button** (the floating rainbow palm mark, customizable or replaceable)
 - A **resizable Workbench panel** (docked to the top or bottom of the viewport, resizable via pointer or keyboard)
 - A compact **36px TanStack Devtools header** with Plugins, Marketplace, SEO, and Settings destinations. The palm emblem is inline SVG, so it stays sharp and takes its colour from the theme.
 - A fixed-height **44px secondary strip** for plugin and SEO navigation. It scrolls horizontally when space is limited, and a pull tab on its bottom edge folds it away behind the header. Folding changes nothing else — the panel keeps its height and the destination content keeps running — so the tab is rendered only on the destinations that have a strip.
 - A separate **Marketplace** header tab that does not disturb mounted plugin panes
 - A **settings panel** for theme, hotkeys, position, and other preferences
 - Up to three simultaneous **plugin mount frames**, divided into equal widths by static separators
 
-Settings and UI state (panel size, position, active tab, theme) are persisted in `localStorage` so they survive page reloads.
+Settings and UI state (panel size, position, active tab, theme, and whether the secondary strip is folded) are persisted in `localStorage` so they survive page reloads.
 
 The core shell owns the Workbench header, navigation, mount-frame geometry, separators, and surrounding light/dark surfaces. Each external plugin owns everything inside its mount target; core styling deliberately does not reach into plugin descendants. Detaching the Workbench uses a fixed `100vh` Picture-in-Picture layout and restores the stored docked height when reattached.
 
 #### Workbench surfaces and gutters
 
 Two rules keep the shell reading as one surface:
 
-- **Chrome versus canvas.** The header and every secondary strip paint the brand surface (cream in light mode, near-black in dark mode) and close with a translucent ink hairline. Destination content and plugin mount frames paint the workspace surface. A plugin pane can paint any colour it likes, so the separator between panes uses a mid-tone border that stays visible against both.
+- **Chrome versus canvas.** The header and every secondary strip paint the brand surface (cream in light mode, near-black in dark mode) and close with a translucent ink hairline. Destination content and plugin mount frames paint the workspace surface. A plugin pane can paint any colour it likes. The resize gutter between panes is invisible at rest and paints a line on hover or keyboard focus.
 - **One gutter.** `WORKBENCH_GUTTER` (16px, or `WORKBENCH_GUTTER_NARROW` at 12px below 430px) is the single inline gutter. The header, the strips, and each destination's content all start there, so the left edge is one column instead of three. `MainPanel withPadding` uses the same value.
 
-Colour comes from the semantic theme only. Raw hex values in core-owned source are rejected by `tests/semantic-color-usage.test.ts` unless they carry a narrow, path-scoped `semantic-color-exempt` marker — currently only third-party network marks and the source-inspector highlight alpha. Status colours (success, warning, error, info) mark real state; identity accents do not compete with them, so a card that is both featured and active keeps the neutral outline and lets its badge say which it is.
+Colour comes from the semantic theme only. Raw hex values in core-owned source are rejected by `tests/semantic-color-usage.test.ts` unless they carry a narrow, path-scoped `semantic-color-exempt` marker. The current exemptions are third-party network marks, the source-inspector highlight alpha, and the trigger rainbow mark. Status colours (success, warning, error, info) mark real state; identity accents do not compete with them, so a card that is both featured and active keeps the neutral outline and lets its badge say which it is.
 
 ### @tanstack/devtools-ui -- Component Library
 
@@ -190,15 +190,17 @@ This client is a singleton (`devtoolsEventClient`) used by both the core shell a
 Each framework adapter is a thin wrapper that bridges its framework's component model to the core Solid.js shell. The pattern is the same across all adapters:
 
 1. **Creates a `TanStackDevtoolsCore` instance** with the user's plugins and config.
-2. **Mounts it to a DOM element** using the framework's lifecycle hooks (`useEffect` in React, `onMounted` in Vue, `onMount` in Solid).
-3. **Converts framework-specific plugin definitions** into the core's DOM-based `render(el, theme)` interface. Each adapter defines its own plugin type (e.g. `TanStackDevtoolsReactPlugin`) that accepts framework-native components, then wraps them in a `render` callback that the core calls with a target DOM element and the current theme.
-4. **Uses the framework's portal/teleport mechanism** to render plugin components into the core's DOM containers:
+2. **Mounts it to a DOM element** using the framework's lifecycle APIs, such as `useEffect` in React, `onMounted` in Vue, `$effect` in Svelte, and `onMount` in Solid.
+3. **Converts framework-specific plugin definitions** into the core's DOM-based `render(el, props)` interface. Each adapter defines its own plugin type (e.g. `TanStackDevtoolsReactPlugin`) that accepts framework-native components, then wraps them in a `render` callback that the core calls with a target DOM element and `{ theme, devtoolsOpen }`.
+4. **Uses the framework's rendering API** to render plugin components into the core's DOM containers:
    - **React** -- `createPortal()` from `react-dom`
    - **Vue** -- `<Teleport :to="'#' + plugin.id" />`
    - **Solid** -- `<Portal mount={el} />`
    - **Preact** -- Same portal pattern as React
+   - **Svelte** -- `mount(component, { target: el, props })`
+   - **Angular** -- `createComponent()` with the container's environment injector
 
-The key insight: the core shell is always Solid.js, but your plugins run in **your** framework. A React plugin is a real React component rendered by React's `createPortal` into a DOM element that the Solid.js shell created. A Vue plugin is a real Vue component rendered by Vue's `<Teleport>`. The adapters bridge this gap so you never need to think about Solid.js unless you want to.
+The key insight: the core shell is always Solid.js, but your plugins run in **your** framework. Each adapter receives the same plugin props and renders a native framework component into a DOM element created by the Solid.js shell. The adapters bridge this gap so you never need to think about Solid.js unless you want to.
 
 ### What an adapter does NOT do
 

docs/architecture.md

@@ -35,7 +35,7 @@ The `config` object is mainly focused around user interaction with the devtools
 { position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'middle-left' | 'middle-right' }
 ```
 
-- `triggerMode` - How the trigger is placed. `'fixed'` anchors it to `position`; `'floating'` lets you drag the trigger anywhere on screen (and throw it — it glides with momentum and springs back off the edges). The floating spot is persisted in local storage.
+- `triggerMode` - How the trigger is placed. `'floating'` (the default) lets you drag the trigger anywhere on screen, and throw it: it glides with momentum and springs back off the edges. `'fixed'` anchors it to `position`. The floating spot is persisted in local storage.
 
 ```ts
 { triggerMode: 'fixed' | 'floating' }

docs/configuration.md

@@ -77,7 +77,7 @@ const [MyPlugin, NoOpPlugin] = createReactPlugin({
 
 The returned tuple contains two factory functions:
 
-- **`Plugin()`** -- returns a plugin object with `name`, `id`, `defaultOpen`, and a `render` function that renders your `Component` with the current theme.
+- **`Plugin()`** -- returns a plugin object with `name`, `id`, `defaultOpen`, and a `render` function that renders your `Component` with the current plugin props.
 - **`NoOpPlugin()`** -- returns a plugin object with the same metadata but a `render` function that renders an empty fragment. Use this for production builds where you want to strip devtools out.
 
 A common pattern for tree-shaking:
@@ -90,15 +90,15 @@ const ActivePlugin = process.env.NODE_ENV === 'development' ? MyPlugin : NoOpPlu
 
 ### createReactPanel
 
-For library authors shipping a class-based devtools core that exposes `mount(el, theme)` and `unmount()` methods. This factory wraps that class in a React component that handles mounting into a `div`, passing the theme, and cleaning up on unmount.
+For library authors shipping a class-based devtools core that exposes `mount(el, props)` and `unmount()` methods. This factory wraps that class in a React component that handles mounting into a `div`, passing the complete plugin props, and cleaning up on unmount.
 
 **Signature:**
 
 ```ts
 function createReactPanel<
-  TComponentProps extends DevtoolsPanelProps | undefined,
+  TComponentProps extends DevtoolsPanelProps,
   TCoreDevtoolsClass extends {
-    mount: (el: HTMLElement, theme: 'light' | 'dark') => void
+    mount: (el: HTMLElement, props: DevtoolsPanelProps) => void
     unmount: () => void
   },
 >(CoreClass: new () => TCoreDevtoolsClass): readonly [Panel, NoOpPanel]
@@ -107,10 +107,13 @@ function createReactPanel<
 **Usage:**
 
 ```tsx
-import { createReactPanel } from '@tanstack/devtools-utils/react'
+import {
+  createReactPanel,
+  type DevtoolsPanelProps,
+} from '@tanstack/devtools-utils/react'
 
 class MyDevtoolsCore {
-  mount(el: HTMLElement, theme: 'light' | 'dark') {
+  mount(el: HTMLElement, props: DevtoolsPanelProps) {
     // render your devtools UI into el
   }
   unmount() {
@@ -129,9 +132,9 @@ const [MyPlugin, NoOpPlugin] = createReactPlugin({
 
 The returned `Panel` component:
 - Creates a `div` with `height: 100%` and stores a ref to it.
-- Instantiates `CoreClass` on mount and calls `core.mount(el, theme)`.
+- Instantiates `CoreClass` on mount and calls `core.mount(el, props)`.
 - Calls `core.unmount()` on cleanup.
-- Re-mounts when the `theme` prop changes.
+- Re-mounts when the plugin props change.
 
 `NoOpPanel` renders an empty fragment and does nothing.
 
@@ -262,14 +265,18 @@ The panel component accepts `theme` and `devtoolsProps` as props. It mounts the
 
 ### createSveltePlugin
 
-The Svelte factory takes a `name` string and a Svelte component as separate arguments, similar to the Vue API.
+The Svelte factory takes the plugin metadata and Svelte component in a configuration object.
 
 **Signature:**
 
 ```ts
 function createSveltePlugin<TComponentProps extends Record<string, any>>(
-  name: string,
-  component: Component<TComponentProps>,
+  config: {
+    name: string
+    id?: string
+    defaultOpen?: boolean
+    Component: Component<TComponentProps>
+  },
 ): readonly [Plugin, NoOpPlugin]
 ```
 
@@ -279,13 +286,18 @@ function createSveltePlugin<TComponentProps extends Record<string, any>>(
 import { createSveltePlugin } from '@tanstack/devtools-utils/svelte'
 import MyStorePanel from './MyStorePanel.svelte'
 
-const [MyPlugin, NoOpPlugin] = createSveltePlugin('My Store', MyStorePanel)
+const [MyPlugin, NoOpPlugin] = createSveltePlugin({
+  Component: MyStorePanel,
+  name: 'My Store',
+  id: 'my-store',
+  defaultOpen: true,
+})
 ```
 
 The returned functions:
 
-- **`Plugin(props?)`** -- returns `{ name, component, props }` where `component` is your Svelte component.
-- **`NoOpPlugin(props?)`** -- returns `{ name, component: NoOpComponent, props }` where the component renders nothing visible.
+- **`Plugin(props?)`** -- returns the plugin metadata, component, and forwarded props.
+- **`NoOpPlugin(props?)`** -- preserves the plugin metadata and props but replaces the component with one that renders nothing visible.
 
 Both accept an optional `props` object that gets forwarded to the component on mount.
 
@@ -299,7 +311,7 @@ import { createSveltePanel } from '@tanstack/devtools-utils/svelte'
 const [MyPanel, NoOpPanel] = createSveltePanel(MyDevtoolsCore)
 ```
 
-The panel accepts `theme` and `devtoolsProps` props. It creates a `div` element, mounts the core instance into it, and calls `unmount()` on cleanup.
+The panel constructs the core without arguments. It creates a `div` element, passes the complete `{ theme, devtoolsOpen }` plugin props to `mount()`, and registers `unmount()` with Svelte's component cleanup lifecycle.
 
 ## Angular
 

docs/devtools-utils.md

@@ -28,7 +28,7 @@ Each plugin describes a tab in the devtools panel:
 ```ts
 type PluginRender =
   | JSX.Element
-  | ((el: HTMLElement, theme: 'dark' | 'light') => JSX.Element)
+  | ((el: HTMLElement, props: TanStackDevtoolsPluginProps) => JSX.Element)
 
 type TanStackDevtoolsReactPlugin = {
   id?: string
@@ -38,7 +38,7 @@ type TanStackDevtoolsReactPlugin = {
 }
 ```
 
-- **`render`** can be a JSX element (simplest -- just pass `<YourPanel />`) or a function that receives the container element and current theme. The function form is useful when you need to access the raw DOM element or respond to theme changes.
+- **`render`** can be a JSX element (simplest -- just pass `<YourPanel />`) or a function that receives the container element and current `{ theme, devtoolsOpen }` props. The function form is useful when you need to access the raw DOM element or respond to plugin state changes.
 - **`name`** works the same way -- use a string for plain text, or JSX / a function for custom tab titles.
 - **`id`** is an optional unique identifier. If omitted, it is generated from the name.
 - **`defaultOpen`** marks the plugin as initially active when no other plugins are open.

docs/framework/react/adapter.md

@@ -38,14 +38,16 @@ type TanStackDevtoolsSveltePlugin = {
 | Field | Type | Description |
 | --- | --- | --- |
 | `id` | `string` (optional) | Unique identifier for the plugin. |
-| `component` | `Component<any>` | The Svelte component to render as the plugin panel content. |
-| `name` | `string \| Component<any>` | Display name for the tab title. Can be a plain string or a Svelte component for custom rendering. |
-| `props` | `Record<string, any>` (optional) | Additional props passed to the plugin component on mount. |
+| `component` | `Component<any>` | The Svelte component to render as the plugin panel content. It receives the shared `theme` and `devtoolsOpen` props. |
+| `name` | `string \| Component<any>` | Display name for the tab title. A custom Svelte component receives the same merged plugin props. |
+| `props` | `Record<string, any>` (optional) | Additional props merged with the shared plugin props when the component mounts. |
 | `defaultOpen` | `boolean` (optional) | Whether this plugin tab should be open by default. |
 
 ## Key Difference from Other Frameworks
 
-The Svelte adapter uses `component` (a Svelte component reference) instead of `render` (a JSX element) in plugin definitions. Props are provided through the `props` field and passed to the component via Svelte's `mount()` API, rather than being embedded directly in a JSX expression.
+The Svelte adapter uses `component` (a Svelte component reference) instead of `render` (a JSX element) in plugin definitions. It passes `{ theme, devtoolsOpen, ...plugin.props }` to the component through Svelte's `mount()` API.
+
+When the core renders a plugin again, the adapter updates the existing Svelte host with the latest component and props. If the component identity is unchanged, its state and lifecycle remain intact. The adapter unmounts the host when the plugin is destroyed or the Devtools instance shuts down.
 
 ```svelte
 <!-- Svelte: pass component reference + props -->

docs/framework/svelte/adapter.md

@@ -48,6 +48,6 @@ Import the desired devtools and provide them to the `TanStackDevtools` component
 <TanStackDevtools {plugins} />
 ```
 
-> Note: The Svelte adapter uses `component` (a Svelte component reference) instead of `render` (a JSX element) in plugin definitions. Additional props can be provided via the `props` field and are passed to the component on mount.
+> Note: The Svelte adapter uses `component` (a Svelte component reference) instead of `render` (a JSX element) in plugin definitions. Components receive the shared `theme` and `devtoolsOpen` props. Additional values from the plugin's `props` field are merged into the same object when the component mounts.
 
 Finally, add any additional configuration you desire to the `TanStackDevtools` component. More information can be found under the [TanStack Devtools Configuration](../../configuration) section.