yuzuha 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -21,6 +21,86 @@ documentos. Veja a [política completa](VERSIONING.md).
 
 </details>
 
+## v0.2.0 · 02/11/2026
+
+Embeds completos em uma API só, nos modos nativo e function mode, com uma matriz automática de paridade com o SDK. Esta atualização da biblioteca Yuzuha foi preparada em 02/11/2026 (v0.2.0); a tag Git `v0.2.0` aponta para esta versão.
+
+- `Embed` aceita `url`, `timestamp`, `author` com ícone e link, `footer.iconURL`, texto alternativo em imagem e miniatura, e `fields[].inline` opcional. Na função `$color` e em `$embedFromObject`, a cor aceita `#RRGGBB`, tupla `r,g,b` ou nome simples; o tipo `Embed` nativo continua recebendo número. `embed()` valida um embed tipado na API nativa e `yuzuha/sdk` continua expondo o `EmbedBuilder` do SDK.
+- Mensagens aceitam até 10 embeds, `tts`, `stickerIds`, `flags`, `allowedMentions` e `reply` na API nativa. O padrão continua sem menções e sem ping ao autor respondido. Relaxar menções exige `MentionEveryone` do autor, e TTS exige `SendTtsMessages`.
+- Catorze funções novas: `$url`, `$embedTimestamp`, `$author`, `$footerIcon`, `$imageAlt`, `$thumbnailAlt`, `$fields`, `$addField`, `$removeField`, `$editField`, `$embedFromObject`, `$embeds`, `$addEmbed` e `$messageOptions`. `$field` aceita valor vazio quando é inline.
+- `$fetchMessage` e `$messages` devolvem `embeds` normalizados, com `type`, `provider`, `video`, `audio`, `nsfw` e `children` somente leitura.
+- Mudança incompatível: `MessageInfo.embeds` é obrigatório para implementações próprias de `MessagesResources`. Objetos de mensagem em script rejeitam chaves desconhecidas, que antes viravam embed sem validação. Veja [VERSIONING.md](VERSIONING.md#migrar-para-020).
+- `npm run docs:generate` gera [PARITY-MATRIX.md](docs/PARITY-MATRIX.md), que classifica cada export do SDK como coberto por script, coberto pelo código nativo, só-SDK ou lacuna. Um teste falha quando o SDK ganha export sem área.
+- Catálogo do function mode: de 322 para **336** funções. [FUNCTION-GAPS.md](docs/FUNCTION-GAPS.md) foi atualizado com a contagem real.
+
+## v0.1.9 · 29/10/2026
+
+Composição opcional de cartões para comandos, eventos e function mode, com fontes locais e renderização isolada. Esta atualização da biblioteca Yuzuha foi preparada em 29/10/2026 (v0.1.9).
+
+- `yuzuha/canvas` oferece builder tipado para texto, imagens, avatares, formas, gradientes, sombras, badges e progresso. A raiz e o function mode continuam importáveis sem instalar `@napi-rs/canvas`; o backend carrega somente no processo filho durante a renderização.
+- `ctx.canvas.send` e `bot.contextEvent` permitem anexar imagens em comandos e eventos sem mensagem. O canal é explícito quando o evento não o fornece.
+- Doze funções `$canvas*` mantêm cenas privadas por execução e elevam o catálogo canônico de 310 para **322**. Quotas, cancelamento e limites atravessam `$try`.
+- Inter 4.1 Regular e Bold acompanham os arquivos originais e a licença OFL. Fontes próprias podem vir de bytes, aliases configurados ou HTTP submetido à política do contexto.
+- Canvas e Sharp compartilham no máximo dois processos simultâneos, sem fila implícita. Canvas não depende de Sharp; `yuzuha/images` preserva seu contrato.
+- Perfil, boas-vindas e ranking têm versões JS, TS e function mode e geram nove PNGs offline. O tarball verifica imports sem os peers e renderização real com Canvas sem Sharp.
+- SDK 3.3.0, Node >=22.13 e schema persistido 2 permanecem compatíveis.
+
+## v0.1.8 · 28/10/2026
+
+Bases de bots, buscas e páginas do Fluxer.js, com autorização compartilhada e correções de limites, streams e cooldowns. Esta atualização da biblioteca Yuzuha foi preparada em 28/10/2026 (v0.1.8).
+
+- A CLI oferece sete bases JS/TS com `templates` e `init --template`: simple, multifunctional, moderation, community, economy, entertainment e utility. A multifuncional reúne 24 comandos raiz; os projetos incluem configuração, exemplos e testes offline. O scaffold padrão e `--functions` continuam disponíveis.
+- A distribuição preserva o modo executável da CLI e testa a instalação, os tipos e o dispatch dos 14 pares de base/linguagem a partir do tarball.
+- Quatro funções novas levam o catálogo de 306 a **310**: `$searchMessagesAdvanced`, `$pinnedMessagesPage`, `$reactionUsersPage` e `$threadMember`. Seus recursos e tipos também estão disponíveis na API nativa.
+- A busca aceita filtros de conteúdo, frases, autores, canais, menções, anexos, IDs e ordenação sem exigir texto. A validação é compartilhada entre scripts e adaptador, copia arrays e limita as opções a 32 KiB; a busca anterior continua disponível, incluindo cursor vazio.
+- Páginas de fixadas preservam ordem de fixação, timestamps, `hasMore` e cursor ISO. Páginas de reações preservam `hasMore`/`nextAfter`, incluindo respostas legadas em array. A consulta individual de membros de threads inclui flags e metadados de mute, com o autor do contexto como padrão nos scripts.
+- Mutações de emojis e stickers pelo contexto exigem `ManageExpressions` de autor e bot no servidor atual. Criar emoji verifica as permissões antes do download e revalida antes de criar o recurso. Guards não são capturados por `$try`.
+- `$jsonEncode` preserva guards, limites, cancelamento, controle de loops e `PartialModerationError`. Incrementos, remoções/inclusões em arrays e atualizações por caminho verificam a saída antes do commit, preservando valor, TTL e ausência quando recusados.
+- O prazo cooperativo do runtime usa relógio monotônico. Esperas externas sobrepostas ou aninhadas descontam seu intervalo uma única vez, sem conceder tempo duplicado.
+- HTTP valida sub-redes IPv4/IPv6, inclusive IPv4 mapeado, link-local e redes especiais. Literais IPv6 públicos funcionam sem consulta DNS; credenciais na URL e corpos em GET/HEAD são recusados.
+- Redirects preservam os métodos conforme o padrão Fetch e removem cabeçalhos de conteúdo quando descartam o corpo. Respostas binárias copiam chunks reutilizados; cancelamento libera readers mesmo quando a fonte não conclui a limpeza.
+- Anexos por stream mantêm os metadados validados durante a leitura e não deixam um timeout agendado quando a fonte já está bloqueada por outro reader.
+- Deduplicação de mensagens e consultas de cooldown ativo deixam de varrer o mapa de cooldowns. A coleta considera vencimentos e pressão de capacidade; renovação e admissão reutilizam entradas expiradas, mantendo o teto de 100 mil. Flags malformadas geram `GuardError` antes do handler.
+- Um benchmark reproduzível compara a implementação anterior e a atual com amostras intercaladas. O ganho é localizado na manutenção removida; cenários comuns tiveram resultados mistos, registrados sem alegação de aceleração geral.
+- Referências, catálogo do editor, guias e consumidores JS/TS acompanham os novos contratos. O SDK continua fixado em 3.3.0, o schema persistido em 2 e os sete entrypoints permanecem disponíveis.
+- **Adaptação de integrações:** implementações completas próprias de `MessagesResources` devem acrescentar `pinnedPage` e `reactionUsersPage`; `ThreadsResources` deve acrescentar `member`. Comandos antes autorizados apenas pelo bot podem receber `GuardError` nas mutações de expressões. Apesar da numeração patch, esta entrega altera esses contratos; veja [VERSIONING.md](VERSIONING.md) antes de atualizar.
+
+## v0.1.7 · 23/10/2026
+
+Loops controláveis, comparadores de arrays, regex isolada, decimais exatos e busca pela CLI, com o conteúdo preparado na 0.1.6. Esta atualização da biblioteca Yuzuha foi preparada em 23/10/2026 (v0.1.7).
+
+- `yuzuha functions --search <termo>` filtra nomes, aliases e descrições por trecho, sem distinguir maiúsculas e minúsculas. Aceita `$` inicial e combina com categoria, JSON, exportação de catálogo e filtros de plugins, preservando a ordem dos resultados.
+- Buscas sem resultados encerram com sucesso e retornam uma mensagem no terminal ou uma lista vazia em JSON. Termos vazios, ausentes ou repetidos são recusados; categorias desconhecidas continuam sendo erros.
+- Consultas paginadas de variáveis por prefixo, com TTL e cursor; índice SQLite derivado do snapshot e invalidado por trigger. Streaming UTF-8 em scripts, com backpressure, controle de loop e cancelamento.
+- `yuzuha/images` adiciona transformação opcional de PNG/JPEG/WebP com Sharp em processos limitados e canceláveis. `ctx.sendStream` lê anexos com orçamento e prazo antes do upload de bytes exigido pelo SDK.
+- Auditoria de integrações documenta configuração de shards já suportada pelo core, gerenciamento externo de processos e ausência de contratos para componentes/comandos de aplicação.
+- Tarefas aceitam prioridade persistida; `globalConcurrency` coordena claims no store compartilhado, preservando o limite local.
+- **18 funções novas**, totalizando **306**: `guildFeatures`, `leaveGuild`, `while`, `break`, `continue`, `arraySortWith`, `sortLeft`, `sortRight`, `regexTest`, `regexMatch`, `regexReplace`, `decimal`, `decimalCompare`, `decimalRound`, `queryVars`, `httpStream`, `httpChunk` e `httpChunkIndex`.
+- `ctx.guildFeatures()` copia as features do servidor; `ctx.leaveGuild()` só permite a saída solicitada pelo dono do servidor, com a mesma autorização nos scripts. Ports customizados antigos continuam válidos; ausência do recurso retorna `NATIVE_UNAVAILABLE`.
+- Loops restauram o contexto ao sair; `break` e `continue` atravessam `$try` e afetam o corpo do loop mais próximo. Comparadores usam ordenação estável e orçamento compartilhado. Decimais retornam texto e usam até 1000 dígitos, sem perda por `Number`.
+- Regex roda em workers limitados, com cancelamento, prazo e limites de entrada, correspondências e saída. O worker é incluído no tarball e não executa JavaScript fornecido pelo script.
+- Inclui as otimizações de dispatch, runtime e estado, as APIs nativas de música, a integração Lavalink v4 e a ponte de áudio descritas na entrada 0.1.6. SDK 3.3.0, schema 2 e imports anteriores permanecem compatíveis.
+- Erros do gateway e de shards chegam aos hooks `onError`/`onLog` mesmo sem listeners do usuário. Os listeners padrão permanecem ativos durante o encerramento e preservam os listeners de clients injetados.
+- O parser salta trechos de texto comum mantendo offsets, escapes e diagnósticos. A limpeza de `$httpStream` não bloqueia o comando quando a fonte deixa o cancelamento pendente.
+- Biblioteca e CLI voltam à raiz do repositório, com instalação npm, guias Markdown e exemplos incluídos no pacote. O site fica arquivado para uma etapa futura.
+
+## v0.1.6 · 22/10/2026
+
+Dispatch, argumentos, runtime e leituras de estado mais rápidos, com ferramentas nativas para música e integração Lavalink v4. Esta atualização da biblioteca Yuzuha foi preparada em 22/10/2026 (v0.1.6).
+
+- Deduplicação usa uma fila circular de 10000 entradas; mensagens ignoradas seguem um caminho curto. Prefixos estáticos são reaproveitados, o sinal de encerramento é compartilhado e serviços, mapas de argumentos e variáveis do contexto são criados sob demanda.
+- Registro individual de comandos valida conflitos antes de inserir, sem copiar todo o catálogo. Carga e recarga continuam atômicas. Argumentos simples usam tokenização por trechos; o caminho de aspas/apóstrofos evita inspecionar repetidamente a palavra em construção. Escapes, flags e erros de entrada são preservados.
+- Parser acumula trechos de texto; evaluator evita promises para literais e resolve funções com cache fraco por AST. A validação continua ativa para ASTs externos ou editados, com ordem, tipos, guards, orçamento e falhas parciais preservados.
+- Leituras pontuais em memória e JSON copiam somente o valor solicitado e respeitam TTL e ordenação das transações. Stores próprios conservam o caminho anterior; `readVariable` é uma capacidade opcional. SQLite reutiliza statements sem alterar schema, WAL ou validação antes do commit.
+- `yuzuha/music` entrega cliente Lavalink v4 com REST/WebSocket autenticados, retomada de sessão, reconexão limitada, cancelamento, limite de respostas/requisições, cache LRU com orçamento de bytes e compartilhamento de buscas simultâneas.
+- Gerenciador de música com distribuição de novos players entre nodes disponíveis, filas limitadas por servidor, avanço automático, loop, pause, skip, stop, seek, volume e filtros. Controles e eventos são serializados; falhas de PATCH preservam as faixas pendentes.
+- Sessões Lavalink perdidas são reconstruídas com concorrência limitada, posição, pausa, filtros e renovação de voz. Sessões retomadas preservam a reprodução; eventos aguardam a confirmação do handshake. Respostas antigas não alteram a fila.
+- Filas permitem remover, mover, embaralhar e consultar páginas sem copiar todo o catálogo. Controles pendentes são limitados por player; eventos de fim mantêm capacidade reservada. Nodes consideram CPU, players e frames ao distribuir carga; saídas pelo plugin ignoram os contadores de voz Discord, evitando perda falsa no balanceamento.
+- Buscas com signals distintos compartilham a requisição, com cancelamento por chamada e aborto quando todos desistem. Decode de faixas/lotes e diagnósticos de cache/rede completam a API; parsing de flags evita mapas e objetos temporários por valor.
+- `FluxerVoice` carrega `@fluxerjs/voice` opcionalmente para áudio WebM/Opus nativo. `ctx.voice` e `ctx.music` recebem serviços configurados e participam do encerramento.
+- `FluxerLavalinkBridge` e o plugin `yuzuha-audio` conectam a saída Opus do Lavalink 4.2.2 ao SDK do Fluxer. Mantêm uma publicação entre faixas, pausa, seek e filtros; transmissão incremental, limites, cancelamento e reconexão liberam os recursos por servidor. A integração local usa áudio e decoder reais, com publicação LiveKit simulada.
+- `MockMusicBackend`, `mockTrack`, exemplo offline, guia de música e benchmarks adicionais acompanham a versão. Relatórios anteriores/atuais e método estão em [BENCHMARKS.md](docs/BENCHMARKS.md). SDK 3.3.0, schema 2 e 288 funções de script permanecem compatíveis.
+
 ## v0.1.5 · 22/10/2026
 
 Subcomandos e flags tipadas, ajuda derivada das definições e testes nativos com relógio controlável, com projetos gerados prontos para compartilhar. Esta atualização da biblioteca Yuzuha foi preparada em 22/10/2026 (v0.1.5).

package/README.md

@@ -1,159 +1,215 @@
 # Yuzuha
 
-Framework para bots do Fluxer: a ergonomia que falta no Fluxer.js, com comandos
-tipados, guards, estado, moderação, agendamentos e testes offline. Function mode
-(scripts no estilo ForgeScript) é opcional. Versão **0.1.5**.
+Framework TypeScript para bots do [Fluxer](https://fluxer.app), com comandos
+tipados em JavaScript/TypeScript e uma linguagem opcional de scripts.
+Os dois modos compartilham permissões, moderação, estado e recursos.
 
-```ts
-import { arg, defineCommand, Yuzuha } from 'yuzuha';
+O Yuzuha usa **Fluxer.js 3.3.0**. Você continua tendo acesso ao client original
+por `bot.client` e aos exports do SDK em `yuzuha/sdk`.
 
-const bot = new Yuzuha({ name: 'meu-bot', prefix: '!' });
+[0.2.0](CHANGELOG.md) · Node **22.13+** · ESM · [MIT](LICENSE)
 
-bot.command(defineCommand({
-  name: 'ban',
-  description: 'Bane um membro e registra um caso.',
-  args: {
-    membro: arg.user().required(),
-    motivo: arg.text().rest(),
-  },
-  async run(ctx) {
-    const caso = await ctx.mod.ban(ctx.args.get('membro'), {
-      reason: ctx.args.get('motivo') ?? '',
-    });
-    await ctx.reply(`Membro banido. Caso #${caso.id}.`);
-  },
-}));
+[Começar](#começar) · [Comandos](#escrever-comandos) · [Recursos](#recursos) · [Testes](#testar-sem-token) · [Documentação](#documentação)
+
+## Começar
+
+### Criar um bot
+
+```sh
+npx yuzuha@0.2.0 init ./meu-bot --ts
+cd meu-bot
+npm install
+npm run check
+npm run typecheck
+npm test
+cp .env.example .env
+```
+
+Preencha `FLUXER_BOT_TOKEN` no `.env` e inicie o bot:
 
-await bot.login();
+```sh
+npm run dev
 ```
 
-Uso: `!ban @membro spam no chat`. `ctx.mod.ban` verifica permissões e hierarquia,
-executa o banimento e registra o caso. O token vem de `FLUXER_BOT_TOKEN`.
-`bot.client` continua sendo o client real do Fluxer.js.
+O projeto inclui três comandos, configuração e um teste offline. Para JavaScript,
+troque `--ts` por `--js` e omita `typecheck`. Acrescente `--functions` ao `init`
+para incluir um comando de exemplo com scripts.
+
+`npm run check`, `npm run typecheck` e `npm test` validam o projeto sem conectar o bot.
+`npm run dev` conecta e recarrega os arquivos de comando ao editar;
+`npm start` executa sem recarga automática.
 
-## O que o Yuzuha adiciona ao Fluxer.js
+### Usar em um projeto existente
+
+```sh
+npm install yuzuha@0.2.0
+```
 
-- Comandos com prefixos, subcomandos, flags e argumentos tipados, cooldowns e permissões.
-- Ajuda com uso, escolhas e exemplos a partir das definições dos comandos.
-- Guards, middleware, plugins, eventos tipados e recarga de comandos sem reiniciar.
-- Moderação compartilhada (ban, kick, timeout, unban) com casos por servidor.
-- Recursos prontos: usuários, cargos, canais, mensagens, convites, webhooks,
-  emojis, stickers, threads e fóruns, incluindo reações, membros de threads,
-  posição de cargos/canais e categorias.
-- Estado em memória, JSON ou SQLite, com transações e variáveis por escopo.
-- Agendamentos persistentes com cron, fuso IANA, concorrência e retry com jitter.
-- HTTP textual/binário, streaming e multipart, com limites e políticas por comando.
-- `createTestBot`, relógio controlável, `MockTransport` e stores isolados para testar sem token.
-- Transações entre chaves, agendamentos editáveis com pausa/retry e apelidos com autorização compartilhada.
-- Limpeza de expirados, estatísticas e backup/restauração versionados com simulação.
-- `doctor`, lint JSON, cenários offline, catálogos de plugins e extensão VS Code.
-- SDK `@fluxerjs/core` **3.3.0** reexportado em `yuzuha/sdk`, sem esconder o original.
+Use `"type": "module"` no `package.json`. O [guia inicial](docs/QUICKSTART.md)
+mostra como configurar o bot e carregar comandos.
 
-Não é um fork do Fluxer.js nem um wrapper de todos os métodos do SDK. O que não
-estiver no framework continua acessível por `bot.client` e pelos tipos originais.
+## Escrever comandos
 
-## Function mode (opcional)
+Salve **uma das versões** abaixo em `commands/eco.ts` (`.js` para JavaScript).
+Ambas respondem a `!eco Olá, Yuzuha!` com `Olá, Yuzuha!`.
 
-Quem preferir a sintaxe curta do ForgeScript pode usar `yuzuha/functions`. O
-runtime é ativado quando um comando com `code` ou um evento de script é registrado.
+### JavaScript / TypeScript
 
 ```ts
-import { script } from 'yuzuha/functions';
-import { Yuzuha } from 'yuzuha';
+import { arg, defineCommand } from 'yuzuha';
+
+export default defineCommand({
+  name: 'eco',
+  description: 'Repete o texto informado.',
+  args: { texto: arg.text().rest().required() },
+  async run(ctx) {
+    await ctx.reply(ctx.args.get('texto'));
+  },
+});
+```
+
+Schemas `arg.*` inferem os tipos de argumentos e flags. Você também pode declarar
+subcomandos, checks e middleware. O [guia nativo](docs/NATIVE.md) cobre esses
+contratos, eventos, moderação e persistência.
+
+### Function mode do Yuzuha
 
-const bot = new Yuzuha({ prefix: '!' });
+```ts
+import { script } from 'yuzuha/functions';
 
-bot.command(script({
-  name: 'ban',
-  code: '$modBan[$mentioned[1];$messageSlice[1]]$reply[Membro banido. Caso #$caseID.]',
-}));
+export default script({
+  name: 'eco',
+  description: 'Repete o texto informado.',
+  code: '$reply[$messageSlice[0]]',
+});
 ```
 
-Os dois modos compartilham guards, estado, moderação e recursos. São
-**288 funções** com referência gerada, ou use `bot.enableFunctions()` para
-pré-carregar o runtime.
+O function mode tem **336 funções** para mensagens, guards, moderação, variáveis,
+JSON, arrays, loops, eventos e agendamentos. O runtime é ativado ao registrar um
+comando com `code` ou um evento de script.
 
-`bot.scriptEvent()` registra scripts para entrada/saída de membros, edição/exclusão
-de mensagens e reações. O contexto preserva os dados disponíveis do evento e exige
-um canal real para enviar respostas. Veja [eventos](docs/EVENTS.md).
+As funções seguem as assinaturas e regras do runtime do Yuzuha. Consulte a
+[linguagem](docs/LANGUAGE.md), as [assinaturas das funções](docs/FUNCTIONS.md)
+e a [cobertura](docs/PARITY.md).
 
-## Instalar pelo npm
+## Recursos
 
-Requer Node **22.13 ou mais recente**. O pacote é ESM; use `"type": "module"`
-no `package.json` do seu projeto.
+| Área | O que está disponível |
+|---|---|
+| Comandos | Prefixos, aliases, subcomandos, argumentos e flags tipadas, cooldowns e ajuda gerada dos metadados |
+| Extensões | Plugins, eventos, checks, middleware e recarga atômica de comandos |
+| Moderação | Ban, kick, timeout, unban e moderação de voz, com permissões, hierarquia e casos por servidor |
+| Fluxer | Usuários, membros, cargos, canais, mensagens, reações, anexos, threads, convites, webhooks e expressões |
+| Dados | Memória, JSON e SQLite; TTL, transações, limpeza e backup/restauração com simulação |
+| Agendamentos | Tarefas persistentes, cron, fusos IANA, pausa/retomada, histórico e retry |
+| HTTP | Texto, bytes, streaming e multipart, com limites, cancelamento e políticas por comando |
+| Canvas | Cartões com texto, avatares, imagens, gradientes, badges e progresso; peer nativo opcional |
+| Música | Lavalink v4 com plugin e ponte de áudio para Fluxer, recuperação, filas editáveis, loop, seek, volume e filtros |
+| Desenvolvimento | CLI, autocomplete e diagnósticos no VS Code, mocks e relógio controlável para testes |
+
+## Testar sem token
+
+O scaffold já inclui um teste executável com `npm test`. Para testar o comando
+`eco` acima, crie `test/eco.test.ts` (`.js` para JavaScript):
 
-```sh
-npm install yuzuha@0.1.5
+```ts
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createTestBot } from 'yuzuha/testing';
+import eco from '../commands/eco.js';
+
+test('eco responde com o texto informado', async t => {
+  const fixture = createTestBot({ commands: [eco] });
+  t.after(() => fixture.destroy());
+
+  assert.equal(await fixture.send('!eco Olá, Yuzuha!'), 'success');
+  assert.equal(fixture.messages.at(-1)?.payload.content, 'Olá, Yuzuha!');
+});
 ```
 
-Para gerar um bot novo:
+`createTestBot` usa transporte e recursos simulados, com estado isolado. O relógio
+controlável permite testar cooldown, TTL e tarefas sem aguardar tempo real.
+Veja fixtures, stores e cenários na [documentação de testes](docs/TESTING.md).
 
-```sh
-npx yuzuha@0.1.5 init ./meu-bot --ts
-cd meu-bot
-npm install
-npm run check
-npm run typecheck
-npm test
-cp .env.example .env
-```
+## CLI
+
+Execute estes comandos no diretório do seu bot:
+
+| Comando | Uso |
+|---|---|
+| `npx yuzuha check` | Validar configuração e comandos sem login |
+| `npx yuzuha doctor` | Diagnosticar ambiente, configuração e store |
+| `npx yuzuha lint commands --json` | Analisar scripts sem importar módulos |
+| `npx yuzuha functions --category moderation` | Consultar funções e assinaturas |
+| `npx yuzuha functions --search mensagem` | Buscar funções por nome, alias ou descrição |
+| `npx yuzuha editor` | Encontrar a extensão VS Code incluída no pacote |
 
-`init` declara a dependência npm e gera um teste offline. O projeto pode ser
-movido e compartilhado sem depender do caminho da instalação que o criou.
-Para JavaScript, use `--js` e omita `typecheck`.
-Para acrescentar um exemplo de script, use `--functions`.
+`check` importa configurações e comandos JS/TS de confiança; a verificação de
+tipos é feita por `npm run typecheck`. A [referência da CLI](docs/CLI.md) também cobre
+catálogos de plugins, cenários offline e manutenção de dados.
 
-Preencha `FLUXER_BOT_TOKEN` no `.env` e execute `npm run dev`.
+## Documentação
+
+O [índice completo](docs/README.md) reúne os guias e as referências.
+
+| Quero… | Ler |
+|---|---|
+| Criar e configurar um bot | [Guia inicial](docs/QUICKSTART.md) |
+| Programar em JS/TS | [Guia nativo](docs/NATIVE.md), [framework](docs/FRAMEWORK.md) e [API](docs/API.md) |
+| Criar um bot de música | [Lavalink, filas e voz Fluxer](docs/MUSIC.md) |
+| Medir performance | [Benchmarks e comparações com a 0.1.5](docs/BENCHMARKS.md) |
+| Compor cartões e imagens | [Canvas](docs/CANVAS.md) e [transformações de imagem](docs/IMAGES.md) |
+| Escrever scripts `$...` | [Linguagem](docs/LANGUAGE.md) e [referência de funções](docs/FUNCTIONS.md) |
+| Copiar exemplos | [Receitas](docs/COOKBOOK.md) e [código de exemplo](examples) |
+| Usar o editor ou diagnosticar um erro | [VS Code](docs/EDITOR.md) e [problemas comuns](docs/TROUBLESHOOTING.md) |
+| Entender a cobertura | [Paridade](docs/PARITY.md) e [funções ausentes](docs/FUNCTION-GAPS.md) |
+| Conferir mudanças e validação | [Changelog](CHANGELOG.md), [versionamento](VERSIONING.md) e [evidências](docs/VALIDATION.md) |
 
-## Desenvolver a biblioteca localmente
+## Desenvolver a biblioteca
+
+Na cópia do repositório:
 
 ```sh
