@ufjs/webview 0.1.3

package/flutter/test/web_view_test.dart

@@ -0,0 +1,369 @@
+// The app half of specs/013-web-view. The web twin is
+// ../../test/web-view-web.test.ts, and the payload strings asserted here are
+// the same ones it asserts — that pair IS the "two ends, one contract" check.
+// EagerGestureRecognizer lives here, not in material.dart — without this the
+// whole file failed to compile, which `flutter test` reports as one failed
+// "loading …" case rather than as a missing import.
+import 'package:flutter/gestures.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutter_fjs/flutter_fjs.dart';
+import 'package:fjs_webview/fjs_webview.dart';
+import 'package:webview_flutter/webview_flutter.dart';
+import 'package:webview_flutter_platform_interface/webview_flutter_platform_interface.dart';
+
+MirrorNode nodeWith(Map<String, Object?> props) {
+  final node = MirrorNode(7, 'web-view');
+  node.props = props;
+  return node;
+}
+
+void main() {
+  setUp(resetFjsWebViewWarnings);
+
+  group('payloads mirror the JS side', () {
+    test('load, error and message', () {
+      expect(
+        fjsWebViewLoadPayload('https://example.com/a'),
+        '{"src":"https://example.com/a"}',
+      );
+      expect(
+        fjsWebViewErrorPayload('https://example.com/a'),
+        '{"src":"https://example.com/a","errMsg":"web-view load failed"}',
+      );
+      expect(fjsWebViewMessagePayload('hello #1'), '{"data":"hello #1"}');
+    });
+
+    test('escapes what JSON has to escape', () {
+      expect(fjsWebViewMessagePayload('a "b"\nc'), '{"data":"a \\"b\\"\\nc"}');
+      expect(fjsWebViewMessagePayload('tab\there'), '{"data":"tab\\there"}');
+    });
+  });
+
+  group('src', () {
+    test('classifies the loadable schemes and refuses the rest', () {
+      expect(fjsClassifyWebViewSrc('https://a'), FjsWebViewSrcKind.http);
+      expect(fjsClassifyWebViewSrc('http://a'), FjsWebViewSrcKind.http);
+      expect(fjsClassifyWebViewSrc('asset://a.html'), FjsWebViewSrcKind.asset);
+      expect(fjsClassifyWebViewSrc(''), FjsWebViewSrcKind.empty);
+      expect(fjsClassifyWebViewSrc(null), FjsWebViewSrcKind.empty);
+      for (final src in const [
+        'file:///etc/passwd',
+        'javascript:alert(1)',
+        'data:text/html,x',
+        'example.com',
+      ]) {
+        expect(fjsClassifyWebViewSrc(src), FjsWebViewSrcKind.unsupported,
+            reason: src);
+      }
+    });
+
+    test('an asset path cannot escape the module directory', () {
+      expect(fjsWebViewAssetPath('asset://demo.html'), 'demo.html');
+      expect(fjsWebViewAssetPath('asset:///demo.html'), 'demo.html');
+      expect(fjsWebViewAssetPath('asset://../secret'), isNull);
+      expect(fjsWebViewAssetPath('asset://'), isNull);
+    });
+
+    test('asset:// goes to the dev server while fjs dev is connected', () {
+      final target = fjsResolveWebViewSrc(
+        'asset://demo.html',
+        devUri: Uri.parse('http://127.0.0.1:38900/'),
+      );
+      expect(target.url, 'http://127.0.0.1:38900/modules/webview/demo.html');
+      expect(target.asset, isNull);
+    });
+
+    test('asset:// is a Flutter asset without one', () {
+      final target = fjsResolveWebViewSrc('asset://demo.html');
+      // loadFlutterAsset takes a key, not a URL — hence the separate shape
+      expect(target.asset, 'assets/fjs/modules/webview/demo.html');
+      expect(target.url, isNull);
+      expect(target.suffix, isEmpty);
+    });
+
+    test('an asset key is separate from the document suffix', () {
+      // FWFURLParsingError happens when `demo.html?q=hello` is used as the
+      // manifest key. The suffix is restored on the local document URL
+      // instead, so the page still receives its parameters.
+      final release = fjsResolveWebViewSrc('asset://demo.html?q=hello#top');
+      expect(release.asset, 'assets/fjs/modules/webview/demo.html');
+      expect(release.suffix, '?q=hello#top');
+
+      final dev = fjsResolveWebViewSrc(
+        'asset://demo.html?q=hello#top',
+        devUri: Uri.parse('http://127.0.0.1:38900'),
+      );
+      expect(dev.url,
+          'http://127.0.0.1:38900/modules/webview/demo.html?q=hello#top');
+      expect(dev.suffix, isEmpty);
+    });
+
+    test('a root path is the app\'s own page, not the module\'s', () {
+      // classifySrc in ../../index.ts has the same three kinds; missing this
+      // branch on one end shows up as `unsupported` + a warn on that end
+      // only, never as an exception (constitution I).
+      expect(fjsClassifyWebViewSrc('/html/guide.html'),
+          FjsWebViewSrcKind.local);
+      expect(fjsWebViewLocalPath('/html/guide.html'), 'html/guide.html');
+      expect(fjsWebViewLocalPath('///html/guide.html'), 'html/guide.html');
+      expect(fjsWebViewLocalPath('/../secret'), isNull);
+      expect(fjsWebViewLocalPath('/'), isNull);
+    });
+
+    test('a root path goes to the dev server while fjs dev is connected', () {
+      final target = fjsResolveWebViewSrc(
+        '/html/guide.html',
+        devUri: Uri.parse('http://127.0.0.1:38900/'),
+      );
+      expect(target.url, 'http://127.0.0.1:38900/html/guide.html');
+      expect(target.asset, isNull);
+    });
+
+    test('a root path is an app asset without one', () {
+      final target = fjsResolveWebViewSrc('/html/guide.html');
+      expect(target.asset, 'assets/fjs/public/html/guide.html');
+      expect(target.url, isNull);
+      expect(target.suffix, isEmpty);
+    });
+
+    test('a root path splits key and suffix the same way asset:// does', () {
+      final release = fjsResolveWebViewSrc('/html/guide.html?q=1#top');
+      expect(release.asset, 'assets/fjs/public/html/guide.html');
+      expect(release.suffix, '?q=1#top');
+    });
+
+    test('strips a fragment too', () {
+      expect(fjsWebViewStripQuery('a.html#top'), 'a.html');
+      expect(fjsWebViewStripQuery('a.html'), 'a.html');
+    });
+
+    test('http is left alone either way', () {
+      expect(fjsResolveWebViewSrc('https://example.com/a').url,
+          'https://example.com/a');
+      expect(
+        fjsResolveWebViewSrc('https://example.com/a',
+                devUri: Uri.parse('http://127.0.0.1:38900'))
+            .url,
+        'https://example.com/a',
+      );
+    });
+
+    test('nothing to load for empty and unsupported', () {
+      expect(fjsResolveWebViewSrc('').isNothing, isTrue);
+      expect(fjsResolveWebViewSrc('file:///x').isNothing, isTrue);
+      expect(fjsResolveWebViewSrc('asset://../x').isNothing, isTrue);
+    });
+  });
+
+  group('load cycle', () {
+    test('reports one terminal event per load', () {
+      final cycle = FjsWebViewLoadCycle();
+      final generation = cycle.begin();
+      expect(cycle.finish(generation), isTrue);
+      // error after load, or a second onPageFinished, is not a second event
+      expect(cycle.finish(generation), isFalse);
+    });
+
+    test('drops the previous page after the src changes', () {
+      final cycle = FjsWebViewLoadCycle();
+      final first = cycle.begin();
+      final second = cycle.begin();
+      expect(cycle.finish(first), isFalse);
+      expect(cycle.finish(second), isTrue);
+    });
+
+    test('accepts messages only from the current page', () {
+      final cycle = FjsWebViewLoadCycle();
+      final first = cycle.begin();
+      expect(cycle.accepts(first), isTrue);
+      cycle.begin();
+      expect(cycle.accepts(first), isFalse);
+    });
+  });
+
+  group('release asset navigation', () {
+    test('reattaches parameters before the first page script', () {
+      final navigation = FjsWebViewAssetNavigation('?q=hello#top');
+      expect(
+        navigation.redirect('file:///bundle/demo.html'),
+        'file:///bundle/demo.html?q=hello#top',
+      );
+      expect(
+        navigation.accepts('file:///bundle/demo.html?q=hello#top'),
+        isTrue,
+      );
+      expect(navigation.redirect('file:///bundle/demo.html'), isNull);
+    });
+
+    test('does not redirect an already parameterized URL', () {
+      final navigation = FjsWebViewAssetNavigation('?q=hello');
+      expect(
+        navigation.redirect('file:///bundle/demo.html?q=hello'),
+        isNull,
+      );
+      expect(navigation.redirect('file:///bundle/demo.html'), isNotNull);
+    });
+
+    test('stops protecting the base URL after the redirected page finishes',
+        () {
+      final navigation = FjsWebViewAssetNavigation('?q=hello');
+      navigation.redirect('file:///bundle/demo.html');
+      expect(
+        navigation.shouldPreventBaseNavigation('file:///bundle/demo.html'),
+        isTrue,
+      );
+      navigation.markFinished('file:///bundle/demo.html?q=hello');
+      expect(
+        navigation.shouldPreventBaseNavigation('file:///bundle/demo.html'),
+        isFalse,
+      );
+    });
+  });
+
+  group('box', () {
+    test('needs a bounded height, because a page has no natural one', () {
+      expect(
+        fjsWebViewFitsBox(
+            const BoxConstraints.tightFor(width: 300, height: 200)),
+        isTrue,
+      );
+      expect(
+        fjsWebViewFitsBox(const BoxConstraints(maxWidth: 300)),
+        isFalse,
+      );
+    });
+  });
+
+  group('widget', () {
+    testWidgets('an empty src builds nothing at all', (tester) async {
+      final events = <(int, String?)>[];
+      await tester.pumpWidget(MaterialApp(
+        home: FjsWebViewWidget(
+          node: nodeWith(const {}),
+          dispatch: (id, type, {String? text}) => events.add((type, text)),
+        ),
+      ));
+      expect(find.byType(SizedBox), findsOneWidget);
+      expect(events, isEmpty);
+    });
+
+  testWidgets('an unsupported scheme warns once and loads nothing',
+      (tester) async {
+      final logs = <String>[];
+      final original = debugPrint;
+      debugPrint = (message, {wrapWidth}) => logs.add(message ?? '');
+      try {
+        await tester.pumpWidget(MaterialApp(
+          home: FjsWebViewWidget(
+            node: nodeWith(const {'src': 'file:///etc/passwd'}),
+            dispatch: (id, type, {String? text}) {},
+          ),
+        ));
+      } finally {
+        debugPrint = original;
+      }
+      expect(logs.where((l) => l.contains('file:///etc/passwd')), isNotEmpty);
+    });
+
+    testWidgets('claims gestures inside the platform view', (tester) async {
+      final platform = _FakeWebViewPlatform();
+      WebViewPlatform.instance = platform;
+      addTearDown(() => WebViewPlatform.instance = _FakeWebViewPlatform());
+
+      await tester.pumpWidget(MaterialApp(
+        home: FjsWebViewWidget(
+          node: nodeWith(const {'src': 'https://example.com'}),
+          dispatch: (id, type, {String? text}) {},
+        ),
+      ));
+
+      final params = platform.lastWidgetParams;
+      expect(params, isNotNull);
+      expect(params!.gestureRecognizers, hasLength(1));
+      expect(
+        params.gestureRecognizers.single.constructor(),
+        isA<EagerGestureRecognizer>(),
+      );
+    });
+  });
+}
+
+class _FakeWebViewPlatform extends WebViewPlatform {
+  PlatformWebViewWidgetCreationParams? lastWidgetParams;
+
+  @override
+  PlatformWebViewController createPlatformWebViewController(
+    PlatformWebViewControllerCreationParams params,
+  ) => _FakeWebViewController(params);
+
+  @override
+  PlatformWebViewWidget createPlatformWebViewWidget(
+    PlatformWebViewWidgetCreationParams params,
+  ) {
+    lastWidgetParams = params;
+    return _FakeWebViewWidget(params);
+  }
+
+  @override
+  PlatformNavigationDelegate createPlatformNavigationDelegate(
+    PlatformNavigationDelegateCreationParams params,
+  ) => _FakeNavigationDelegate(params);
+}
+
+class _FakeWebViewController extends PlatformWebViewController {
+  _FakeWebViewController(super.params) : super.implementation();
+
+  @override
+  Future<void> setJavaScriptMode(JavaScriptMode javaScriptMode) async {}
+
+  @override
+  Future<void> setPlatformNavigationDelegate(
+    PlatformNavigationDelegate handler,
+  ) async {}
+
+  @override
+  Future<void> addJavaScriptChannel(
+    JavaScriptChannelParams javaScriptChannelParams,
+  ) async {}
+
+  @override
+  Future<void> loadFlutterAsset(String key) async {}
+
+  @override
+  Future<void> loadRequest(LoadRequestParams params) async {}
+}
+
+class _FakeWebViewWidget extends PlatformWebViewWidget {
+  _FakeWebViewWidget(super.params) : super.implementation();
+
+  @override
+  Widget build(BuildContext context) => const SizedBox();
+}
+
+class _FakeNavigationDelegate extends PlatformNavigationDelegate {
+  _FakeNavigationDelegate(super.params) : super.implementation();
+
+  // PlatformNavigationDelegate's setters throw UnimplementedError by
+  // default, and NavigationDelegate's constructor calls every one it was
+  // given a callback for. The widget under test registers all four, so a
+  // fake that overrides none cannot be built at all.
+  @override
+  Future<void> setOnNavigationRequest(
+    NavigationRequestCallback onNavigationRequest,
+  ) async {}
+
+  @override
+  Future<void> setOnPageFinished(PageEventCallback onPageFinished) async {}
+
+  @override
+  Future<void> setOnPageStarted(PageEventCallback onPageStarted) async {}
+
+  @override
+  Future<void> setOnWebResourceError(
+    WebResourceErrorCallback onWebResourceError,
+  ) async {}
+
+  @override
+  Future<void> setOnHttpError(HttpResponseErrorCallback onHttpError) async {}
+}

