Guia Web

Porta fixa e sessãoCopiar link da âncora

O login guarda sessão por origin (inclui porta), seja Supabase Auth ou Firebase Auth. kasy run --web usa 5555 para a sessão persistir entre execuções.

Escala viewport (0.93)Copiar link da âncora

Flutter Web renderiza ~10% maior que o equivalente nativo. O kit aplica escala 0.93 na web para ficar alinhado ao design mobile.

Knobs em lib/core/web_viewport_scale.dart:

const bool kWebViewportScaleEnabled = true;
const double kWebViewportScale = 0.93;

Nativo nunca escala (kIsWeb). Device preview desliga escala para simular tamanho real do celular.

Quanto mais perto de 1.0, maior fica tudo:

A escala vale em todos os breakpoints da web, então não existe salto de tamanho ao cruzar um breakpoint. Ela também não substitui o design responsivo: desligue o knob e o app continua com breakpoints, tipografia responsiva e layouts adaptativos funcionando, só ~7% maior.

No desktop existe uma compensação a mais: se a tela do Mac/Windows estiver com escala de sistema alta, o app comprime além do 0.93 para não cortar o layout. A conta usa a largura da tela, não a da janela, então estreitar a janela do navegador só refluí o layout, não encolhe. O limite de desktop é a constante kWebViewportScaleDesktopBreakpoint (1024px) no mesmo arquivo.

Device preview (debug)Copiar link da âncora

control/ctrl + shift + d liga o frame de iPhone/iPad no navegador (debug). No Mac use control (⌃), não command (⌘). Inspector: control/ctrl + shift + i. Também listados em Admin → Visão geral → Preview.

Na primeira vez (projeto novo ou storage limpo), o fundo do preview e o tema do app dentro da moldura seguem o modo do sistema (claro/escuro do macOS/Windows). O botão sol/lua no canto inferior direito muda só o canvas atrás do device; o ícone sol/lua na barra do preview muda o tema do app. As duas escolhas são salvas no localStorage e voltam iguais no próximo kasy run --web.

Fundo da página no reloadCopiar link da âncora

Em release isso não existe, porque o preview só roda em debug na web: o fundo sempre segue o tema do app. Por baixo, o preview grava a decisão já resolvida na chave kasy.web_preview_chrome (dark, light ou off), e o script de boot do web/index.html lê só essa chave no arranque.

Onboarding e autenticaçãoCopiar link da âncora

O preview não muda só o tamanho da moldura. Ele também define qual fluxo de auth você está testando no kasy run --web:

Layout ≠ fluxo. Abrir o app no Safari do iPhone ou no Chrome do tablet usa os breakpoints mobile/tablet (UI responsiva), mas o comportamento de conta continua sendo o da web: login obrigatório, sem onboarding, sem guest anônimo. Isso é intencional no preset SaaS do kit: trial, assinatura (RevenueCat/Stripe) e suporte precisam de um usuário identificável.

Use o preview em iOS / Android / iPad quando quiser validar onboarding, paywall, conta anônima e skip sem abrir simulador. Na web publicada (mobile incluído), o padrão é pedir conta antes de usar o app.

Navegação dentro do app: em Configurações → Cadastrar (ou Entrar), o preview mobile/tablet mostra a seta voltar igual ao nativo quando a rota foi aberta com push. No preview Desktop ou na web sem frame, essa seta some (entrada direta em /signin ou /signup).

Supabase: depois do loader ("criando sua conta"), confira em Authentication → Users. Se o dropdown da busca estiver em Email address, usuários anônimos somem da lista (não têm e-mail). Use Unified search ou busque pelo User ID de public.users. Detalhes em Troubleshooting.

Rota /onboardingCopiar link da âncora

O GoRouter controla quem pode ficar em /onboarding:

Não cria conta duplicada: se já existe ID no backend (login ou guest anônimo), o loader pula a criação de anônimo. Só a primeira instalação sem ID cria guest no fim do fluxo.

Ver o onboarding de novo no devCopiar link da âncora

Na aba normal do navegador (incluindo o browser do Cursor), o kit lembra coisas entre reloads:

Por isso a aba anônima parece "funcionar": storage vazio = primeiro acesso de novo. O kasy clear-web e o kasy reset --web abrem a URL ?kasy_clear_storage=1 no seu navegador padrão (macOS, Windows e Linux). Essa URL zera localStorage, sessionStorage e IndexedDB (sessão do Firebase Auth na web fica no IndexedDB).

Opções sem anônimo:

1. Admin → Testar onboarding (/onboarding?preview=true): percorre todas as telas sem criar guest, sem gravar perfil e sem prompts reais. Volta pro Admin no fim. Em release, só admin (ou debug). Bom pra layout e copy.
2. Primeiro acesso real de novo: kasy clear-web (com kasy run --web ativo), kasy run --web --open-browser --fresh, aba anônima/privada, ou limpar site data do localhost:5555 no DevTools → Application. No MCP: run_app com freshStorage=true ou clear_web_storage. Com device preview em aba iOS/Android/iPad, cai no onboarding.
3. URL direta: /onboarding?preview=true só em debug ou como admin. O fluxo real (/onboarding sem query) só na primeira instalação; sessão estabelecida vai pra Home.

Hot reload e hot restart (r / R)Copiar link da âncora

No kasy run --web, você atualiza o build de duas formas:

Não use R só por mudança visual: é mais lento e zera formulários, navegação e sessão guest.

Quem manda r / RCopiar link da âncora

Dev humano: toolbar ou terminal quando quiser. IA: regras completas em Orientação para IA (documentação do site, não a landing page).

Navegação por IA (Browser QA)Copiar link da âncora

Flutter Web pinta a tela inteira em canvas, sem tratamento especial, um agente de IA no navegador (Cursor, Claude, Playwright) não enxerga botão nem campo de texto como enxergaria numa página React comum, só pixels.

O kit resolve isso ligando a árvore de semantics do Flutter em toda build de debug/profile (nunca em produção) e instalando uma ponte JS (window.__kasyBrowserQa) que permite ao agente clicar e digitar sem depender do hit-test do DOM:

if (!kReleaseMode) {
  SemanticsBinding.instance.ensureSemantics();
  installBrowserQaBridge();
}

Com isso ligado, um agente de IA consegue ler a página como uma árvore de acessibilidade normal (nome de cada botão, campo, switch) e chamar:

• window.__kasyBrowserQa.click(label) pra tocar um controle pelo nome (não depende de browser_click no DOM)
• window.__kasyBrowserQa.setTextIn(label, valor) pra digitar num campo pelo nome
• window.__kasyBrowserQa.exists(label) / go(path) pra assert e navegação

A ponte também neutraliza overlays flt-semantics de tela cheia no DOM, então browser_click por ref continua como fallback. Não invente pointer-events à mão.

Roteiro do agente (reload r/R, terminal, snapshot, click / setTextIn): Orientação para IA e docs/agent-browser-qa.md no projeto. MCP: browser_qa_guide. Requer kasy-cli ≥ 1.87.1 (e kasy update core em projetos já gerados; a 1.87.0 anunciava a ponte mas o update core não a entregava).

Se você usa um agente de IA com o MCP do Kasy conectado, chame browser_qa_guide depois de implementar ou mudar uma tela (ver MCP).

Login social em iframe ou navegador embutido (Cursor, LP)Copiar link da âncora

Abrir o app web em iframe (preview na landing) ou no Simple Browser do Cursor/VS Code não é igual a uma aba normal do Chrome.

O kit trata esses hosts como embedded OAuth host. No Cursor / VS Code Simple Browser, o login social usa redirect na mesma aba (não popup), porque popups abrem como aba nova e o OAuth não volta.

Domínios OAuth (Firebase): o kasy new registra no Google Cloud os redirect URIs firebaseapp.com e web.app, e ajusta authDomain para SEU_PROJETO.web.app. Projeto já existente: kasy oauth-web. Apple e Facebook não têm API pública para isso: no Apple Developer (Services ID) e no Meta você precisa cadastrar os dois handlers manualmente. O kasy apple-web e o kasy facebook imprimem a lista completa.

Se o popup abre mas a aba original também redireciona, atualize o kit (kasy update core) e confirme kasy-cli ≥ 1.71.3.

Google CloudCopiar link da âncora

Adicione http://localhost:5555 e seu domínio de produção como origins autorizados em Google Cloud Console → Credenciais → seu OAuth Client.

Atualizado em 03/11/2026