-cd ~/Projects/yuzuha
+git clone https://github.com/horizzon3507/yuzuha.git
+cd yuzuha
 npm ci
-npm run build
-node dist/cli.js init ~/Projects/meu-bot --ts --local
-cd ~/Projects/meu-bot
-npm install
 npm run check
-npm run typecheck
-cp .env.example .env
+npm run smoke:package
 ```
 
-O scaffold desse fluxo usa a biblioteca local. O
-[guia inicial](docs/QUICKSTART.md) explica instalação e configuração.
-
-## Experimentar sem token
+Para experimentar os exemplos offline:
 
 ```sh
 npx tsx examples/offline.ts
 npx tsx examples/function-mode.ts
-node dist/cli.js check examples/yuzuha.config.js --json
-node dist/cli.js functions --category moderation
 ```
 
-Os exemplos usam `MockTransport`; nenhuma ação chega ao Fluxer. `check` importa
-config e comandos JS/TS de confiança, valida os scripts e não chama `login`.
-Ele não substitui o typecheck do TypeScript.
+Para gerar um bot que use sua instalação local da biblioteca:
 
-## Documentação
+```sh
+node dist/cli.js init ../meu-bot-local --ts --local
+```
 
-Comece pelo [índice da documentação](docs/README.md).
+O `init` usa a dependência npm por padrão; `--local` aponta para a instalação
+que executa a CLI. Veja [contribuição](CONTRIBUTING.md) para as regras de código
+e as verificações do projeto.
 
-| Preciso de… | Documento |
-|---|---|
-| Criar meu primeiro bot JS ou TS | [Guia inicial](docs/QUICKSTART.md) |
-| Programar comandos, eventos e plugins | [Guia nativo JS/TS](docs/NATIVE.md) |
-| Escrever scripts `$...` | [Function mode](docs/LANGUAGE.md) e [referência](docs/FUNCTIONS.md) |
-| Saber quais funções de script existem | [Lacunas auditadas](docs/FUNCTION-GAPS.md) |
-| Usar comandos, contexto e extensões | [Framework](docs/FRAMEWORK.md) e [API](docs/API.md) |
-| Copiar exemplos completos | [Receitas](docs/COOKBOOK.md) |
-| Usar a linha de comando | [CLI](docs/CLI.md) |
-| Entender módulos e dependências | [Arquitetura](docs/ARCHITECTURE.md) |
-| Escolher persistência e tratar falhas | [Estado e execução](docs/STORAGE.md) |
-| Diagnosticar ou testar | [Problemas comuns](docs/TROUBLESHOOTING.md) e [testes](docs/TESTING.md) |
-| Usar autocomplete e diagnóstico offline | [Editor e doctor](docs/EDITOR.md) |
-| Medir dispatch, runtime e memória | [Benchmarks](docs/BENCHMARKS.md) |
-| Ver evidência local | [Validação](docs/VALIDATION.md) |
-
-As mudanças estão no [changelog](CHANGELOG.md); a política de versões está em
-[VERSIONING.md](VERSIONING.md). Leia [CONTRIBUTING.md](CONTRIBUTING.md) para contribuir.
+Transformações opcionais de imagens e entrada de anexos por stream estão em
+[IMAGES.md](docs/IMAGES.md); consultas por prefixo e cursor em
+[STORAGE.md](docs/STORAGE.md), e limites das integrações em
+[INTEGRATIONS.md](docs/INTEGRATIONS.md).
+
+### Bases de bots
+
+Sete opções: `simple`, `multifunctional`, `moderation`, `community`, `economy`,
+`entertainment` e `utility`. Na cópia local compilada:
+
+```sh
+node dist/cli.js templates
+node dist/cli.js init ../bot-comunidade --template community --ts --local
+```
+
+A multifuncional reúne 24 comandos raiz com embeds e subcomandos, incluindo
+moderação com casos, regras, sugestões, enquetes, moedas virtuais, diversão
+e notas pessoais em DM. Todas as bases aceitam JS/TS e `--functions`, com README
+e testes offline próprios. Veja [BOT-BASES.md](docs/BOT-BASES.md).

package/VERSIONING.md

@@ -1,16 +1,16 @@
 # Versionamento
 
 O Yuzuha aplica o formato Hory ao histórico e usa **SemVer simples** no pacote.
-A versão desta atualização é **0.1.5**.
+A versão desta atualização é **0.2.0**.
 
 ## Pacote e histórico
 
 | Lugar | Formato nesta versão |
 |---|---|
-| `package.json` e raiz do `package-lock.json` | `0.1.5` |
-| Pacote npm e saída de `yuzuha --version` | `0.1.5` |
-| Título do changelog | `## v0.1.5 · 22/10/2026` |
-| Eventual tag Git | `v0.1.5` |
+| `package.json` e entrada raiz de `package-lock.json` | `0.2.0` |
+| Pacote npm e saída de `yuzuha --version` | `0.2.0` |
+| Título do changelog | `## v0.2.0 · 02/11/2026` |
+| Tag Git | `v0.2.0` |
 
 O SDK e a CLI pertencem ao mesmo pacote. Para bibliotecas, a convenção Hory mantém
 SemVer sem `m`, sem seções por superfície e sem sufixos de canal.
