@mittwald/flow-react-components 1.2.0-next.8 → 2.0.0-next.0

package/AGENTS.md

@@ -125,6 +125,17 @@ return (
   components break remote rendering.
 - When parent context must not leak into a component's children, use targeted
   clearing, e.g. `wrapWith: <ClearPropsContext />` (see `Modal.tsx`).
+- **A context that tunnels `Button` must tunnel overlay triggers as a whole** —
+  spread `overlayTriggersTunneledTo(tunnel)` (`@/lib/propsContext`). An overlay
+  trigger's button is the react-aria trigger: `OverlayTrigger` pins it with
+  `tunnel: null`, because the press handling, the trigger ref and
+  `aria-haspopup`/`aria-expanded`/`aria-controls` travel through a
+  `PressResponder` that only reaches its own subtree. The list includes
+  `DialogTrigger` because a host sees a different component than the author
+  wrote: `ModalTrigger`, `PopoverTrigger` and `LightBoxTrigger` are not
+  `@flr-generate`, so a remote tree reaches the host as a `DialogTrigger` with
+  no `OverlayTrigger` around it — which is why `DialogTrigger` pins the button
+  itself as well.
 
 Why this works the way it does across the remote boundary:
 [docs/remote-ui.md](https://github.com/mittwald/flow/blob/main/docs/remote-ui.md).
@@ -147,6 +158,13 @@ Why this works the way it does across the remote boundary:
 Remote generation details:
 
 - `@flr-generate all` on the component const marks it for generation.
+- `@flr-provider` carries a `flowComponent`'s `type: "provider"` over to the
+  generated remote component. Without it the remote element is created as a
+  `"ui"` component and wrapped in a `ClearPropsContext` — which drops every
+  props context a provider around it just set. It only matters where the
+  provider actually runs inside the remote tree, i.e. where the component that
+  renders it is not itself `@flr-generate` (`ModalTrigger` → `OverlayTrigger` →
+  `DialogTriggerView`).
 - **A prop that carries rendered output has to be a slot, not a property.** A
   remote property is transported as data, and a React element carries
   `$$typeof: Symbol(react.…)` — `postMessage` refuses symbols and rejects the
@@ -158,6 +176,15 @@ Remote generation details:
   output, because the host has to call it: that needs an eager slot or
   `@flr-ignore-props`. `checkSerializableProps` **fails generation** on any such
   prop, so a new one cannot ship.
+- **A function property's return value is a Promise on the host.** Functions do
+  cross — as thread proxies — but calling one is a round trip. Type the return
+  as `Promise<T> | T` and await it on the host (`ChartTooltip`'s formatters), or
+  keep the prop off the remote surface with `@flr-ignore-props` (`XAxis`/`YAxis`
+  `tickFormatter`). A host that reads the result synchronously gets the Promise
+  itself — recharts concatenated it into every tick as `[object Promise]`.
+  `checkSerializableProps` fails generation on a new one; the pre-existing set
+  is listed in `acknowledgedValueReturningProps`, which can neither grow nor go
+  stale.
 - `@flr-ignore-props` excludes props that must not cross the remote boundary —
   either because they cannot be serialized, or because they could do **too much
   on the host side**. A global ignore list lives in
@@ -229,6 +256,17 @@ if ("action" in props) {
   Group repeated variants in local mixins.
 - Structure sections with comments: `/* Elements */`, `/* States */`,
   `/* Size */`, `/* Variants */`.
+- **A `z-index` is scoped by the nearest ancestor stacking context** — mark that
+  element `isolation: isolate` explicitly. `position: relative`, a scroll
+  container (`overflow: auto`) and a flex/grid parent are **not** stacking
+  contexts, so without it the value competes with the whole page instead of the
+  siblings it was written for. A `transform` animation in between is one only
+  _while it runs_, so the scope otherwise changes with the animation state.
+  Isolating does not reorder anything inside the component: among positioned
+  siblings, `z-index: auto` and a `0`-equivalent stacking context paint in the
+  same step, in tree order. The exception is an element portalled into
+  `document.body` (`NotificationContainer`) — that one sits in the root stacking
+  context by construction and cannot be scoped; say so in a comment.
 - **Overriding a dependency that injects its own stylesheet** (CodeMirror,
   react-easy-crop, FontAwesome) needs `@layer flow.unlayered { … }`: their
   `<style>` elements are unlayered, and unlayered CSS beats layered CSS
@@ -276,15 +314,23 @@ Run: `pnpm nx test:unit components`,
 
 ## Public API surfaces
 
-| Export                                                          | Contents                                                                                                                                                                                                           |
-| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `.` (default)                                                   | Everything listed **manually** in `src/components/public.ts` — new public components must be added there.                                                                                                          |
-| `./internal`                                                    | Advanced internals (`flowComponent`, prop helper types, …).                                                                                                                                                        |
-| `./flr-universal`                                               | Curated subset that works local _and_ remote. Adding to `public.ts` does **not** add here.                                                                                                                         |
-| `./nextjs`, `./react-hook-form`, `./mittwald-password-tools-js` | Integrations (`src/integrations/`): wrappers around third-party dependencies that not every consumer should pay for — they get their own export entry instead of entering the core surface.                        |
-| `./all.css`, `./all-layered.css`                                | Bundled stylesheet, plain and `@layer`-wrapped.                                                                                                                                                                    |
-| `./component-index`                                             | Generated consumer-facing index: every public component with its status and its own props (`dev/component-index/`). What the docs site's prop tables read, and the one prop dataset a consumer's agent should use. |
-| `./doc-properties`                                              | Raw `react-docgen-typescript` output — a 13 MB build input for the generators above, not something to read directly.                                                                                               |
+| Export                                                          | Contents                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.` (default)                                                   | Everything listed **manually** in `src/components/public.ts` — new public components must be added there.                                                                                                                                           |
+| `./internal`                                                    | Advanced internals (`flowComponent`, prop helper types, …).                                                                                                                                                                                         |
+| `./flr-universal`                                               | Curated subset that works local _and_ remote. Adding to `public.ts` does **not** add here.                                                                                                                                                          |
+| `./tunnel`                                                      | `@mittwald/react-tunnel` re-exported (`src/index/tunnel.ts`) plus `getTunnelProviderId`, so a consumer's own tunnels share Flow's module instance instead of creating a second React context.                                                       |
+| `./nextjs`, `./react-hook-form`, `./mittwald-password-tools-js` | Integrations (`src/integrations/`): wrappers around third-party dependencies that not every consumer should pay for — they get their own export entry instead of entering the core surface.                                                         |
+| `./all.css`, `./all-layered.css`                                | Bundled stylesheet, plain and `@layer`-wrapped.                                                                                                                                                                                                     |
+| `./component-index`                                             | Generated consumer-facing index: every public component with its status and its own props (`dev/component-index/`). What the docs site's prop tables read, and the one prop dataset a consumer's agent should use.                                  |
+| `./doc-properties`                                              | `react-docgen-typescript` output in its raw `ComponentDoc[]` shape, filtered to the props a consumer can act on. Prefer `./component-index`. The unfiltered dump the generators above read is `.cache/doc-properties.json`, which is not published. |
+
+**Adding any new export entry?** Add the subpath to `keptSubpaths` in
+`packages/codemods/src/migrations/imports-to-package-root/transform.ts`. That
+codemod collapses subpath imports onto the package root with a catch-all `else`,
+so a subpath that is not listed gets flattened onto a root that does not export
+its names. The guard beside the transform fails the codemods unit tests when you
+forget.
 
 **Adding a new integration export entry?** Also register it in the component
 status registry so it is covered: add the entry to `STATUS_EXPORT_ENTRIES`
@@ -342,6 +388,19 @@ Easy-to-miss conventions not spelled out above. Full details and examples in
   must affect layout.
 - **Controllers coexist with declarative props** — overlay-like APIs support
   controlled/uncontrolled props _and_ a controller object, not one or the other.
+- **A component without `value` and without `defaultValue` still has to render
+  as controlled** — react-aria's `useControlledState` reads only `undefined` as
+  uncontrolled. A component that mirrors the value in its own state therefore
+  hands react-aria `undefined` on the first render and a real value after the
+  first change: the value changes owner mid-flight, and React and react-aria
+  warn `A component changed from uncontrolled to controlled`. Pass a sentinel
+  instead of `undefined` — `null` where "nothing selected yet" is representable
+  (`Tabs`' `selectedKey`), otherwise the type's empty value (`""` for text,
+  `NaN` for a number, `null` for a date range — `useControlledHostValueProps`'
+  `emptyValue`). Mind `??` once the sentinel is `null`: a caller-supplied `null`
+  must not fall through to `defaultValue`. Nothing breaks visibly, and a
+  component holding its own document state (`CodeEditor`) does not even warn —
+  it changes owner silently.
 - **Complex behavior is split by vocabulary** — `components/` for render,
   `hooks/` for behavior, `lib/` for pure transforms, `models/` for durable
   state.
@@ -360,6 +419,20 @@ Easy-to-miss conventions not spelled out above. Full details and examples in
   icon-only padding silently do not apply. Wrap it — `<Icon><IconFoo /></Icon>`
   — as the [Icon page](https://flow.mittwald.de/components/content/icon)
   documents. Nothing errors: types, lint and the console stay clean.
+- **A collection child is rendered twice** — react-aria renders the children of
+  a collection (`Select`, `ComboBox`, `Autocomplete`, `Menu`, `ListBox`, `Tree`,
+  …) once into its hidden collection document and once for real. Both renders
+  are full component instances, so anything derived per instance happens twice
+  for one logical element: `useId` returns two ids, effects run twice, and every
+  registration into shared state lands twice. Whatever such a child registers
+  therefore needs an id derived from the element itself, not a generated one —
+  options pass their collection key as the tunnel's `staticEntryId`
+  (`Option/optionsTunnel.ts`), and a new tunnelled collection child must do the
+  same. Without it the tunnel exit renders each child twice: the keys stay
+  unique, so the DOM and the tests look right, but the collection holds two
+  nodes per key and its `prevKey`/`nextKey` chain closes into a ring — `ArrowUp`
+  on the first item wraps to the last, and react-stately's focus restoration
+  walks `getKeyBefore` forever and freezes the tab (#3146).
 - **Universal exports are deliberately explicit** — remote-safe values and their
   types are curated in `flr-universal.ts` independently of the main public
   surface; adding to `public.ts` does not add them there.

package/MIGRATION.md

@@ -28,6 +28,192 @@ The CLI's own output does detect it and prints the right form.
 
 ---
 
+<a id="popover-open-state-props"></a>
+
+## Popover: `defaultOpen` renamed, `isOpen` and `onOpenChange` now work
+
+**Since `1.1.47`** · migration · codemod available · also applies to
+`@mittwald/flow-remote-react-components`
+
+`Popover`'s open state props now behave the way their names say. This covers
+`ContextualHelp` and `ContextMenu` too, which inherit them.
+
+#### `defaultOpen` is now `isDefaultOpen`
+
+The name matches `Modal` and the other overlays.
+
+```diff
+- <ContextualHelp defaultOpen>
++ <ContextualHelp isDefaultOpen>
+```
+
+`defaultOpen` keeps working and logs a deprecation warning. A codemod renames
+it, on `Popover`, `ContextualHelp` and `ContextMenu` only — the identically
+named react-aria prop on `Select`, `MenuTrigger`, `Tooltip`, `TooltipTrigger`,
+`DialogTrigger`, `DatePicker` and `DateRangePicker` is untouched.
+
+#### `onOpenChange` reports instead of taking over
+
+Passing `onOpenChange` used to switch the popover into a controlled mode that
+had no `isOpen` to control it with: the handler fired, and the popover stopped
+closing. It is now a notification that fires on every path — react-aria's
+dismissal, and a close performed through the controller — and never performs or
+suppresses the change.
+
+```diff
+- <Popover onOpenChange={(isOpen) => controller.setOpen(isOpen)}>
++ <Popover onOpenChange={(isOpen) => track(isOpen)}>
+```
+
+Two things to check:
+
+- A handler that performed the close itself can drop that call. Leaving it in is
+  harmless — the controller ignores a state it is already applying.
+- A handler that relied on the prop to _block_ a close no longer blocks it. Use
+  the controller for that: a handler registered through `useOverlayController`'s
+  `onClose` still aborts by returning `false`.
+
+#### `isOpen` controls the popover
+
+`isOpen` was inherited from react-aria but silently overridden. It is now the
+open state whenever it is set.
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<Popover isOpen={isOpen} onOpenChange={setIsOpen}>
+  …
+</Popover>;
+```
+
+If you pass `isOpen` without updating it from `onOpenChange` — for instance by
+spreading props that happen to carry it — the popover no longer opens. Drop the
+prop, or wire up the state.
+
+A controller stays the third option and needs neither prop: with
+`controller={controller}`, `onOpenChange` is a pure monitor.
+
+**Apply:** Rename `defaultOpen` to `isDefaultOpen` on `Popover`,
+`ContextualHelp` and `ContextMenu` — a codemod does it, scoped to those three.
+Leave `defaultOpen` alone on `Select`, `MenuTrigger`, `Tooltip`,
+`TooltipTrigger`, `DialogTrigger`, `DatePicker` and `DateRangePicker`, where it
+is react-aria's own prop and unchanged. Then check every `isOpen` and
+`onOpenChange` passed to those three by hand, because both changed behaviour and
+neither is mechanically decidable. `isOpen` used to be ignored and now controls
+the popover: a value that is not kept up to date through `onOpenChange` keeps
+the popover closed. `onOpenChange` used to take over the open state and now only
+reports it, so a handler that performed the close itself —
+`onOpenChange={(open) => controller.setOpen(open)}` — can drop that call, and a
+handler that relied on the prop to _suppress_ the close no longer does; use the
+controller's `onClose` for that.
+
+```shell
+npx @mittwald/flow-codemods@latest popover-open-state-props src
+```
+
+---
+
+<a id="tabler-icons-no-longer-transitive"></a>
+
+## @tabler/icons-react is no longer installed alongside Flow
+
+**Since `1.1.40`** · migration · manual change · also applies to
+`@mittwald/flow-remote-react-components`
+
+Flow no longer depends on `@tabler/icons-react`. `@mittwald/flow-icons` carries
+the path data of the 123 icons it uses directly, so a Flow install stops pulling
+in 74 MB and ~24,000 files it never needed.
+
+The icons themselves do not change: same names, same exports, same rendered
+`<svg>` including the `tabler-icon` and `tabler-icon-<name>` classes.
+
+The one thing that breaks is code which imported `@tabler/icons-react` without
+declaring it, and got it because npm hoisted Flow's copy into the project's
+`node_modules`. That copy is gone. Declare the package where you use it:
+
+```shell
+npm i @tabler/icons-react
+```
+
+```tsx
+// unchanged — it just needs the package in your own dependencies now
+import { IconStar } from "@tabler/icons-react";
+
+<Icon>
+  <IconStar />
+</Icon>;
+```
+
+**Apply:** Only affects code that imports from `@tabler/icons-react` — typically
+a `<Icon><IconSomething /></Icon>` using an icon that is not in Flow's own set.
+Add the package to your own dependencies (`npm i @tabler/icons-react`); the
+imports themselves stay unchanged. Flow's own `Icon*` components are unaffected,
+keep their names, and render exactly as before.
+
+---
+
+<a id="option-value-inferred-from-mixed-children"></a>
+
+## Option: value is inferred from mixed children
+
+**Since `1.1.12`** · migration · no code change needed · also applies to
+`@mittwald/flow-remote-react-components`
+
+An `Option` used to infer its `textValue` — and, through it, its `value` — only
+when its children were exactly one text node. Text next to any element left both
+undefined, so react-aria assigned the option a key off a render-order counter:
+
+```tsx
+<Select>
+  <Option>
+    Millennium Falcon <Badge>Latest</Badge>
+  </Option>
+  <Option>X-Wing</Option>
+</Select>
+```
+
+| Option                        | key before     | key now             |
+| ----------------------------- | -------------- | ------------------- |
+| `Millennium Falcon` + `Badge` | `react-aria-1` | `Millennium Falcon` |
+| `X-Wing`                      | `X-Wing`       | `X-Wing`            |
+
+The key is what the field reports as its selected value and what `defaultValue`
+has to match, so the old key made the field submit a meaningless string, could
+not be preselected, and shifted when unrelated markup around it changed.
+
+Only text that is a child itself contributes — text inside an element child does
+not, so the option above is `"Millennium Falcon"` and not
+`"Millennium Falcon Latest"`.
+
+An `Option` with no text among its children at all still has no key to infer,
+and now says so on the console instead of failing silently:
+
+```tsx
+// logs: An <Option> has no 'value' and none could be inferred from its children…
+<Option>
+  <Text>Millennium Falcon</Text>
+</Option>
+```
+
+Give those options a `value`:
+
+```diff
+- <Option>
++ <Option value="millennium-falcon">
+    <Text>Millennium Falcon</Text>
+  </Option>
+```
+
+**Apply:** No code change required for the option itself. An `Option` whose
+children are text plus an element — text and a `Badge`, text and an icon — now
+carries that text as its key, where it previously fell back to react-aria's
+generated `react-aria-N`. Check anywhere such a key was read back: a stored or
+server-side selection, a `defaultValue`/`value` matched against it, or a test
+asserting on it. Pass an explicit `value` to pin the key to something other than
+the display text.
+
+---
+
 <a id="use-design-tokens-build-metadata-removed"></a>
 
 ## useDesignTokens(): no longer returns style-dictionary build metadata
@@ -509,7 +695,7 @@ case.
 
 ## TableColumn: `maxWidth` removed, `width` and `minWidth` retyped
 
-**Since `0.2.0-alpha.956`** · migration · manual change · also applies to
+**Since `0.2.0-alpha.956`** · migration · codemod available · also applies to
 `@mittwald/flow-remote-react-components`
 
 `maxWidth` has been removed. `width` and `minWidth` are now typed as
@@ -526,9 +712,24 @@ Percentage, pixel and `fr` values keep working as strings or numbers
 (`width="50%"`, `width="200fr"`, `width={300}`). Where you passed `null` to mean
 "no explicit width", omit the prop instead.
 
+A codemod removes `maxWidth` — the prop is gone from the type, so an explicit
+attribute is wrong at any value, an expression included — and removes a `width`
+or `minWidth` written as the literal `null`.
+
+It declines what it cannot decide from the source: `width={maybeNull}` could be
+anything at runtime, and a spread's contents are invisible. Both keep their
+props and need a look by hand.
+
 **Apply:** Remove `maxWidth` from every `TableColumn`. Where `width` or
 `minWidth` was `null`, omit the prop instead — the type no longer accepts
-`null`, only `number | string`.
+`null`, only `number | string`. A codemod does both for the cases it can decide
+from the source. Two it declines: a `width`/`minWidth` whose value is an
+expression (`width={maybeNull}`), and a spread that might carry `maxWidth`
+(`<TableColumn {...props} />`). Check those by hand.
+
+```shell
+npx @mittwald/flow-codemods@latest table-column-width-props src
+```
 
 ---
 
@@ -949,18 +1150,39 @@ Only function **references** are affected. An inline arrow
 (`onAction={() => …}`), a zero-parameter function, and anything already
 accepting `unknown` are all fine.
 
-A codemod renames the prop. It deliberately does not wrap: whether the
-referenced function declares a parameter cannot be decided from the source —
-that needs type information — and wrapping everything would silently drop the
-arguments `Action` passes to handlers that do accept them.
+A codemod renames the prop and wraps the reference.
+
+Whether a reference _needs_ wrapping is not decidable from the source — that
+needs type information. Performing the wrap does not need it: `() => fn()` calls
+what `Action` would have called, and `onAction` takes no arguments. So the wrap
+fixes the reference that needed it and changes nothing for the rest, which makes
+the decision unnecessary.
+
+Wrapped: a plain identifier and a member expression (`close`,
+`controller.close`, `this.handleSave`). Left alone: an arrow function and a
+function expression, which already are the handler; a call (`makeHandler()`,
+`close.bind(controller)`), which produces it; and anything that is not one
+reference (`isOpen ? close : open`, `onClose ?? noop`, `controller?.close`).
+
+Two wraps are worth a look afterwards. A handler that read the event `Action`
+forwards — undocumented, but it does forward the trigger's event — stops
+receiving it. And `onAction={props.onAction}`, where the reference may be
+`undefined`: passing it was fine, calling it is not, so TypeScript now reports
+the call and wants a guard.
 
 **Apply:** Rename the `action` prop on `Action` to `onAction`. Not only a
 rename: the new prop is typed `ActionFn` (`(...args: unknown[]) => unknown`), so
 a function _reference_ that declares a parameter no longer type-checks and needs
 wrapping — `onAction={() => controller.close()}` rather than
-`onAction={controller.close}`. Check every site where you passed a reference
-rather than an inline arrow; the codemod renames the prop but cannot decide this
-one from the source.
+`onAction={controller.close}`. A codemod does both. It wraps every bare
+reference (`close`, `controller.close`), because the wrap is a no-op for a
+reference that did not need it. It leaves a value that already is the handler or
+produces one — an arrow function, a function expression, a call like
+`makeHandler()` or `close.bind(controller)` — and anything that is not one
+reference, such as `isOpen ? close : open` or `controller?.close`. Two wraps to
+look at afterwards: a handler that read the event `Action` forwards stops
+receiving it, and a possibly-undefined reference (`onAction={props.onAction}`)
+becomes a call TypeScript rejects — add the guard it asks for.
 
 ```shell
 npx @mittwald/flow-codemods@latest action-prop-to-on-action src
@@ -1033,6 +1255,21 @@ import { Field } from "@mittwald/flow-react-components/react-hook-form";
 import { Link } from "@mittwald/flow-react-components/nextjs";
 ```
 
+### Stylesheets stay stylesheet imports
+
+A CSS export is a file, not a JS module, so it never moves onto the package
+root. A bundler query addressing it (`?url`, `?inline`, `?raw`) is part of how
+the file is requested, not part of the subpath — both of these stay exactly as
+they are:
+
+```javascript
+import "@mittwald/flow-react-components/all.css";
+import flowStyles from "@mittwald/flow-react-components/all.css?url";
+```
+
+Only a stale `global.css` or `globals.css` is rewritten to `all.css`, query
+included.
+
 ### `tsconfig.json`
 
 Set `"module": "esnext"` in your `tsconfig.json`, if you have trouble with
@@ -1057,8 +1294,13 @@ and the first stable release of Flow is `1.0.0`.
 **Apply:** Rewrite every subdirectory import from
 `@mittwald/flow-react-components` to the package root, except `react-hook-form`
 and `nextjs`, which move to `@mittwald/flow-react-components/react-hook-form`
-and `@mittwald/flow-react-components/nextjs`. If you hit missing module errors,
-set `"module": "esnext"` in `tsconfig.json`.
+and `@mittwald/flow-react-components/nextjs`. Asset imports are not part of
+this: a CSS specifier stays a CSS specifier — `all.css` and `all-layered.css`
+unchanged, a stale `global.css` or `globals.css` rewritten to `all.css` — and
+keeps any bundler query it carries (`?url`, `?inline`, `?raw`). It never becomes
+a named import from the package root, which has no JS binding behind a
+stylesheet. If you hit missing module errors, set `"module": "esnext"` in
+`tsconfig.json`.
 
 ```shell
 npx @mittwald/flow-codemods@latest imports-to-package-root src
@@ -1070,7 +1312,7 @@ npx @mittwald/flow-codemods@latest imports-to-package-root src
 
 ## Renamed CSS export
 
-**Since `0.1.0-alpha.292`** · migration · manual change
+**Since `0.1.0-alpha.292`** · migration · codemod available
 
 The CSS export `@mittwald/flow-react-components/styles` has renamed to the more
 precise name `@mittwald/flow-react-components/all.css`, because the file
@@ -1083,5 +1325,16 @@ as well. A documentation on how to use them is planned.
 + import "@mittwald/flow-react-components/all.css";
 ```
 
+A codemod rewrites the specifier in every JavaScript and TypeScript form that
+names a module. It cannot reach a `.css` or `.scss` file, so an `@import` of the
+old path there needs a manual search.
+
 **Apply:** Replace the import `@mittwald/flow-react-components/styles` with
-`@mittwald/flow-react-components/all.css`.
+`@mittwald/flow-react-components/all.css`, keeping any bundler query the
+specifier carries (`.../styles?url` becomes `.../all.css?url`). A codemod does
+this for JavaScript and TypeScript files. An `@import` of the old path inside a
+`.css` or `.scss` file is not covered — search for it by hand.
+
+```shell
+npx @mittwald/flow-codemods@latest renamed-css-export src
+```

package/USAGE.md

@@ -70,6 +70,7 @@ overrides), `RouterProvider` (so `Link` and navigation use your router),
 | `@mittwald/flow-react-components/nextjs`                     | Next.js integration                             |
 | `@mittwald/flow-react-components/react-hook-form`            | react-hook-form integration                     |
 | `@mittwald/flow-react-components/mittwald-password-tools-js` | password-strength integration                   |
+| `@mittwald/flow-react-components/tunnel`                     | Tunnels — see below                             |
 | `@mittwald/flow-react-components/all.css`                    | Stylesheet                                      |
 | `@mittwald/flow-react-components/component-index`            | Machine-readable component + prop index (below) |
 
@@ -77,6 +78,34 @@ overrides), `RouterProvider` (so `Link` and navigation use your router),
 (`flowComponent`, prop helper types, the status registry) and is not a consumer
 API.
 
+### Tunnels
+
+`@mittwald/flow-react-components/tunnel` re-exports `TunnelProvider`,
+`TunnelEntry` and `TunnelExit`. Import them from there — **never add
+`@mittwald/react-tunnel` to your own dependencies.** Its React context lives in
+a module-level `createContext`, so a second copy of the package is a second,
+unrelated context: your `TunnelEntry` stops finding any provider and
+`useTunnelState` throws at runtime. Nothing in `tsc` or ESLint warns first.
+
+The same entry point exports `getTunnelProviderId`, which names the tunnel Flow
+opens around every ui/layout component. That is how you render into a Flow
+component's own exits — a `Heading`'s `headingContent`, for example, the slot
+`Badge` and `AlertBadge` use:
+
+```tsx
+import {
+  TunnelEntry,
+  getTunnelProviderId,
+} from "@mittwald/flow-react-components/tunnel";
+
+<Heading>
+  <ModelTitle model={model} />
+  <TunnelEntry id="headingContent" providerId={getTunnelProviderId("Heading")}>
+    {titleSuffix}
+  </TunnelEntry>
+</Heading>;
+```
+
 ## Finding the right component
 
 `@mittwald/flow-react-components/component-index` is a JSON index of every