[FIX] Flutter WebView: load /?_embed=1 to skip plugin-served DevShell #6

Merged

dunemask merged 1 commit from ep/May14-2026/FlutterEmbedQuery into main

2026-05-14 18:33:51 +00:00

dunemask commented

2026-05-14 18:33:46 +00:00

Owner

After the framework-neutral refactor, vite serves the DevShell parent
page at / and the consumer's app at /?_embed=1. Flutter WebView was
hitting / and rendering the phone-frame DevShell HTML inside itself —
a phone-frame inside a phone-shell, then trying to iframe the app at a
URL that the WebView couldn't follow correctly.

Fix _validatedUrl() to always append ?_embed=1 to the cache-server
URL. Vite's transformIndexHtml sees the query and returns the
consumer's app HTML. In prod the plugin doesn't run server-side at all
(apply: "serve"), so the query is a harmless no-op.

Applied in three places:

packages/vite-plugin/scaffold/lib/shell/webview_screen.dart —
the template; future consumers scaffolded from this get the fix
examples/todo/shell-app/lib/shell/webview_screen.dart —
existing example, scaffolded before this change
docs/flutter-shell.md — new "?_embed=1 — always" section
so existing consumers can apply the same one-line patch

Credit: client developer on apprabbit-studio caught this during
their framework-neutral migration.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

After the framework-neutral refactor, vite serves the DevShell parent page at `/` and the consumer's app at `/?_embed=1`. Flutter WebView was hitting `/` and rendering the phone-frame DevShell HTML inside itself — a phone-frame inside a phone-shell, then trying to iframe the app at a URL that the WebView couldn't follow correctly. Fix `_validatedUrl()` to always append `?_embed=1` to the cache-server URL. Vite's `transformIndexHtml` sees the query and returns the consumer's app HTML. In prod the plugin doesn't run server-side at all (`apply: "serve"`), so the query is a harmless no-op. Applied in three places: - `packages/vite-plugin/scaffold/lib/shell/webview_screen.dart` — the template; future consumers scaffolded from this get the fix - `examples/todo/shell-app/lib/shell/webview_screen.dart` — existing example, scaffolded before this change - `docs/flutter-shell.md` — new "`?_embed=1` — always" section so existing consumers can apply the same one-line patch Credit: client developer on apprabbit-studio caught this during their framework-neutral migration. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dunemask added 1 commit

2026-05-14 18:33:47 +00:00

[FIX] Flutter WebView: load /?_embed=1 to skip plugin-served DevShell a2e6bc4831

After the framework-neutral refactor, vite serves the DevShell parent
page at `/` and the consumer's app at `/?_embed=1`. Flutter WebView was
hitting `/` and rendering the phone-frame DevShell HTML inside itself —
a phone-frame inside a phone-shell, then trying to iframe the app at a
URL that the WebView couldn't follow correctly.

Fix `_validatedUrl()` to always append `?_embed=1` to the cache-server
URL. Vite's `transformIndexHtml` sees the query and returns the
consumer's app HTML. In prod the plugin doesn't run server-side at all
(`apply: "serve"`), so the query is a harmless no-op.

Applied in three places:
  - `packages/vite-plugin/scaffold/lib/shell/webview_screen.dart` —
    the template; future consumers scaffolded from this get the fix
  - `examples/todo/shell-app/lib/shell/webview_screen.dart` —
    existing example, scaffolded before this change
  - `docs/flutter-shell.md` — new "`?_embed=1` — always" section
    so existing consumers can apply the same one-line patch

Credit: client developer on apprabbit-studio caught this during
their framework-neutral migration.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>