Web Guide

Fixed port and session

Login stores the session by origin (which includes the port), whether Supabase Auth or Firebase Auth. kasy run --web uses 5555 so the session persists across runs.

Viewport scale (0.93)

Flutter Web renders ~10% larger than the equivalent native size. The kit applies a 0.93 scale on the web to stay aligned with the mobile design.

Knobs in lib/core/web_viewport_scale.dart:

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

Native never scales (kIsWeb). Device preview turns off the scale to simulate the phone's real size.

Device preview (debug)

Cmd/Ctrl + Shift + D turns on an iPhone/iPad frame in the browser, handy for seeing how a screen looks on a smaller size without opening the simulator. It shows up on any web debug build, whether you pick Chrome in kasy run's picker or use kasy run --web: the frame is rendered by the app itself, regardless of which window hosts the page. It doesn't show up in production builds and doesn't affect native.

On the first run (new project or cleared storage), the preview background and the in-frame app theme follow system light/dark (macOS/Windows). The standalone sun/moon button in the bottom-right corner changes only the canvas behind the device; the sun/moon icon in the preview toolbar changes the app theme. Both choices are saved to localStorage and come back the same on the next kasy run --web.

Onboarding and authentication

Preview doesn't only change the frame size. It also controls which auth flow you're testing in kasy run --web:

Layout ≠ flow. Opening the app in iPhone Safari or a tablet browser uses mobile/tablet breakpoints (responsive UI), but account behavior stays web: sign-in required, no onboarding, no anonymous guest. That's intentional for the kit's SaaS default: trials, subscriptions (RevenueCat/Stripe), and support need an identifiable user.

Use preview on iOS / Android / iPad when you want to validate onboarding, paywall, anonymous accounts, and skip without opening a simulator. On published web (mobile included), the default is to require an account before using the app.

In-app navigation: Settings → Sign up (or Sign in) shows the back arrow on mobile/tablet preview, same as native, when the route was opened with push. Desktop preview or plain web without the frame hides it (direct entry at /signin or /signup).

Supabase: after the loader ("creating your account"), check Authentication → Users. If the search dropdown is Email address, anonymous users vanish from the list (they have no email). Use Unified search or search by User ID from public.users. See Troubleshooting.

/onboarding route

GoRouter controls who may stay on /onboarding:

No duplicate account: if a backend ID already exists (signed-in or anonymous guest), the loader skips anonymous creation. Only first install without an ID creates a guest at the end of the flow.

See onboarding again in dev

In a normal browser tab (including Cursor's browser), the kit remembers state across reloads:

That's why an incognito tab "works": empty storage = first visit again. kasy clear-web and kasy reset --web open the ?kasy_clear_storage=1 URL in your default browser (macOS, Windows, and Linux). That URL clears localStorage, sessionStorage, and IndexedDB (Firebase Auth sessions on web live in IndexedDB).

Options without incognito:

1. Admin → Test onboarding (/onboarding?preview=true): walk every screen without creating a guest, writing profile data, or firing real permission prompts. Returns to Admin when done. On release, admin only (or debug). Good for layout and copy.
2. Real first visit again: kasy clear-web (with kasy run --web running), kasy run --web --open-browser --fresh, an incognito/private tab, or clear site data for localhost:5555 in DevTools → Application. On MCP: run_app with freshStorage=true or clear_web_storage. With device preview on an iOS/Android/iPad tab, you land on onboarding.
3. Direct URL: /onboarding?preview=true only in debug or as admin. The real flow (/onboarding without query) is first install only; an established session goes Home.

Hot reload and hot restart (r / R)

On kasy run --web, update the build in two ways:

Do not use R for visual-only tweaks: it is slower and clears forms, navigation, and guest session.

Who sends r / R

Human dev: toolbar or terminal whenever you want. Agent: full rules in AI guidance (site docs at kasy.dev/docs, not the marketing landing page).

AI navigation (Browser QA)

Flutter Web paints the whole screen to canvas — without special handling, an AI agent in the browser (Cursor, Claude, Playwright) can't see a button or a text field the way it would on a normal React page, only pixels.

The kit fixes this by turning on Flutter's semantics tree on every debug/profile build (never in production) and installing a JS bridge (window.__kasyBrowserQa) that lets the agent fill fields reliably:

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

With that on, an AI agent can read the page as a normal accessibility tree (every button's, field's, switch's name) and call window.__kasyBrowserQa.setTextIn(label, value) to type into a field by name, instead of relying on click-then-hope-it-focused.

Agent ritual (reload r/R, terminal, snapshot, setTextIn): AI guidance and docs/agent-browser-qa.md in the project. MCP: browser_qa_guide.

If you're using an AI agent with Kasy's MCP connected, call browser_qa_guide after implementing or changing a screen (see MCP).

Google Cloud

Add http://localhost:5555 and your production domain as authorized origins in Google Cloud Console → Credentials → your OAuth Client.

Last updated on 08/02/2026