# @nexus-cross/connect-kit-core

Pure domain layer for **crossx-kit** — TypeScript types, port interfaces, and
framework-agnostic utilities. This package has **no runtime dependencies** on
wagmi, viem, React, or any wallet SDK. It is the seam that lets the wagmi and
React layers evolve independently.

> DApp developers normally don't install this package directly. Install
> [`@nexus-cross/connect-kit-react`](../react) (and optionally
> [`@nexus-cross/connect-kit-wagmi`](../wagmi)) — both re-export the types you need.

## Install

```sh
pnpm add @nexus-cross/connect-kit-core
```

## What's inside

### Domain types

```ts
import type {
  // Wallet taxonomy
  WalletId,            // 'cross_embedded' | 'cross_wallet' | 'cross_extension' | 'metamask' | 'binance' | (string & {})
  ConnectorType,       // 'embedded' | 'app' | 'extension' | 'external'
  WalletDescriptor,

  // Connection result
  Account,
  ConnectorResult,
  ChainBalance,

  // Kit config (input to createCrossxConfig)
  CrossConnectKitConfig,
  AppMetadata,
  NetworkConfig,

  // UI / Theme
  ModalView,
  Theme,
  ThemeMode,           // 'light' | 'dark'
  ThemeTokens,

  // PIN keyboard (embedded SDK modal behavior)
  PinKeyboardMode,     // 'virtual' | 'native'
  PinKeyboardOption,   // PinKeyboardMode | (() => PinKeyboardMode)

  // Misc
  Unsubscribe,
  WalletState,
} from '@nexus-cross/connect-kit-core';

import { ConnectionStatus } from '@nexus-cross/connect-kit-core';
// ConnectionStatus.CONNECTED | .DISCONNECTED | .CONNECTING | .RECONNECTING
```

### Ports (capability interfaces)

Ports describe **what** the kit needs from its environment, not **how** it is
delivered. Adapters in `@nexus-cross/connect-kit-wagmi` and `@nexus-cross/connect-kit-react` implement
them.

```ts
import type {
  ConnectorPort,        // Connect / disconnect / subscribe to wallet state
  StoragePort,          // Async key-value storage (localStorage, cookies, …)
  ModalControlPort,     // Open / close the kit's modal views
  ThemePort,            // Read & write theme tokens
  WalletDetectionPort,  // EIP-6963 / injected / SDK wallet discovery
  BalancePort,          // Per-chain balance fetcher
} from '@nexus-cross/connect-kit-core';
```

Ports are the only contract core has with the outside world — any new external
capability must enter through a port, never as a direct dependency.

### Utilities

BigInt-safe formatters for blockchain numerics. These **always floor** when
truncating decimals and never round up or use banker's rounding.

```ts
import { formatBalance, formatWei } from '@nexus-cross/connect-kit-core';

formatBalance(1234567890000000000n, 18);      // '1.234567890000000000'
formatBalance(1234567890000000000n, 18, 4);   // '1.2345'  (truncated)
formatWei('0xde0b6b3a7640000');               // '1'       (1 ETH)
```

## Design rules

The core package enforces the architectural spine:

- **No environment dependencies** — no wagmi, viem, React, DOM, or Node APIs.
  Anything impure lives behind a port.
- **Constructor injection only** — no singletons, no module-level globals,
  no hidden `window` access.
- **BigInt end-to-end** — wei / gas / balance values stay in `BigInt` through
  every computation; display values are UI-only and never fed back into
  arithmetic.
- **External SDK types don't leak** — the wagmi package converts between
  external shapes (viem `Address`, wagmi `Connector`) and core's plain types
  (`string` addresses, `WalletDescriptor`) at its own boundary.

## Compatibility

- TypeScript 5.x
- Node 18+ / modern browsers (ES2020 target)
- No peer dependencies

## License

MIT