# melt-ui/next-gen architecture

> Architecture diagram of the GitHub repository melt-ui/next-gen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/melt-ui/next-gen
- Repository: https://github.com/melt-ui/next-gen

## Overview

#### Overview

Melt UI is a Svelte library of headless, accessible component builders. It supplies interaction behavior, state, and WAI-ARIA-oriented behavior while application code supplies markup composition, styling, and surrounding components.

#### Public surfaces

- `packages/melt/src/lib/index.ts` is the primary package entry point.
- `packages/melt/src/lib/builders/index.ts` organizes the component-builder API, including controls such as dialogs, selects, tabs, menus, and trees.
- `packages/melt/src/lib/components/index.ts` provides a separate Svelte component surface for the component implementations present in that directory.
- `docs/src/pages/index.astro` is the documentation site entry; its content describes installation, styling, component usage, and API behavior.

#### Core implementation areas

- **Builder layer — `packages/melt/src/lib/builders`**  
  Contains per-component Svelte/TypeScript builders. This is the main headless behavior layer and is the primary extension surface for applications that want their own DOM and visual design.

- **Svelte component layer — `packages/melt/src/lib/components`**  
  Contains ready-made Svelte component implementations for part of the builder catalog. It is a distinct consumer-facing surface; the tree does not establish that every component delegates directly to a builder.

- **Shared runtime utilities — `packages/melt/src/lib/utils`**  
  Provides reusable browser and interaction mechanics, including attributes, DOM events, keyboard handling, focus trapping, pointer behavior, popovers, collections, typeahead, floating positioning, and selection state.

- **Shared contracts — `packages/melt/src/lib/types.ts`**  
  Centralizes TypeScript types used across the library’s public and internal surfaces.

#### State and boundaries

Interaction state appears to be in-memory and Svelte-reactive, supported by state-oriented modules such as `selection-state.svelte.ts`, `getters.svelte.ts`, and `effect.svelte.ts`. No durable storage or server-side persistence layer is visible in the supplied tree.

The external actor is the consuming Svelte application: it chooses markup, styles, component composition, and application data. Melt UI owns reusable interaction and accessibility behavior. Browser DOM APIs and events form the principal runtime boundary.

#### Relationships

A consuming Svelte app reaches the library through `packages/melt/src/lib/index.ts`, then uses either the builder surface or available Svelte components. Builders and components share contracts from `packages/melt/src/lib/types.ts` and reusable mechanics from `packages/melt/src/lib/utils`. The documentation site explains these public surfaces but is a separate documentation application, not a runtime dependency of the library.

Main entry points: [`packages/melt/src/lib/index.ts`](https://github.com/melt-ui/next-gen/blob/main/packages/melt/src/lib/index.ts) (Library entry), [`packages/melt/src/lib/components`](https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/components) (Svelte components), [`packages/melt/src/lib/builders`](https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/builders) (Builders), [`packages/melt/src/lib/utils`](https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/utils) (Runtime utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public surfaces"]
  node_entry["Library entry<br/>package entry point<br/>[index.ts]"]
  node_components["Svelte components<br/>component surface"]
end

subgraph group_runtime["Library runtime"]
  node_builders["Builders<br/>headless builder layer"]
  node_utils["Runtime utilities"]
  node_types["Shared contracts<br/>TypeScript contracts<br/>[types.ts]"]
end

subgraph group_external["External boundaries"]
  node_consumer(("Consuming Svelte app<br/>external consumer"))
  node_browser(("Browser DOM and events<br/>external runtime"))
end

subgraph group_docs["Documentation"]
  node_docs["Documentation site<br/>documentation application<br/>[index.astro]"]
end

node_consumer -->|"imports"| node_entry
node_entry -->|"exposes"| node_builders
node_entry -->|"exposes"| node_components
node_builders -->|"uses mechanics"| node_utils
node_components -->|"uses mechanics"| node_utils
node_builders -->|"uses contracts"| node_types
node_components -->|"uses contracts"| node_types
node_utils -->|"uses DOM events"| node_browser
node_docs -.->|"documents"| node_entry

click node_entry "https://github.com/melt-ui/next-gen/blob/main/packages/melt/src/lib/index.ts"
click node_builders "https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/builders"
click node_components "https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/components"
click node_utils "https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/utils"
click node_types "https://github.com/melt-ui/next-gen/blob/main/packages/melt/src/lib/types.ts"
click node_docs "https://github.com/melt-ui/next-gen/blob/main/docs/src/pages/index.astro"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_components toneBlue
class node_builders,node_utils,node_types toneAmber
class node_consumer,node_browser toneMint
class node_docs toneRose
```

## Components

### Public surfaces

Consumer-facing library entry points.

- [Library entry](https://github.com/melt-ui/next-gen/blob/main/packages/melt/src/lib/index.ts): package entry point · `packages/melt/src/lib/index.ts`
- [Svelte components](https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/components): component surface · Provides ready-made Svelte component implementations. · `packages/melt/src/lib/components`

### Library runtime

Headless behavior, components, shared mechanics, and contracts.

- [Builders](https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/builders): headless builder layer · Provides reusable interaction and accessibility behavior. · `packages/melt/src/lib/builders`
- [Runtime utilities](https://github.com/melt-ui/next-gen/tree/main/packages/melt/src/lib/utils): shared runtime utilities · Provides browser and interaction mechanics. · `packages/melt/src/lib/utils`
- [Shared contracts](https://github.com/melt-ui/next-gen/blob/main/packages/melt/src/lib/types.ts): TypeScript contracts · `packages/melt/src/lib/types.ts`

### External boundaries

Consumer applications and browser runtime.

- **Consuming Svelte app**: external consumer · Supplies markup, styling, composition, and application data.
- **Browser DOM and events**: external runtime

### Documentation

Separate documentation application.

- [Documentation site](https://github.com/melt-ui/next-gen/blob/main/docs/src/pages/index.astro): documentation application · Explains installation, styling, usage, and API behavior. · `docs/src/pages/index.astro`

## Connections

- Consuming Svelte app → Library entry: imports
- Library entry → Builders: exposes
- Library entry → Svelte components: exposes
- Builders → Runtime utilities: uses mechanics
- Svelte components → Runtime utilities: uses mechanics
- Builders → Shared contracts: uses contracts
- Svelte components → Shared contracts: uses contracts
- Runtime utilities → Browser DOM and events: uses DOM events
- Documentation site → Library entry: documents
