# `A2UI.Server`
[🔗](https://github.com/23min/ex_a2ui/blob/main/lib/a2ui/server.ex#L1)

Starts an A2UI WebSocket server, embeddable in any OTP supervision tree.

## Example

    # In your application supervisor:
    children = [
      {A2UI.Server,
       provider: MyApp.DashboardProvider,
       port: 4000}
    ]

    Supervisor.start_link(children, strategy: :one_for_one)

## Options

- `:provider` (required) — module implementing `A2UI.SurfaceProvider`
- `:provider_opts` — map passed to `provider.init/1` (default: `%{}`)
- `:port` — HTTP port (default: `4000`)
- `:ip` — bind address (default: `{127, 0, 0, 1}`)

All other options are forwarded to Bandit.

## Push Updates

Use `push_data/3` and `push_surface/2` to broadcast updates to all
connected clients from external processes (timers, PubSub, GenServer casts):

    A2UI.Server.push_data("dashboard", %{"/uptime" => 42},
      provider: MyApp.DashboardProvider)

    A2UI.Server.push_surface(updated_surface,
      provider: MyApp.DashboardProvider)

You can also pass `registry:` directly if you've already resolved it.

# `broadcast`

```elixir
@spec broadcast(String.t(), term(), keyword()) :: :ok
```

Sends an arbitrary message to all connected socket processes for the given surface.

## Options

- `:provider` — the provider module (resolves registry automatically)
- `:registry` — the Registry name directly (use one or the other)

# `broadcast_all`

```elixir
@spec broadcast_all(
  term(),
  keyword()
) :: :ok
```

Sends an arbitrary message to all connected socket processes for the provider,
regardless of surface ID.

## Options

- `:provider` — the provider module (resolves registry automatically)
- `:registry` — the Registry name directly (use one or the other)

## Examples

    A2UI.Server.broadcast_all(:tick, provider: MyApp.Provider)

# `child_spec`

```elixir
@spec child_spec(keyword()) :: Supervisor.child_spec()
```

Returns a child specification for starting the A2UI server under a supervisor.

# `push_data`

```elixir
@spec push_data(String.t(), map(), keyword()) :: :ok
```

Broadcasts a data model update to all connected clients for the given surface.

## Options

- `:provider` — the provider module (resolves registry automatically)
- `:registry` — the Registry name directly (use one or the other)

## Examples

    A2UI.Server.push_data("dashboard", %{"/uptime" => 42}, provider: MyApp.Provider)

# `push_surface`

```elixir
@spec push_surface(
  A2UI.Surface.t(),
  keyword()
) :: :ok
```

Broadcasts a full surface update to all connected clients.

## Options

- `:provider` — the provider module (resolves registry automatically)
- `:registry` — the Registry name directly (use one or the other)

## Examples

    A2UI.Server.push_surface(updated_surface, provider: MyApp.Provider)

# `start_link`

```elixir
@spec start_link(keyword()) :: {:ok, pid()} | {:error, term()}
```

Starts the A2UI server linked to the current process.

See `child_spec/1` for available options.

---

*Consult [api-reference.md](api-reference.md) for complete listing*