guides

Expansão de texto no Wayland: por que quebra e o que realmente funciona

Por Equipe Lightning Assist26 de julho de 20269 minutos de leitura
waylandlinuxx11text-expandergnomekdexwaylandinput
Compartilhar:
Expansão de texto no Wayland: por que quebra e o que realmente funciona

Resposta rápida: Os expansores de texto precisam observar cada pressionamento de tecla em todo o sistema e simular a digitação em qualquer aplicativo em foco. O X11 permitia ambos por padrão; os compositores do Wayland restringem deliberadamente ambos por razões de segurança, e é por isso que um expansor de texto que funciona perfeitamente no Ubuntu 20.04 pode ser instalado de forma limpa e não fazer absolutamente nada em uma sessão moderna do Wayland – sem nenhuma mensagem de erro. Não existe uma solução única; as opções reais são XWayland (executar da maneira antiga, dentro de uma camada de compatibilidade), um backend evdev/uinput com acesso explícito ao grupo de entrada ou um backend de entrada dedicado de baixo nível que solicita uma concessão de permissão única. O Lightning Assist usa o último.

Se você instalou um expansor de texto, digitou seu gatilho e não viu nada acontecer – nenhum erro, nenhuma falha, apenas silêncio – você provavelmente está no Wayland, e esta é uma categoria conhecida de problema, não um bug específico da ferramenta que você escolheu.

Por que o Wayland bloqueia a escuta global de teclas

No X11, qualquer processo pode interceptar o teclado em baixo nível e ler cada pressionamento de tecla no sistema, e qualquer processo pode simular pressionamentos de tecla em qualquer janela atualmente em foco - isso é literalmente o que ferramentas como xdotool fazem, e é por isso que expansores de texto, gerenciadores de teclas de atalho e software de controle remoto funcionaram no Linux por duas décadas sem muito atrito. É também, do ponto de vista da segurança, exatamente o tipo de coisa que você não deseja por padrão: qualquer aplicativo, inclusive um comprometido, pode registrar suas teclas digitadas ou injetar entrada arbitrária em sua sessão bancária.

Os compositores do Wayland (Mutter para o GNOME, KWin para o KDE Plasma, os baseados em wlroots para o Sway e similares) foram projetados em torno do padrão oposto: um aplicativo vê apenas os eventos de entrada destinados à sua própria janela e nada pode injetar entrada sintética em outro aplicativo sem um mecanismo explícito e deliberado para fazer isso. Isso não é um descuido ou um recurso ausente — é o modelo de segurança funcionando conforme planejado. O custo é que cada ferramenta que dependia do comportamento "qualquer processo pode observar e injetar" do X11 precisa de uma maneira diferente, e geralmente mais limitada, de fazer o mesmo trabalho.

O resultado prático: um expansor de texto que intercepta as teclas digitadas do jeito do X11 não vê nada em uma sessão pura do Wayland, e um expansor de texto que injeta texto do jeito do X11 não tem nada em que injetar. Normalmente ele falha silenciosamente, em vez de causar um erro claro, porque não há nenhuma exceção sendo lançada — os eventos que ele está escutando simplesmente nunca chegam.

Por que as extensões do navegador não cobrem a área de trabalho

Uma solução alternativa natural é um expansor de texto baseado em extensão do navegador, e apenas para as guias do navegador ele funciona – as extensões operam dentro do DOM da página, o que não tem nada a ver com o modelo de entrada do Wayland. O problema é o escopo: uma extensão só vê o navegador em que está instalada. Ela não pode expandir um snippet no seu terminal, no seu IDE, em um aplicativo GTK ou Qt nativo, no cliente de desktop do Slack ou do Discord, nem em um leitor de PDF. Se o seu dia envolve algo fora de uma guia do navegador (o que para desenvolvedores e equipes de suporte é a maior parte do dia), uma extensão do navegador resolve uma fração do problema e deixa o resto da sua área de trabalho descoberto.

O que realmente existe no Wayland hoje

Não existe uma solução universal, mas existem algumas abordagens reais e documentadas, cada uma com vantagens e desvantagens.

