# `runtime-override` — pack-component override merger

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Pure helper that merges a `ComponentPack`'s default components with the
`<ReactUiProvider components={...}>` runtime override map. The result
is a flat `Map<componentName, ComponentType<unknown>>` the chassis
stores in the `PackRegistryContext`'s `resolved` slot. White-label and
runtime-swap scenarios drive the override mechanism — consumers swap a
pack's `LoginForm` for their bespoke implementation without forking the
pack package.

## Features

- Pure / synchronous merge of pack defaults with overrides
- Skips `undefined` override entries so consumers can spread a partial
  override map without wiping a pack default
- Skips overrides for unrelated packs so multiple packs share a single
  override map without cross-talk
- Returns a frozen-style `ReadonlyMap` so consumers cannot mutate
  the registry post-construction

## Usage: Basic example

```ts
import { mergePackComponents } from "@suaveplan/react-ui/pack";

const merged = mergePackComponents({
    pack: authPack,
    overrides: {
        auth: { LoginForm: AcmeLoginForm },
    },
});
```

## Usage: Advanced example

```ts
import {
    mergePackComponents,
    type RuntimeComponentOverride,
} from "@suaveplan/react-ui/pack";

const overrides: RuntimeComponentOverride = {
    auth: {
        LoginForm: AcmeLoginForm,
        RegisterForm: AcmeRegisterForm,
    },
    social: {
        ShareButton: AcmeShareButton,
    },
};

const merged = mergePackComponents({ pack: authPack, overrides });
const Login = merged.get("LoginForm"); // → AcmeLoginForm
```

## API Reference

- `mergePackComponents({ pack, overrides? })` →
  `ReadonlyMap<string, ComponentType<unknown>>`
- `type RuntimeComponentOverride = Partial<Record<string,
  Partial<Record<string, ComponentType<unknown>>>>>`

## Implementation notes

The override semantics are intentionally simple: the override entry,
if present and not `undefined`, replaces the pack's default for that
component name. There is no deep-merge or composition step because
React components are atomic units — swapping `LoginForm` is the
intent, not "augment the existing component with override props". A
consumer that wants compositional swapping wraps their override
component around the imported pack default explicitly.