beplus-mcp 0.28.0 → 0.29.0

package/README.md

@@ -121,11 +121,13 @@ Falam com `/api/v1/canvas`. **Não geram mídia nem gastam diamantes**: montam o
 | Tool | O que faz |
 |------|-----------|
 | `canvas_list_boards` | Boards de que você é membro (id, título, papel, seq). |
-| `canvas_read_board` | Resumo compacto: nós (tipo, nome, campos principais), ligações, vínculo com o IA Lab. Sem mídia. `node_ids` traz o `data` de alguns nós, com cada corte marcado (`path=…`). **Obrigatório antes de editar.** |
-| `canvas_read_node` | O `data` de um nó **sem corte**, em JSON, com tamanho total e sha256 para conferir e fazer diff; partes explícitas (`offset`) acima de `max_chars`. Na Montagem, sem `path`, traz `data.timeline` (ou `data.sequence`, o legado, quando ainda não há timeline) e diz qual veio. Não conta como leitura para editar. |
+| `canvas_read_board` | Resumo compacto: nós (tipo, nome, posição, **tamanho**, campos principais), ligações, vínculo com o IA Lab. Sem mídia. O tamanho diz a origem: `medido` (o da tela) ou `gravado` (o piso). `node_ids` traz o `data` de alguns nós, com cada corte marcado (`path=…`). **Obrigatório antes de editar.** |
+| `canvas_read_node` | O `data` de um nó **sem corte**, em JSON, com tamanho total e sha256 para conferir e fazer diff; partes explícitas (`offset`) acima de `max_chars`. O cabeçalho traz o tamanho do cartão (`medido` com a hora da medida, ou `gravado`). Na Montagem, sem `path`, traz `data.timeline` (ou `data.sequence`, o legado, quando ainda não há timeline) e diz qual veio. Não conta como leitura para editar. |
 | `canvas_create_board` | Cria board vazio ou `template: "narration"` (Contexto, Narração, Roteiro e Locução ligados). |
-| `canvas_add_node` | Adiciona nó de um tipo do catálogo, com `label`, `data` e ligações de entrada/saída no mesmo passo. |
-| `canvas_update_node` | Grava chaves do `data` (null apaga), renomeia (`label`) e move. |
+| `canvas_add_node` | Adiciona nó de um tipo do catálogo, com `label`, `data`, `size` e ligações de entrada/saída no mesmo passo. |
+| `canvas_update_node` | Grava chaves do `data` (null apaga), renomeia (`label`), move (`position`) e muda a caixa (`size`). |
+| `canvas_update_nodes` | Vários nós num passo (position, size, label, data), em envelopes de até 64 KB com o relato de cada um. `layout_only: true` aceita só posição e `size {w, h}`, não pede leitura e não recusa por conflito (nesses campos vale quem grava por último). |
+| `canvas_arrange_rows` | Arruma nós em linhas (uma por versão ou por take) com o tamanho da tela e as larguras da convenção; grava só posição e tamanho. Veja abaixo. |
 | `canvas_patch_node` | Grava vários caminhos dentro do `data` (`{path, value}` ou `{path, unset: true}`), quebrando sozinho em envelopes de até 64 KB e relatando cada um. É o jeito de mexer em partes de uma estrutura grande (ex.: clipes da timeline) sem reenviar tudo. O caminho não entra em lista. |
 | `canvas_upload_media` | Sobe arquivo local ou URL pela rota de arquivos (teto de 95 MB) e devolve url, mime, bytes, duração e dimensões, o item do nó Mídia (`media_item`), o `asset` e o `libraryItemId` de um clipe da timeline da Montagem. Com `board_id`, já grava no nó Mídia (`node_id`) ou cria um nó Mídia novo. |
 | `canvas_connect` | Liga saída → entrada. |
@@ -138,7 +140,37 @@ Falam com `/api/v1/canvas`. **Não geram mídia nem gastam diamantes**: montam o
 | `canvas_reopen_comment` | Reabre, com motivo opcional. |
 | `canvas_comment` | Cria comentário raiz ancorado (nó, versão, minutagem, ponto ou board), para deixar pergunta na tela da pessoa. |
 