XWayland — rodando da maneira antiga, dentro de uma camada de compatibilidade

A maioria dos ambientes de desktop Wayland (GNOME, KDE Plasma prontos para uso no Ubuntu 22.04+, Fedora 38+ e similares) executam o XWayland junto com o compositor Wayland nativo – uma camada de compatibilidade que permite que aplicativos somente X11 continuem funcionando. Uma ferramenta construída sobre a interceptação de entrada do X11 continua funcionando para aplicativos executados dentro do XWayland. O problema é o escopo: se você estiver em uma sessão onde o XWayland está explicitamente desabilitado (algumas configurações reforçadas do GNOME), ou se o aplicativo específico em que você está digitando for um cliente Wayland nativo em vez de um XWayland, a interceptação no estilo X11 não o alcança.

O protocolo zwp_virtual_keyboard_v1

Alguns compositores Wayland - entre eles o Mutter do GNOME e o KWin do KDE - implementam o protocolo Wayland zwp_virtual_keyboard_v1, que fornece a um aplicativo uma maneira sancionada de simular eventos de teclado. Isso está mais próximo de uma resposta integrada em nível de protocolo do que de uma solução alternativa, mas depende do compositor: um aplicativo que depende dele funciona apenas onde o compositor escolheu implementar esse protocolo, e o comportamento ainda pode variar - algumas configurações recorrem a um substituto baseado em colar da área de transferência, que pode se comportar de maneira diferente em aplicativos com manipulação especial de colagem (um terminal com modo bracketed-paste, por exemplo).

A interface RemoteDesktop do xdg-desktop-portal

A especificação do portal freedesktop.org define uma interface RemoteDesktop construída explicitamente para "permitir o controle remoto de uma sessão de desktop" - ela pode injetar eventos de teclado e ponteiro, mas somente depois que o usuário conceder acesso KEYBOARD/POINTER quando a sessão for iniciada, e é um mecanismo de sessão com escopo de permissão em vez de uma interceptação de sistema sempre ativa. É a porta sancionada que o Wayland fornece para injeção de entrada, mas foi projetada em torno de ferramentas de controle remoto e compartilhamento de tela, não em torno de “detectar silenciosamente cada gatilho que eu digito, para sempre, em segundo plano” – que é o que um expansor de texto realmente precisa.

evdev/uinput com acesso ao grupo de entrada

A opção de nível inferior é ler a entrada bruta diretamente de /dev/input (evdev) e injetar eventos sintéticos por meio de /dev/uinput, ignorando totalmente o modelo de entrada do compositor. Isso funciona genuinamente com qualquer compositor - não importa se você está no GNOME, no KDE ou no Sway, porque opera abaixo de todos eles, na camada de entrada do kernel. O Espanso usa exatamente essa abordagem para seu suporte ao Wayland, que sua própria documentação descreve como "atualmente experimental": requer uma concessão única de setcap cap_dac_override+p no binário (ou associação ao grupo input, dependendo da configuração) para ler a entrada bruta sem executar como root, e vem com advertências conhecidas - layouts de teclado fora dos EUA precisam de configuração explícita, as sessões do GNOME podem mostrar oscilações no back-end da área de transferência e conectar um novo teclado requer uma reinicialização manual do serviço. Funciona, mas “experimental” é a palavra certa para definir a situação atual.

Ferramentas que simplesmente não suportam Wayland

Algumas ferramentas de automação para Linux são construídas diretamente sobre o xdotool e a árvore de janelas do X11, sem nenhum caminho para o Wayland - o AutoKey é o exemplo mais claro: funciona somente com X11, e o XWayland não ajuda porque sua simulação de entrada tem como alvo a árvore da janela X11 diretamente, não o compositor. Se você estiver em uma sessão pura do Wayland, ferramentas como essa simplesmente não funcionam, ponto final, independentemente da configuração.

Como o Lightning Assist lida com isso

