# `PhiaUi.Collab.RoomManager`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/collab/collab_registry.ex#L1)

Manages collaboration room lifecycles via `DynamicSupervisor`.

Provides join-or-create semantics: if a room already exists, returns
its PID; otherwise starts a new `PhiaUi.Collab.CollabRoom` GenServer
under the `PhiaUi.Collab.RoomSupervisor`.

This module is stateless — it delegates to the `RoomRegistry` (a `Registry`)
for lookups and to the `RoomSupervisor` (a `DynamicSupervisor`) for process
management. Both are started by `PhiaUi.Collab.Supervisor`.

## Example

    # Ensure the room exists (idempotent)
    {:ok, pid} = PhiaUi.Collab.RoomManager.join_or_create_room("doc-123",
      callback_module: MyApp.CollabCallbacks,
      idle_timeout: :timer.minutes(15)
    )

    # Later, when user disconnects
    PhiaUi.Collab.RoomManager.leave_room("doc-123", "user-42")

# `get_room`

```elixir
@spec get_room(String.t()) :: pid() | nil
```

Get the PID of a running room, or `nil` if not running.

# `join_or_create_room`

```elixir
@spec join_or_create_room(
  String.t(),
  keyword()
) :: {:ok, pid()} | {:error, term()}
```

Join or create a collaboration room.

If the room exists, returns `{:ok, pid}`. Otherwise starts a new
`CollabRoom` GenServer under the `DynamicSupervisor`.

## Options
  - `:callback_module` — module implementing `PhiaUi.Collab.CollabRoom` behaviour
  - `:idle_timeout` — milliseconds before an empty room shuts down (default 30 min)

## Returns
  - `{:ok, pid}` — the room process PID
  - `{:error, reason}` — if the room could not be started

# `leave_room`

```elixir
@spec leave_room(String.t(), String.t()) :: :ok
```

Leave a room and trigger cleanup if empty.

Safe to call even if the room is not running — returns `:ok` in all cases.

# `list_rooms`

```elixir
@spec list_rooms() :: [String.t()]
```

List all active room IDs.

Returns a list of room ID strings for all currently running `CollabRoom` processes.

# `room_count`

```elixir
@spec room_count() :: non_neg_integer()
```

Count the number of currently active rooms.

---

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