-Concorrência: cada edição relê o board, vai num envelope só (um `seq`) e é recusada, sem aplicar nada, se outra pessoa mexeu nos mesmos nós desde a sua leitura. Recusas do servidor (`node-missing` e afins) voltam em português com "releia". A exceção é o `canvas_patch_node`: vários envelopes em ordem, cada um julgado sozinho, e o relatório diz qual entrou.
+Concorrência: cada edição relê o board, vai num envelope só (um `seq`) e é recusada, sem aplicar nada, se outra pessoa mexeu nos mesmos nós desde a sua leitura. Recusas do servidor (`node-missing` e afins) voltam em português com "releia". As exceções são o `canvas_patch_node` e o `canvas_update_nodes`: vários envelopes em ordem, cada um julgado sozinho, e o relatório diz qual entrou. A medida que a tela grava sozinha (`data.__measured`) não conta como "outra pessoa mexeu".
+
+Tamanho do cartão: o `size` gravado é **piso**; o cartão cresce com o conteúdo (um Prompt de 340 de largura com o `!!ESTILO` resolvido vira uma coluna de 1.800). O Canvas grava o tamanho desenhado em `data.__measured = { w, h, at }` quando o cartão passa do piso; as leituras mostram esse (`medido`) ou o piso (`gravado`). É campo interno: não aparece como dado e nenhuma ferramenta grava nele. `size: {w, h}` muda a caixa; `size: "titulo" | "subtitulo" | "corpo"` é o tamanho do texto do Texto livre (`data.size` do nó `label`).
+
+Menção (`!!` de Bloco, `##` de texto): gravar `{{var}}` no `template` do Prompt com `data.mentions = { var: { node, port } }` (o Bloco sai pela porta `text`) cria, no mesmo envelope, a ligação fina que o Canvas desenha no navegador (`viaMention`, id `mention:<origem>:<porta>><prompt>:<var>`, o mesmo dos dois lados). Tirar a var ou a menção tira a ligação. Porta já ligada à mão não ganha segunda ligação, e menção que fecharia ciclo não liga. As ligações das outras regras do conciliador (mídia `@@`, `prompt.refs → gerador.refs`, seções) o Canvas faz ao abrir o board.
+
+#### `canvas_arrange_rows`: linhas de revisão e de take
+
+Uma linha por versão (ou por take), de cima para baixo a partir de `origin`: `title` em cima; à esquerda a coluna `left`, com o prompt, e a mídia/imagem que alimenta o prompt ou o gerador (referência, frame de entrada) alinhada à direita embaixo dele; à direita a coluna `right` (gerador), com o topo no do prompt. Qualquer tipo entra em qualquer coluna. A largura vem do tipo real do nó (sobrescrevível em `widths`): prompt 1024, gerador de imagem 560, gerador de vídeo 560, referência (Mídia) 320, frame (Mídia/imagem ligada na porta `frame` do vídeo) 320, título 1024. `gap` (padrão 80) entre cartões, metade entre título e linha, o dobro entre linhas.
+
+A resposta começa pelo que ainda pode crescer (nós sem medida da tela ou com altura estimada porque a largura mudou), depois as sobreposições **com os tamanhos usados**, as caixas finais e as larguras trocadas. Nó sem medida pode ficar mais alto quando o board abrir: abra o board (o Canvas mede sozinho) e rode a mesma chamada de novo. Se a área encostar em nó de fora, nada é gravado e vem uma origem livre sugerida. `dry_run: true` só calcula.
+
+Revisão de imagem (convenção de 27/09: uma linha por versão, referência própria em cada linha):
+
+```json
+{ "board_id": "…", "origin": { "x": 6000, "y": 0 },
+  "rows": [
+    { "title": "<título v1>", "left": ["<prompt v1>", "<referência v1>"], "right": ["<gerador de imagem v1>"] },
+    { "title": "<título v2>", "left": ["<prompt v2>", "<referência v2>"], "right": ["<gerador de imagem v2>"] }
+  ] }
+```
+
+Linha de take da animação (frame de entrada ligado em `frame` do vídeo, prompt ligado em `prompt`):
+
+```json
+{ "board_id": "…", "origin": { "x": 0, "y": 8000 },
+  "rows": [
+    { "title": "<título take 1>", "left": ["<prompt take 1>", "<frame take 1>"], "right": ["<gerador de vídeo take 1>"] },
+    { "title": "<título take 2>", "left": ["<prompt take 2>", "<frame take 2>"], "right": ["<gerador de vídeo take 2>"] }
+  ] }
+```
 
 Montagem: `musicGainDb`, `duckingDb` e `fadeMs` valem só para a montagem automática (clipes ligados). A timeline do editor (`data.timeline`; `data.sequence` é o legado congelado desde a EP1 do Canvas) tem volume próprio nos clipes (`gainDb`, pontos de ganho, fades) e nas faixas. Quando o nó já tem `data.timeline`, o MCP não escreve no `data.sequence`.