O Lightning Assist adota uma abordagem de dois caminhos, dependendo do tipo de sessão. Nas sessões X11 e XWayland, ele usa a interceptação de entrada padrão do X11 - o mesmo mecanismo que funcionou de forma confiável no Linux por anos. Em uma sessão pura do Wayland, ele muda para um back-end de entrada de baixo nível dedicado: na primeira vez que precisa, o aplicativo solicita uma vez o acesso de entrada (um prompt "Conceder acesso") e, após essa concessão única, a detecção global de teclas e a expansão de texto funcionam da mesma maneira no GNOME, no KDE e em outros compositores - sem YAML, sem comando setcap para executar você mesmo, sem etapa de configuração de layout por teclado. Este é um back-end mantido criado para esse propósito, não um substituto instalado posteriormente, e o modelo de concessão única significa que você não repete uma etapa manual a cada sessão.

Uma lista de verificação prática antes de escolher uma ferramenta

Dada a quantidade de variação entre as ferramentas, vale a pena verificar algumas coisas antes de se comprometer com uma em um desktop Wayland:

  • Ela documenta explicitamente o suporte ao Wayland ou apenas alega "suporte a Linux" de forma ampla? Afirmações amplas geralmente significam "testado no X11" com comportamento do Wayland não testado.
  • É necessário um setcap manual ou uma etapa de root para funcionar no Wayland? Não é um impedimento, mas você deve saber disso de antemão, em vez de descobri-lo após a instalação.
  • Ele nomeia advertências específicas do compositor (GNOME, KDE, Sway) em vez de um genérico "funciona no Wayland"? Ferramentas que são honestas sobre peculiaridades específicas do compositor (cintilação da área de transferência, configuração do layout do teclado, reinicialização em um novo dispositivo) geralmente são aquelas que realmente foram testadas lá.
  • O XWayland precisa permanecer ativado? Se uma ferramenta só funciona através do XWayland, confirme se o seu ambiente de desktop o mantém ativado por padrão (a maioria mantém) antes de assumir a compatibilidade.

Perguntas frequentes

Por que meu expansor de texto funciona em uma máquina Linux, mas não em outra?

A causa mais comum é o tipo de sessão: sessões X11 e sessões Wayland lidam com entradas globais de maneira completamente diferente, e uma ferramenta construída principalmente em torno da interceptação de entrada do X11 pode funcionar perfeitamente em uma e não fazer nada na outra. Execute echo $XDG_SESSION_TYPE em um terminal para verificar qual tipo de sessão você está executando atualmente.

O Wayland simplesmente não funciona para ferramentas de produtividade?

Não – é um modelo de segurança diferente e mais restritivo, não um bug. As restrições que bloqueiam ferramentas ingênuas de entrada global são as mesmas restrições que tornam mais difícil para um aplicativo malicioso registrar suas teclas digitadas ou injetar entrada em sua sessão bancária. As ferramentas que funcionam bem no Wayland são aquelas construídas especificamente em torno de seu modelo de permissão (portais, zwp_virtual_keyboard_v1, ou um backend evdev/uinput dedicado com acesso ao grupo de entrada) em vez daquelas que assumem acesso irrestrito no estilo X11.

Desativar o XWayland quebra a expansão de texto?

Pode, para qualquer ferramenta que dependa da interceptação no estilo X11 para alcançar aplicativos executados no XWayland. Se você estiver em uma configuração reforçada com o XWayland explicitamente desativado, verifique especificamente se o seu expansor de texto tem um back-end nativo do Wayland (não apenas uma interceptação X11) - o back-end de entrada Wayland dedicado do Lightning Assist e o modo experimental evdev/uinput do Espanso são ambos construídos exatamente para este caso; uma ferramenta construída exclusivamente sobre o xdotool ou sobre o acesso à árvore de janelas do X11, como o AutoKey, não é.

Preciso executar algum comando de terminal para que o suporte do Wayland funcione?

Depende da ferramenta. O modo Wayland do Espanso precisa de uma concessão única de setcap (ou associação equivalente a um grupo de entrada) que você mesmo executa. Em vez disso, o back-end Wayland do Lightning Assist solicita uma permissão única de "Conceder acesso" no aplicativo na primeira vez que for necessária - nenhum comando de terminal é necessário.

Leitura Relacionada

Fontes

Artigos relacionados