@@ -30,7 +30,8 @@ estivermos em `0.x`. Ao chegar a `1.0.0`, mudanças incompatíveis exigem major;
 novas funcionalidades compatíveis, minor; correções compatíveis, patch.
 
 Os exports públicos são `yuzuha`, `yuzuha/functions`, `yuzuha/sdk`,
-`yuzuha/testing` e `yuzuha/tooling`. A organização interna de `src/` não cria estabilidade de deep
+`yuzuha/testing`, `yuzuha/tooling`, `yuzuha/music`, `yuzuha/images` e
+`yuzuha/canvas`. A organização interna de `src/` não cria estabilidade de deep
 imports. Schema persistido,
 gramática e funções documentadas também fazem parte da compatibilidade.
 
@@ -40,6 +41,117 @@ gerado por `init` pertence ao consumidor e não precisa acompanhar a biblioteca.
 
 ## Preparar uma atualização
 
+### Migrar para 0.2.0
+
+A 0.2.0 acrescenta campos a `Embed` (`url`, `timestamp`, `author`, `footer.iconURL`,
+alt text em imagem e miniatura), `allowedMentions`, `tts`, `stickerIds`, `flags` e
+`reply` em `Payload`, além de 14 funções de script e a leitura normalizada de embeds
+em `$fetchMessage` e `$messages`. Os exports públicos continuam os mesmos.
+
+Há duas mudanças de contrato, por isso a versão é minor na série `0.x`:
+
+- `MessageInfo.embeds` passou a ser obrigatório. Quem implementa `MessagesResources`
+  própria deve devolver `embeds` (use `[]` se não houver embeds).
+- Objetos de mensagem em script (`$reply`, `$sendMessage`, `$editMessage`) aceitam
+  somente as chaves `content`, `embeds`, `tts`, `stickerIds`, `flags` e `allowedMentions`.
+  Antes, qualquer objeto virava embed sem validação; agora campos desconhecidos são erro.
+
+Menções só relaxam com a permissão `MentionEveryone` do autor, e TTS exige
+`SendTtsMessages`. O padrão continua sem menções e sem ping ao autor respondido.
+
+```sh
+npm install yuzuha@0.2.0
+```
+
+### Migrar para 0.1.9
+
+A 0.1.9 acrescenta `yuzuha/canvas`, `ctx.canvas` e `bot.contextEvent`, além de
+12 funções de script da categoria `canvas`. O pacote continua utilizável sem
+Canvas; para renderizar, instale `@napi-rs/canvas@^1.0.13`. Sem o peer, somente
+a chamada de renderização falha com `CANVAS_DEPENDENCY`. Sharp continua sendo
+opcional e independente. O envio usa `resources.messages.sendBytes` e eventos
+sem canal precisam fornecer `channelID` em `ctx.canvas.send`.
+
+`CanvasConfig` pode registrar bytes de assets e fontes TTF/OTF. As respostas
+HTTP continuam sujeitas à política e ao limite configurado no bot. Canvas e
+transformações Sharp compartilham duas vagas de processo. O schema persistido
+permanece em 2 e o SDK em 3.3.0; não há migração de dados.
+
+```sh
+npm install yuzuha@0.1.9 @napi-rs/canvas@^1.0.13
+```
+
+Veja [CANVAS.md](docs/CANVAS.md) para opções, limites, fontes e exemplos. A
+extensão incluída acompanha a versão 0.1.9.
+
+### Migrar para 0.1.8
+
+A 0.1.8 é uma exceção pontual à regra de versões minor para mudanças de
+contrato na série 0.x. Embora use numeração patch, requer adaptação de
+implementações completas próprias de `Resources` e revisão das autorizações
+de comandos. A regra de compatibilidade acima continua valendo para as
+próximas versões.
+
+- Acrescente `messages.pinnedPage`, `messages.reactionUsersPage` e
+  `threads.member` aos adaptadores completos. Os tipos de retorno são
+  `PinnedMessagesPage`, `ReactionUsersPage` e `ThreadMemberDetails`, exportados
+  pela raiz. `mockResources` continua aceitando overrides parciais.
+- Mutações de emojis/stickers por `ctx.resources.expressions` exigem
+  `ManageExpressions` de autor e bot no servidor do contexto. Código confiável
+  que precisa operar diretamente com a autoridade do bot continua usando
+  `bot.resources` ou `bot.client` explicitamente.
+- HTTP recusa credenciais embutidas na URL, corpos GET/HEAD e destinos nas
+  redes locais/especiais bloqueadas, incluindo IPv4 mapeado em IPv6. Use
+  `Authorization` para autenticação; rede privada exige `allowPrivate: true`
+  explícito. Redirects 301/302 preservam PUT/PATCH/DELETE e 303 preserva HEAD;
+  cabeçalhos de conteúdo são removidos quando o corpo é descartado.
+- As opções de busca recebem validação compartilhada de tipos, IDs, cursores
+  e limites. Texto é opcional na API nativa e em `$searchMessagesAdvanced`;
+  `$searchMessages` mantém sua assinatura e aceita cursor vazio.
+- O catálogo passa a 310 funções. Imports, SDK 3.3.0 e schema 2 permanecem;
+  não há migração de dados em disco. As sete bases da CLI são aditivas e não
+  reescrevem projetos existentes. A extensão incluída acompanha a versão 0.1.8.
+
+### Migrar para 0.1.7
+
+A distribuição 0.1.7 inclui o conteúdo preparado na 0.1.6 e acrescenta
+`yuzuha functions --search <termo>`. A busca combina com os filtros e formatos
+existentes sem alterar imports anteriores, schema 2 ou SDK 3.3.0.
+A linguagem recebe 18 funções, chegando a 306. `GuildInfo.features` e
+`UsersResources.leaveGuild` são opcionais para preservar recursos customizados;
+os novos auxiliares do contexto recusam recursos ausentes explicitamente.
+O port `Store.queryVariables` também é opcional; memória/JSON mantêm fallback
+por snapshot. SQLite cria um índice derivado automaticamente na primeira consulta,
+sem alterar schema 2. Prioridade padrão é zero e capacidade compartilhada só é
+ativada com `globalConcurrency`. `yuzuha/images` requer instalar Sharp; o restante
+da biblioteca continua independente dele. Não há mudanças obrigatórias nos bots
+existentes.
+As instruções da 0.1.6 abaixo continuam aplicáveis ao atualizar da 0.1.5.
+
+### Migrar para 0.1.6
+
+Imports, schema 2, SDK 3.3.0 e 288 funções permanecem disponíveis. Os serviços do
+contexto e seus mapas são inicializados sob demanda; as referências devolvidas
+continuam estáveis por contexto. Mensagens ignoradas não criam uma execução.
+O sinal de cancelamento pode ser compartilhado entre comandos do mesmo bot;
+não dependa de sua identidade para correlacionar execuções: use `executionID`.
+
+`Store.readVariable` é opcional e deve retornar uma cópia isolada, respeitar a
+ordenação das transações e avaliar o callback de relógio `now` dentro da leitura,
+após aguardar operações anteriores. `undefined` indica
+ausente/expirado; `null` continua sendo um valor JSON válido. Não há migração de
+disco. SQLite conserva validação do estado completo antes de cada commit.
+
+`yuzuha/music` é um import adicional. Configure `music`/`voice` explicitamente;
+o bot encerra os serviços fornecidos e o chamador fecha os nodes Lavalink.
+`@fluxerjs/voice` é um peer opcional carregado em `join`. Para áudio Lavalink no
+Fluxer, configure `FluxerLavalinkBridge` e instale o plugin `yuzuha-audio` fornecido
+pelo Yuzuha no servidor; veja [MUSIC.md](docs/MUSIC.md).
+Não há wrappers de música no function mode nesta versão.
+
+Benchmarks agora exigem a versão exata do Node e o mesmo modo de GC, suíte e
+carga. Relatórios de outro runtime devem ser executados novamente antes de comparar.
+
 ### Migrar para 0.1.5
 
 Imports, argumentos posicionais e comandos existentes continuam disponíveis.
@@ -133,7 +245,7 @@ externos para idempotência. Veja [NATIVE.md](docs/NATIVE.md) e
 
 ### Procedimento
 
-1. Atualize manifest e lockfile para a mesma versão.
+1. Atualize `package.json` e regenere `package-lock.json` para a mesma versão.
 2. Acrescente a entrada no [CHANGELOG.md](CHANGELOG.md), com data real e mudanças verificáveis.
 3. Atualize migração, cobertura e documentação quando o contrato mudar.
 4. Rode `npm run check` e `npm run smoke:package` e registre a evidência.