package/index.ts

@@ -0,0 +1,210 @@
+// web-view — one tag, a platform WebView on the app and an iframe on the web.
+//
+//   <web-view src="https://example.com" @message="onMessage" />
+//
+// This file is the part both targets agree on: the three event payloads, how
+// a `src` is classified and resolved, and the "one terminal event per load"
+// gate. Neither side imports the other's code — the app side is Dart
+// (flutter/lib/fjs_webview.dart) — so, as with scroll/metrics.ts in the
+// runtime, this file is the SPEC as much as the implementation, and the Dart
+// half mirrors it and points back here.
+//
+// Why a module and not a built-in tag: webview_flutter needs Dart SDK ^3.5,
+// and flutter_fjs still declares >=3.3. Built in, every app would pay that;
+// as a module, only the apps that install it do.
+
+/** The module's short name — the npm scope is stripped by the toolchain, so
+ * this is what appears in `/modules/<name>/…` and in the Flutter asset path. */
+export const WEB_VIEW_MODULE = 'webview';
+
+/** Where the web target serves the module's `public/` from. The prepare hook
+ * copies the files there because vite does not serve `.fjs/`. */
+export const WEB_ASSET_BASE = `/fjs-modules/${WEB_VIEW_MODULE}`;
+
+/** Where the app's own local files land in a release build — the one
+ * directory the CLI syncs public/ and html/ into (specs/017). */
+export const APP_ASSET_BASE = 'assets/fjs/public';
+
+/** Stable failure text. WKWebView and the browser word their errors
+ * completely differently, and a payload that changes per platform is not a
+ * contract — the platform's own message stays in the platform's log. */
+export const WEB_VIEW_ERROR = 'web-view load failed';
+
+/** `@load`: which page finished. Field order is part of the contract. */
+export function loadPayload(src: string): string {
+  return JSON.stringify({ src });
+}
+
+/** `@error`: which page failed, and a fixed message. */
+export function errorPayload(src: string): string {
+  return JSON.stringify({ src, errMsg: WEB_VIEW_ERROR });
+}
+
+/** `@message`: what the page passed to fjs.postMessage, verbatim. Objects
+ * are the page's job to stringify — only strings cross this boundary. */
+export function messagePayload(data: string): string {
+  return JSON.stringify({ data });
+}
+
+export type SrcKind = 'empty' | 'http' | 'asset' | 'local' | 'unsupported';
+
+/** What a `src` is, before anyone tries to load it.
+ *
+ * Three loadable shapes. `http(s)` is the network. `asset://` is a file THIS
+ * MODULE ships — it resolves under `modules/webview/`, so an app cannot
+ * name its own page that way. A root path (`/html/guide.html`) is the app's
+ * own page, from the project's `html/` directory
+ * (specs/018-src-hints-and-html-dir).
+ *
+ * Everything else stays refused: `file:`, `javascript:`, `data:` and friends
+ * differ so much between WKWebView and a browser that accepting them would
+ * be handing pages a portability trap. */
+export function classifySrc(raw: unknown): SrcKind {
+  const src = raw == null ? '' : String(raw).trim();
+  if (!src) return 'empty';
+  if (src.startsWith('http://') || src.startsWith('https://')) return 'http';
+  if (src.startsWith('asset://')) return 'asset';
+  if (src.startsWith('/')) return 'local';
+  return 'unsupported';
+}
+
+export function unsupportedSrcMessage(raw: unknown): string {
+  return (
+    `<web-view> will not load "${String(raw)}": only http(s)://, ` +
+    'a root path like "/html/page.html" (a file in the project\'s html/ ' +
+    'directory) and asset:// (a file this module ships) are supported. ' +
+    'Other schemes behave too differently between WKWebView and the ' +
+    'browser to promise.'
+  );
+}
+
+/** The path part of an `asset://` src, with the scheme and any leading
+ * slashes removed. Returns null for anything that escapes the module's own
+ * directory. */
+export function assetPath(raw: string): string | null {
+  const path = raw.slice('asset://'.length).replace(/^\/+/, '');
+  if (!path || path.includes('..')) return null;
+  return path;
+}
+
+/** The path part of a root-absolute src, with leading slashes removed.
+ * Returns null for anything that escapes the app's own files. */
+export function localPath(raw: string): string | null {
+  const path = raw.replace(/^\/+/, '');
+  if (!path || path.includes('..')) return null;
+  return path;
+}
+
+/** Where the loaded page lives, per target.
+ *
+ *  * `web` — the app's own static root, put there by the prepare hook;
+ *  * `app-dev` — the dev server already serves `/modules/<name>/…`;
+ *  * `app-release` — a Flutter asset, which the Dart side loads with
+ *    `loadFlutterAsset` rather than as a URL. It is returned as a distinct
+ *    shape for exactly that reason.
+ */
+export type SrcTarget =
+  | { target: 'web' }
+  | { target: 'app-dev'; devHost: string }
+  | { target: 'app-release' };
+
+export type ResolvedSrc =
+  | { kind: 'url'; url: string }
+  | { kind: 'flutter-asset'; asset: string; suffix: string }
+  | { kind: 'none' };
+
+/** Everything before `?` / `#`. A Flutter asset key cannot carry either. */
+export function stripQuery(path: string): string {
+  const cut = path.search(/[?#]/);
+  return cut < 0 ? path : path.slice(0, cut);
+}
+
+/** The part that belongs to the document URL rather than the asset key. */
+export function assetSuffix(path: string): string {
+  const cut = path.search(/[?#]/);
+  return cut < 0 ? '' : path.slice(cut);
+}
+
+export function resolveSrc(raw: unknown, where: SrcTarget): ResolvedSrc {
+  const src = raw == null ? '' : String(raw).trim();
+  switch (classifySrc(src)) {
+    case 'http':
+      return { kind: 'url', url: src };
+    case 'local': {
+      // The app's own file. It rides the same root-path contract images use
+      // (specs/017-local-image-assets): the browser serves it from the site
+      // root, the dev server answers for it, and a release build has it as a
+      // Flutter asset under assets/fjs/public/.
+      const path = localPath(src);
+      if (!path) return { kind: 'none' };
+      if (where.target === 'web') return { kind: 'url', url: `/${path}` };
+      if (where.target === 'app-dev') {
+        const host = where.devHost.replace(/\/+$/, '');
+        return { kind: 'url', url: `${host}/${path}` };
+      }
+      return {
+        kind: 'flutter-asset',
+        asset: `${APP_ASSET_BASE}/${stripQuery(path)}`,
+        suffix: assetSuffix(path),
+      };
+    }
+    case 'asset': {
+      const path = assetPath(src);
+      if (!path) return { kind: 'none' };
+      if (where.target === 'web') {
+        return { kind: 'url', url: `${WEB_ASSET_BASE}/${path}` };
+      }
+      if (where.target === 'app-dev') {
+        const host = where.devHost.replace(/\/+$/, '');
+        return { kind: 'url', url: `${host}/modules/${WEB_VIEW_MODULE}/${path}` };
+      }
+      // A Flutter asset is a KEY, not a URL: loadFlutterAsset looks the
+      // string up in the bundle's manifest, so `demo.html?q=1` is simply not
+      // a file and the platform throws. The key is stripped while the caller
+      // keeps the suffix for the document URL. The two values must stay
+      // separate: one is a bundle manifest key, the other is page state.
+      return {
+        kind: 'flutter-asset',
+        asset: `assets/fjs/modules/${WEB_VIEW_MODULE}/${stripQuery(path)}`,
+        suffix: assetSuffix(path),
+      };
+    }
+    default:
+      return { kind: 'none' };
+  }
+}
+
+/** One terminal event per load, and never the previous page's.
+ *
+ * Same shape as the image module's cycle: a `src` change begins a new
+ * generation, a result carrying an old one is dropped, and `load`/`error`
+ * are mutually exclusive within a generation. */
+export class LoadCycle {
+  private generation = 0;
+  private settled = false;
+
+  /** Starts a new load; returns its generation. */
+  begin(): number {
+    this.generation += 1;
+    this.settled = false;
+    return this.generation;
+  }
+
+  get current(): number {
+    return this.generation;
+  }
+
+  /** True when this result should be reported: it belongs to the current
+   * load and nothing has settled it yet. */
+  finish(generation: number): boolean {
+    if (generation !== this.generation || this.settled) return false;
+    this.settled = true;
+    return true;
+  }
+
+  /** Whether a message from [generation] is still the current page's. A
+   * message is not terminal, so it does not settle anything. */
+  accepts(generation: number): boolean {
+    return generation === this.generation;
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@ufjs/webview",
+  "version": "0.1.3",
+  "description": "web-view for fjs — one <web-view /> tag, a WKWebView/WebView on the app and an iframe on the web",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snice/flutter-js.git",
+    "directory": "packages/fjs-webview"
+  },
+  "homepage": "https://github.com/snice/flutter-js#readme",
+  "bugs": "https://github.com/snice/flutter-js/issues",
+  "keywords": [
+    "fjs",
+    "flutter",
+    "webview",
+    "iframe",
+    "vue"
+  ],
+  "type": "module",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./components/*": "./components/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "components",
+    "flutter",
+    "public",
+    "prepare.mjs",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@ufjs/runtime": ">=0.1.3",
+    "vue": "^3.4.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.3",
+    "happy-dom": "^20.12.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "vue": "^3.5.42"
+  },
+  "fjs": {
+    "module": true,
+    "widgets": {
+      "web-view": {
+        "web": "./components/WebViewWeb.vue"
+      }
+    },
+    "flutter": {
+      "package": "fjs_webview",
+      "path": "./flutter",
+      "import": "package:fjs_webview/fjs_webview.dart",
+      "register": "FjsWebview.register(engine)"
+    },
+    "prepare": "./prepare.mjs"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/prepare.mjs

@@ -0,0 +1,40 @@
+// The module's build step. fjs runs this before every build, dev start and
+// Vite start, because package.json says `"fjs": { "prepare": "./prepare.mjs" }`.
+//
+// It copies this module's `public/` — the pages it ships — into the one
+// place both targets read from:
+//
+//   .fjs/modules/webview/<file>        the only copy
+//     → app dev:     `fjs dev` serves /modules/webview/<file>
+//     → app release: the build copies it to assets/fjs/modules/webview/
+//     → web:         the fjs vite plugin serves it at /fjs-modules/webview/,
+//                    and the web builds copy it to the same path
+//
+// It used to write a SECOND copy into the app's own `public/fjs-modules/` —
+// the only hook that ever wrote outside ctx.outDir — because that was the
+// one place vite would serve it from without the app editing its config.
+// Once `public/` started riding into the Flutter bundle wholesale
+// (specs/017-local-image-assets), that second copy became a duplicate file
+// in every release build, and the app side never read it. The toolchain now
+// gives the one copy its web URL instead (specs/018-src-hints-and-html-dir),
+// so a hook is back to writing only where it should.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MODULE = 'webview';
+
+export default async function prepare(ctx) {
+  const source = path.join(ctx.module.dir, 'public');
+  if (!fs.existsSync(source)) return;
+
+  const files = fs
+    .readdirSync(source, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name);
+
+  for (const name of files) {
+    ctx.write(name, fs.readFileSync(path.join(source, name), 'utf8'));
+  }
+
+  ctx.log(`${files.length} page(s) → .fjs/modules/${MODULE}/`);
+}