# Conceitos

O cmux organiza seus terminais em uma hierarquia de quatro níveis. Entender esses níveis ajuda ao usar a API de socket, CLI e atalhos de teclado.

## Hierarquia

```
Window
  └── Workspace (sidebar entry)
        └── Pane (split region)
              └── Surface (tab within pane)
                    └── Panel (terminal or browser content)
```

### Janela

Uma janela do macOS. Abra múltiplas janelas com ⌘⇧N. Cada janela tem sua própria barra lateral com workspaces independentes.

### Workspace

Uma entrada na barra lateral. Cada workspace contém um ou mais painéis divididos. Workspaces são o que você vê listado na barra lateral esquerda.

Na interface e nos atalhos de teclado, workspaces são frequentemente chamados de "abas" já que se comportam como abas na barra lateral. A API de socket e variáveis de ambiente usam o termo "workspace".

| Contexto | Termo usado |
| --- | --- |
| Interface da barra lateral | Aba |
| Atalhos de teclado | Workspace ou aba |
| API de socket | `workspace` |
| Variável de ambiente | `CMUX_WORKSPACE_ID` |

**Atalhos: ⌘N (novo), ⌘1–⌘9 (pular), ⌘⇧W (fechar), ⌃⌘\[ / ⌃⌘\] (anterior/próximo)**

### Painel

Uma região dividida dentro de um workspace. Criado dividindo com ⌘D (direita) ou ⌘⇧D (baixo). Navegue entre painéis com ⌥⌘ + teclas de seta.

Cada painel pode conter múltiplas superfícies (abas dentro do painel).

### Superfície

Uma aba dentro de um painel. Cada painel tem sua própria barra de abas e pode conter múltiplas superfícies. Criada com ⌘T, navegada com ⌘\[ / ⌘\] ou ⌃1–⌃9.

Superfícies são as sessões individuais de terminal ou navegador com as quais você interage. Cada superfície tem sua própria variável de ambiente CMUX\_SURFACE\_ID.

### Panel

O conteúdo dentro de uma superfície. Atualmente dois tipos:

-   **Terminal: uma sessão de terminal Ghostty**
-   **Navegador: uma visualização web integrada**

Panel é majoritariamente um conceito interno. Na API de socket e CLI, você interage com superfícies em vez de panels diretamente.

## Grupos de Workspaces

Agrupe workspaces relacionados em seções nomeadas e recolhíveis na barra lateral. Cada grupo pertence a um workspace âncora e pode ser fixado, renomeado e receber seu próprio ícone e cor. Novos workspaces podem ser criados diretamente dentro de um grupo a partir do seu cabeçalho.

[Leia o guia completo de Grupos de Workspaces](https://cmux.com/pt-BR/docs/workspace-groups)

## Exemplo visual

```
┌──────────────────────────────────────────────────────┐
│ ┌──────────┐ ┌─────────────────────────────────────┐ │
│ │ Sidebar  │ │ Workspace "dev"                     │ │
│ │          │ │                                     │ │
│ │          │ │ ┌───────────────┬─────────────────┐ │ │
│ │ > dev    │ │ │ Pane 1        │ Pane 2          │ │ │
│ │   server │ │ │ [S1] [S2]     │ [S1]            │ │ │
│ │   logs   │ │ │               │                 │ │ │
│ │          │ │ │  Terminal     │  Terminal       │ │ │
│ │          │ │ │               │                 │ │ │
│ │          │ │ └───────────────┴─────────────────┘ │ │
│ └──────────┘ └─────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
```

Neste exemplo:

-   A janela contém uma barra lateral com três workspaces (dev, server, logs)
-   O workspace "dev" está selecionado, mostrando dois painéis lado a lado
-   O Painel 1 tem duas superfícies (\[S1\] e \[S2\] na barra de abas), com S1 ativa
-   O Painel 2 tem uma superfície
-   Cada superfície contém um panel (um terminal neste caso)

## Resumo

| Nível | O que é | Criado por | Identificado por |
| --- | --- | --- | --- |
| Janela | Janela do macOS | `⌘⇧N` | — |
| Workspace | Entrada na barra lateral | `⌘N` | `CMUX_WORKSPACE_ID` |
| Painel | Região dividida | `⌘D` / `⌘⇧D` | ID do painel (API de socket) |
| Superfície | Aba dentro do painel | `⌘T` | `CMUX_SURFACE_ID` |
| Panel | Terminal ou navegador | Automático | ID do panel (interno) |

Canonical: https://cmux.com/pt-BR/docs/concepts

Documentation index: https://cmux.com/llms.txt