Tutorial: seu primeiro plugin para o XCoder

Plugins são a forma de dar superpoderes ao XCoder sem mexer no núcleo. Neste tutorial criamos um plugin real — "Capitalizar títulos" — do zero até o marketplace.

1. Estrutura mínima

Um plugin é um ZIP com quatro arquivos na raiz:

titulo-plus.zip
├── plugin.json   ← manifest
├── main.js       ← código
├── icon.png      ← ícone 128×128
└── readme.md     ← documentação curta

O plugin.json declara a identidade:

{
	"id": "titulo-plus",
	"name": "Título Plus",
	"version": "1.0.0",
	"author": "voce",
	"description": "Capitaliza títulos no formato Title Case"
}

2. O código

A API global window.xcoder é a ponte com o app. Registramos um comando que aparece na paleta (Ctrl-Shift-P):

xcoder.setPluginInit("titulo-plus", (onLoad) => {
	const toast = xcoder.require("toast");
	const editor = xcoder.require("editor");

	function titleCase(text) {
		return text.replace(/\w\S*/g, (w) =>
			w[0].toUpperCase() + w.slice(1).toLowerCase(),
		);
	}

	return [
		editor.addCommand({
			name: "Capitalizar titulos",
			description: "Converte a seleção para Title Case",
			action() {
				const sel = editor.getSelection();
				if (!sel) return toast.show("Selecione um texto primeiro");
				editor.replaceSelection(titleCase(sel));
				toast.show("Pronto ✔");
			},
		}),
	];
});

xcoder.setPluginUnmount?.("titulo-plus", () => { /* teardown */ });

Detalhes que importam:

• setPluginInit recebe o id exato do manifest;
• devolva uma função (ou lista) de limpeza — ela roda quando o usuário desativa o plugin;
• comandos registrados herdam a busca fuzzy e as traduções da paleta de comandos;
• não ofusque código: plugins passam por revisão humana.

3. Teste no app

Em Configurações › Plugins, use Instalar de arquivo e escolha o ZIP. Ative o plugin, abra um arquivo, selecione um texto e rode o comando pela paleta. Ajuste, reempacote, reinstale — o ciclo é rápido.

4. Publique no marketplace oficial

1. Crie um fork do carsaimz/xcoder-plugins;
2. Adicione seu ZIP, ícone 128×128 e a entrada no plugins.json (descrição em EN e PT, tags, author_verified: false para novos autores);
3. Abra o pull request — após revisão, o plugin aparece para todos os usuários do app.

Próximos passos

• Explore os 7 plugins oficiais — eles são exemplos vivos da API (o código-fonte está aberto);
• Veja a referência completa em src/api/ no repositório do app;
• Dúvidas? A categoria de ajuda no fórum tem gente esperando para responder.