CommandCanvas: Construindo em Torno de Objetos Compartilhados

No CommandCanvas, um esboço pode se tornar um diagrama estruturado ao lado de sua fonte. Uma pessoa pode rearranjar o resultado, um colaborador pode editá-lo e um agente host suportado pode abordá-lo através do WebMCP. Cada operação se refere a objetos na mesma sala, com identidades e versões que sobrevivem às mudanças na forma como as pessoas interagem com eles.

Eu construí as mutações da tela compartilhada em torno de um caminho de commit. A entrada por ponteiro, voz e ferramentas podem propor mudanças, mas o servidor deve estabelecer qual membro autorizou uma mudança e se ela ainda se aplica ao estado atual da sala. Adicionar outra entrada não deve introduzir outra definição do que conta como salvo.

Objetos que pessoas e ferramentas podem abordar

Uma nota no CommandCanvas tem uma identidade, um título, uma posição, dimensões e uma versão. Seu conteúdo segue um esquema de nota. Um quadro de tarefas tem colunas e tarefas. Um esboço tem traços e pontos. Um diagrama estruturado tem sua própria carga útil e pode reter uma referência ao esboço do qual veio.

Esses objetos compartilham comportamento espacial enquanto mantêm seus diferentes tipos de conteúdo. Mover um quadro deve preservar suas tarefas. Redimensionar um esboço deve preservar o desenho. Uma operação pode abordar um objeto específico e verificar sua versão antes de alterá-lo. O modelo de objeto torna essas distinções explícitas.

Isso dá a um pedido de ferramenta algo concreto para abordar: o esboço selecionado, um quadro populado ou um objeto existente para transformar. Também restringe o resultado. Uma resposta de modelo deve se encaixar em um esquema de objeto suportado antes que a aplicação possa submetê-la como uma mudança na tela.

A distinção é útil quando pessoas e um agente se revezam. Eles podem se referir ao mesmo objeto sem reconstruir seu conteúdo a partir de uma captura de tela ou carregar uma cópia separada em outra conversa.

Onde uma mudança na tela é registrada

O navegador mantém os objetos visíveis, a seleção atual e o estado da sala. A entrada direta produz comandos de tela. O WebMCP e a voz embutida opcional passam por um runtime de capacidade que valida seus argumentos e contexto atual antes de invocar os adaptadores de comando.

O WebMCP expõe capacidades a um agente host suportado. A voz embutida usa uma conexão OpenAI Realtime separada e um conjunto mais restrito de capacidades. Ambos alcançam os adaptadores de comando da aplicação; nenhum tem sua própria rota ao redor da associação à sala ou verificações de revisão.

O caminho durável da sala se parece com isto:

flowchart TD
  subgraph browser[Espaço de trabalho do navegador]
    direct[Ponteiro, toque e intenções de mão] --> command[Comando canônico da tela]
    tools[WebMCP e voz opcional] --> capability[Validação de capacidade]
    capability --> command
  end
  subgraph server[Servidor e banco de dados]
    api[API de sala autenticada] --> guards[Verificações de associação e revisão]
    guards --> commit[Transação de mutação Postgres]
    commit --> records[Objetos, revisão da sala e recibo]
  end
  command -->|Comando, fonte e revisão base| api
  records -->|Leitura autoritativa| origin[Canvas de origem]
  records -->|Notificação de revisão| reload[Outros clientes recarregam o estado da sala]
  reload --> peers[Canvases de colaboradores]
  presence[Presença e transmissão de cursor] -.-> origin
  presence -.-> peers

O navegador propõe um comando; o servidor estabelece quem pode registrá-lo. Setas sólidas traçam o caminho durável de comando e sincronização. Setas pontilhadas mostram a presença dos participantes e o tráfego do cursor, que não criam recibos de mutação. Em telas estreitas, role o diagrama horizontalmente.

O pedido carrega um ID de comando, sua fonte de entrada relatada e a revisão da sala contra a qual o cliente trabalhou. A rota HTTP verifica o token do portador. O serviço de sala carrega a associação, deriva o ator, lê a tela atual e constrói um plano de mutação. A operação do banco de dados verifica a revisão esperada novamente ao registrar a mudança.

Essa segunda verificação é importante porque a sala pode mudar entre a leitura do servidor e a tentativa de gravação. Um comando preparado contra a revisão 12 não pode ser registrado contra a revisão 13 assumindo que sua visão original ainda se aplica. O pedido obsoleto é rejeitado.

A revisão compartilhada torna a ordem das mudanças registradas explícita. Também torna os conflitos mais grosseiros: duas pessoas trabalhando em objetos diferentes ainda podem competir pela mesma revisão da sala. A aplicação não mescla automaticamente essas edições. Esse é o custo de usar uma única revisão da sala como uma pré-condição de commit.

A transação persiste as mudanças de objeto, avança a revisão da sala e escreve o recibo. O servidor recarrega o estado autoritativo e verifica o recibo esperado antes de retornar o sucesso. Outros clientes recebem uma notificação de revisão compacta e recarregam a sala. O serviço de sala contém esse caminho de commit e leitura.

Por que as prévias de arraste ficam fora do histórico

Aplicar esse caminho de commit a cada amostra de cursor faria com que o movimento ordinário competisse com as edições de objetos por revisões de sala. Também preencheria o histórico com posições intermediárias que são de pouco uso quando alguém deseja desfazer uma ação concluída.

Os cursores e prévias de movimento, portanto, permanecem efêmeros. A Presença do Supabase descreve os participantes conectados, e a Transmissão carrega as atualizações frequentes. Mudanças de objeto estáveis passam pelo caminho de mutação e produzem o recibo que outros clientes podem verificar.

A sala pode mostrar movimento antes de ter um novo estado registrado. Essa distinção é necessária para uma interação responsiva, e deve sobreviver na interface: ver o cursor de outra pessoa se mover não é evidência de que sua edição foi salva.

Transformando um esboço em outro objeto

A interpretação de esboço introduz uma lacuna maior entre preparar uma mudança e tentar registrá-la. Um provedor pode terminar seu trabalho depois que o desenho que recebeu mudou.

A transformação captura o ID e a versão do esboço selecionado, e então o rasteriza para um PNG no navegador. Um provedor interpreta essa imagem e retorna uma saída estruturada. A aplicação valida a carga útil, verifica a referência da fonte e verifica se o tipo de saída solicitado concorda com o resultado.

A pessoa pode continuar desenhando enquanto o provedor trabalha. Antes de submeter o novo objeto, a transformação verifica a versão da fonte novamente. Se o esboço mudou, a interpretação pode ter sido bem-sucedida, mas a aplicação se recusa a criar o diagrama a partir desse resultado. O tempo do provedor já foi gasto; aceitar sua resposta de qualquer maneira anexaria uma interpretação desatualizada ao trabalho atual.

sequenceDiagram
  participant C as Canvas
  participant P as Serviço de Interpretação
  participant R as API de Sala
  C->>C: Capturar ID e versão do esboço
  C->>P: Esboço rasterizado e instruções
  P-->>C: Resultado estruturado
  C->>C: Validar carga útil e verificar fonte novamente
  alt Fonte inalterada
    C->>R: Criar diagrama vinculado na revisão atual da sala
    R-->>C: Objeto registrado e recibo
  else Fonte alterada
    C->>C: Recusar a transformação obsoleta
  end

O diagrama gerado se torna um objeto de tela separado. O esboço original permanece disponível, incluindo quando a interpretação falha ou sua fonte mudou. Em telas estreitas, role o diagrama horizontalmente.

Criar o resultado ainda usa o caminho de comando ordinário.