kasy-cli 1.32.0 → 1.35.0

package/templates/firebase/lib/core/theme/responsive_text_theme.dart

@@ -0,0 +1,69 @@
+import 'package:flutter/material.dart';
+import 'package:kasy_kit/core/theme/texts.dart';
+import 'package:kasy_kit/core/widgets/responsive_layout.dart';
+
+/// Republishes the app's typography for the current breakpoint — without
+/// touching a single call site.
+///
+/// It reads the effective viewport width, picks the [DeviceType], and rebuilds
+/// the Material `textTheme` and the [KasyTextTheme] extension from the
+/// per-breakpoint [KasyTypeScale] ramp. Headings step down from desktop to
+/// mobile; body and labels stay constant. Colours are kept from the base theme
+/// (the ramp is colourless), so every `context.textTheme.*` and
+/// `context.kasyTextTheme.*` below inherits the breakpoint's sizes.
+///
+/// Placed as the innermost wrapper of the app (inside `WebViewportScale` and
+/// `DevicePreview`), so it reads the *same* width the screens lay out against:
+/// the type bucket always matches the layout bucket. Desktop is the authored
+/// baseline, so it is a pass-through there.
+class ResponsiveTextTheme extends StatelessWidget {
+  final Widget child;
+
+  const ResponsiveTextTheme({super.key, required this.child});
+
+  @override
+  Widget build(BuildContext context) {
+    final DeviceType device =
+        DeviceType.fromWidth(MediaQuery.sizeOf(context).width);
+
+    // Desktop is the authored baseline (the base theme built in main.dart) — no
+    // rebuild needed.
+    if (device != DeviceType.small && device != DeviceType.medium) {
+      return child;
+    }
+
+    final ThemeData theme = Theme.of(context);
+    final KasyTextTheme ramp = KasyTextTheme.build(device);
+    final TextTheme base = theme.textTheme;
+
+    // Take size/weight/line-height from the ramp, keep colour from the base
+    // (the ramp is colourless, so merge preserves the base slot's colour).
+    final TextTheme rebuilt = TextTheme(
+      displayLarge: base.displayLarge?.merge(ramp.displayLarge),
+      displayMedium: base.displayMedium?.merge(ramp.displayMedium),
+      displaySmall: base.displaySmall?.merge(ramp.displaySmall),
+      headlineLarge: base.headlineLarge?.merge(ramp.headlineLarge),
+      headlineMedium: base.headlineMedium?.merge(ramp.headlineMedium),
+      headlineSmall: base.headlineSmall?.merge(ramp.headlineSmall),
+      titleLarge: base.titleLarge?.merge(ramp.titleLarge),
+      titleMedium: base.titleMedium?.merge(ramp.titleMedium),
+      titleSmall: base.titleSmall?.merge(ramp.titleSmall),
+      bodyLarge: base.bodyLarge?.merge(ramp.bodyLarge),
+      bodyMedium: base.bodyMedium?.merge(ramp.bodyMedium),
+      bodySmall: base.bodySmall?.merge(ramp.bodySmall),
+      labelLarge: base.labelLarge?.merge(ramp.labelLarge),
+      labelMedium: base.labelMedium?.merge(ramp.labelMedium),
+      labelSmall: base.labelSmall?.merge(ramp.labelSmall),
+    );
+
+    // Replace only the KasyTextTheme extension; keep every other extension.
+    final List<ThemeExtension<dynamic>> extensions = theme.extensions.values
+        .map((e) => e is KasyTextTheme ? ramp : e)
+        .toList();
+
+    return Theme(
+      data: theme.copyWith(textTheme: rebuilt, extensions: extensions),
+      child: child,
+    );
+  }
+}

package/templates/firebase/lib/core/theme/texts.dart

@@ -1,5 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:google_fonts/google_fonts.dart';
+import 'package:kasy_kit/core/theme/type_scale.dart';
+import 'package:kasy_kit/core/widgets/responsive_layout.dart';
 
 /// Kasy Design System — Typography Tokens (HeroUI type scale)
 ///
@@ -32,6 +34,22 @@ class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
         decoration: decoration,
       );
 
+  // Builds a role from its responsive [RampSize] at a given [device]: the size
+  // (and proportional line-height) come from the breakpoint, the weight from
+  // the role. This is how every slot picks up the per-breakpoint type scale.
+  static TextStyle _fromRamp(
+    FontWeight weight,
+    RampSize ramp,
+    DeviceType device, {
+    TextDecoration? decoration,
+  }) =>
+      _inter(
+        weight,
+        ramp.size(device),
+        ramp.lineHeight(device),
+        decoration: decoration,
+      );
+
   // -----------------------------------------------------------------------
   // HeroUI roles — canonical styles (color applied per-theme downstream)
   // -----------------------------------------------------------------------
@@ -54,37 +72,9 @@ class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
   static TextStyle get buttonBase => _inter(FontWeight.w500, 16, 24);
   static TextStyle get buttonSm => _inter(FontWeight.w500, 14, 20);
 
-  // -----------------------------------------------------------------------
-  // Semantic app roles — name the recurring UI text roles so screens stop
-  // hand-tuning slots with copyWith(fontSize/fontWeight/...). Each composes a
-  // scale role above; restyle a role app-wide by editing it here once.
-  // Apply color at the call site (.copyWith(color: ...)); the scale is colorless.
-  // -----------------------------------------------------------------------
-
-  /// Top-level page title (auth, paywall, full-screen flows). 24 / w700.
-  static TextStyle get pageTitle => heading2;
-
-  /// Section or master-detail pane title (Settings detail, grouped areas). 16 / w600.
-  static TextStyle get sectionTitle => heading4;
-
-  /// Small header above a grouped list (e.g. "PREFERENCES"). 12 / w600, lightly tracked.
-  static TextStyle get sectionLabel =>
-      _inter(FontWeight.w600, 12, 16).copyWith(letterSpacing: 0.5);
-
-  /// Primary text of a list / settings row. 14 / w500.
-  static TextStyle get rowTitle => bodySmMedium;
-
-  /// Secondary / value text in a row (apply a muted color at the call site). 14 / w400.
-  static TextStyle get rowValue => bodySm;
-
-  /// Card title. 14 / w500.
-  static TextStyle get cardTitle => bodySmMedium;
-
-  /// Card subtitle / supporting line. 12 / w400.
-  static TextStyle get cardSubtitle => bodyXs;
-
-  /// Caption, hint, version label, footnote. 12 / w400.
-  static TextStyle get caption => bodyXs;
+  // Semantic UI roles (pageTitle, sectionTitle, rowTitle, …) live as INSTANCE
+  // getters further down, so they pick up the per-breakpoint scaling. The raw
+  // scale roles above stay static (the authored spec / design-system baseline).
 
   // -----------------------------------------------------------------------
   // Display — large hero text (extends the HeroUI scale upward in Inter)
@@ -143,35 +133,78 @@ class KasyTextTheme extends ThemeExtension<KasyTextTheme> {
     required this.primary,
   });
 
-  factory KasyTextTheme.build() {
+  // -----------------------------------------------------------------------
+  // Semantic app roles — INSTANCE getters (responsive).
+  //
+  // These mirror the static roles above, but derive from this instance's
+  // fields, so they pick up the per-breakpoint scaling applied by
+  // [ResponsiveTextTheme]. Prefer `context.kasyTextTheme.<role>` on screens
+  // when you need a role that scales (the static `KasyTextTheme.<role>` stays
+  // fixed at the desktop baseline — fine for specs/docs, not for live UI).
+  // Apply colour at the call site; the scale is colourless.
+  // -----------------------------------------------------------------------
+
+  /// Top-level page title (auth, paywall, full-screen flows). 24 / w700.
+  TextStyle get pageTitle => headlineMedium;
+
+  /// Section or master-detail pane title (Settings detail, grouped areas). 16 / w600.
+  TextStyle get sectionTitle => titleMedium;
+
+  /// Small header above a grouped list (e.g. "PREFERENCES"). 12 / w600, lightly tracked.
+  TextStyle get sectionLabel =>
+      bodySmall.copyWith(fontWeight: FontWeight.w600, letterSpacing: 0.5);
+
+  /// Primary text of a list / settings row. 14 / w500.
+  TextStyle get rowTitle => titleSmall;
+
+  /// Secondary / value text in a row (apply a muted colour at the call site). 14 / w400.
+  TextStyle get rowValue => bodyMedium;
+
+  /// Card title. 14 / w500.
+  TextStyle get cardTitle => titleSmall;
+
+  /// Card subtitle / supporting line. 12 / w400.
+  TextStyle get cardSubtitle => bodySmall;
+
+  /// Caption, hint, version label, footnote. 12 / w400.
+  TextStyle get caption => bodySmall;
+
+  /// Builds the full text theme for a given [device].
+  ///
+  /// Each slot resolves its size from the responsive [KasyTypeScale] ramp at the
+  /// breakpoint: headings step down from desktop to mobile, body and labels stay
+  /// constant. Defaults to desktop ([DeviceType.large]) so the base theme built
+  /// once in `main.dart` is the authored reference; [ResponsiveTextTheme]
+  /// rebuilds it per breakpoint below the MediaQuery.
+  factory KasyTextTheme.build([DeviceType device = DeviceType.large]) {
     return KasyTextTheme(
-      // Display — hero text in Inter, neutral tracking.
-      displayLarge: _inter(FontWeight.w800, 57, 64),
-      displayMedium: _inter(FontWeight.w800, 45, 52),
-      displaySmall: heading1, // 36/40
-
-      // Headline → HeroUI Heading 1–3.
-      headlineLarge: heading1,
-      headlineMedium: heading2,
-      headlineSmall: heading3,
-
-      // Title → HeroUI Heading 3 / Heading 4 / Body sm medium.
-      titleLarge: heading3,
-      titleMedium: heading4,
-      titleSmall: bodySmMedium,
-
-      // Body → HeroUI Body base / Body sm / Body xs.
-      bodyLarge: bodyBase,
-      bodyMedium: bodySm,
-      bodySmall: bodyXs,
-
-      // Label → HeroUI Button sm / Body xs medium.
-      labelLarge: buttonSm,
-      labelMedium: bodyXsMedium,
-      labelSmall: bodyXsMedium,
+      // Display — hero text.
+      displayLarge: _fromRamp(FontWeight.w800, KasyTypeScale.displayLarge, device),
+      displayMedium: _fromRamp(FontWeight.w800, KasyTypeScale.displayMedium, device),
+      displaySmall: _fromRamp(FontWeight.w800, KasyTypeScale.heading1, device),
+
+      // Headline → Heading 1–3.
+      headlineLarge: _fromRamp(FontWeight.w800, KasyTypeScale.heading1, device),
+      headlineMedium: _fromRamp(FontWeight.w700, KasyTypeScale.heading2, device),
+      headlineSmall: _fromRamp(FontWeight.w600, KasyTypeScale.heading3, device),
+
+      // Title → Heading 3 / Heading 4 / Body sm medium.
+      titleLarge: _fromRamp(FontWeight.w600, KasyTypeScale.heading3, device),
+      titleMedium: _fromRamp(FontWeight.w600, KasyTypeScale.heading4, device),
+      titleSmall: _fromRamp(FontWeight.w500, KasyTypeScale.bodySm, device),
+
+      // Body → Body base / Body sm / Body xs.
+      bodyLarge: _fromRamp(FontWeight.w400, KasyTypeScale.bodyBase, device),
+      bodyMedium: _fromRamp(FontWeight.w400, KasyTypeScale.bodySm, device),
+      bodySmall: _fromRamp(FontWeight.w400, KasyTypeScale.bodyXs, device),
+
+      // Label → Button sm / Body xs medium.
+      labelLarge: _fromRamp(FontWeight.w500, KasyTypeScale.bodySm, device),
+      labelMedium: _fromRamp(FontWeight.w500, KasyTypeScale.bodyXs, device),
+      labelSmall: _fromRamp(FontWeight.w500, KasyTypeScale.bodyXs, device),
 
       // Legacy primary.
-      primary: bodyBase,
+      primary: _fromRamp(FontWeight.w400, KasyTypeScale.bodyBase, device),
     );
   }
 

package/templates/firebase/lib/core/theme/type_scale.dart

@@ -0,0 +1,77 @@
+import 'package:kasy_kit/core/widgets/responsive_layout.dart';
+
+/// Responsive type scale — explicit font size per role, per breakpoint.
+///
+/// Single source of truth for typography sizes. Instead of a blind global
+/// multiplier, every role declares its own size at each breakpoint — the way a
+/// design tool (Figma variables / modes) or a fluid web scale does it.
+///
+/// The professional pattern this follows: **headings are largest on desktop and
+/// compress on smaller viewports** (a 36px title would feel huge and wrap badly
+/// on a phone), while **body and label text stay constant** for stable,
+/// comfortable reading on every device. Desktop is the authored reference;
+/// tablet and mobile step the headings down.
+///
+/// To re-tune the whole app's typography, edit the numbers here — nothing else.
+/// The live ramp is visible under Design System -> Typography (tabs per
+/// breakpoint).
+class RampSize {
+  /// Phone (< 768).
+  final double mobile;
+
+  /// Tablet (768-1024).
+  final double tablet;
+
+  /// Desktop (>= 1024) — the authored reference.
+  final double desktop;
+
+  /// line-height / font-size. Kept constant across breakpoints so the vertical
+  /// rhythm scales together with the font size.
+  final double lineHeightRatio;
+
+  const RampSize({
+    required this.mobile,
+    required this.tablet,
+    required this.desktop,
+    required this.lineHeightRatio,
+  });
+
+  /// The font size (logical px) for [device].
+  double size(DeviceType device) => switch (device) {
+        DeviceType.small => mobile,
+        DeviceType.medium => tablet,
+        DeviceType.large || DeviceType.xlarge => desktop,
+      };
+
+  /// The line height (logical px) for [device].
+  double lineHeight(DeviceType device) => size(device) * lineHeightRatio;
+}
+
+/// The Kasy type scale: every typographic role's size across the 3 breakpoints.
+class KasyTypeScale {
+  const KasyTypeScale._();
+
+  // Hero / display — large, compress hard on the way down.
+  static const displayLarge =
+      RampSize(mobile: 40, tablet: 48, desktop: 57, lineHeightRatio: 64 / 57);
+  static const displayMedium =
+      RampSize(mobile: 34, tablet: 40, desktop: 45, lineHeightRatio: 52 / 45);
+
+  // Headings — largest on desktop, step down on tablet then mobile.
+  static const heading1 =
+      RampSize(mobile: 28, tablet: 32, desktop: 36, lineHeightRatio: 40 / 36);
+  static const heading2 =
+      RampSize(mobile: 22, tablet: 23, desktop: 24, lineHeightRatio: 32 / 24);
+  static const heading3 =
+      RampSize(mobile: 18, tablet: 19, desktop: 20, lineHeightRatio: 28 / 20);
+  static const heading4 =
+      RampSize(mobile: 16, tablet: 16, desktop: 16, lineHeightRatio: 24 / 16);
+
+  // Body & labels — constant across breakpoints for stable, comfortable reading.
+  static const bodyBase =
+      RampSize(mobile: 16, tablet: 16, desktop: 16, lineHeightRatio: 24 / 16);
+  static const bodySm =
+      RampSize(mobile: 14, tablet: 14, desktop: 14, lineHeightRatio: 20 / 14);
+  static const bodyXs =
+      RampSize(mobile: 12, tablet: 12, desktop: 12, lineHeightRatio: 16 / 12);
+}

package/templates/firebase/lib/core/theme/web_background_sync_web.dart

@@ -2,17 +2,31 @@ import 'package:flutter/material.dart';
 import 'package:web/web.dart' as web;
 
 void syncWebBackgroundColor(Brightness brightness) {
-  final color = brightness == Brightness.dark ? '#000000' : '#FFFFFF';
-  (web.document.documentElement as web.HTMLElement?)
-      ?.style
-      .setProperty('background-color', color);
-  web.document.body?.style.setProperty('background-color', color);
+  final bool dark = brightness == Brightness.dark;
+  // iOS Safari tints its status bar / address bar with the page's background
+  // colour once the Flutter canvas covers the viewport (it ignores the
+  // theme-color meta there). It samples whichever element fills the top of the
+  // viewport — the flutter-view host, not just <body> — so we paint <html>,
+  // <body> AND the Flutter host chain with `surface` (the app bar colour). That
+  // way the Safari bars match the app bar with no seam, no matter which element
+  // Safari reads. The app's own canvas draws over these, so the page background
+  // colour only ever shows in the browser chrome.
+  final String chromeColor = dark ? '#18181B' : '#FFFFFF';
+
+  // Keep the <html data-theme> attribute (set pre-boot by the index.html script)
+  // in sync, so a later reload / hot restart paints the splash + Safari chrome
+  // with the theme currently chosen in the app.
+  final html = web.document.documentElement as web.HTMLElement?;
+  html?.setAttribute('data-theme', dark ? 'dark' : 'light');
+  html?.style.setProperty('background-color', chromeColor);
+  web.document.body?.style.setProperty('background-color', chromeColor);
+
   final views = web.document.querySelectorAll(
     'flutter-view, flt-glass-pane, flt-scene-host',
   );
   for (var i = 0; i < views.length; i++) {
     (views.item(i) as web.HTMLElement?)
         ?.style
-        .setProperty('background-color', color);
+        .setProperty('background-color', chromeColor);
   }
 }

package/templates/firebase/lib/core/utils/image_bytes_loader.dart

@@ -0,0 +1,12 @@
+/// Loads raw image bytes from a remote URL, choosing a platform-specific
+/// strategy so social-profile photos (e.g. Google) import reliably:
+///   - native: a direct HTTP download (see `image_bytes_loader_io.dart`),
+///   - web: an `<img>` + canvas read that avoids the CDN throttling that hits
+///     programmatic `fetch()`/XHR (see `image_bytes_loader_web.dart`).
+///
+/// Both implementations expose the same `loadImageBytes(url)` entry point and
+/// return null (or rethrow) on failure so the caller can keep its fallback.
+library;
+
+export 'image_bytes_loader_io.dart'
+    if (dart.library.js_interop) 'image_bytes_loader_web.dart';

package/templates/firebase/lib/core/utils/image_bytes_loader_io.dart

@@ -0,0 +1,28 @@
+import 'package:dio/dio.dart';
+
+/// Downloads image bytes on native platforms.
+///
+/// Native has no browser fetch throttling, so a direct request with a short
+/// retry on transient errors (HTTP 429/503, timeouts) is reliable. Returns the
+/// raw bytes, or rethrows after exhausting retries so the caller can fall back.
+Future<List<int>?> loadImageBytes(String url) async {
+  const delays = [Duration(milliseconds: 600), Duration(seconds: 2)];
+  for (var attempt = 0; ; attempt++) {
+    try {
+      final response = await Dio().get<List<int>>(
+        url,
+        options: Options(responseType: ResponseType.bytes),
+      );
+      return response.data;
+    } on DioException catch (e) {
+      final status = e.response?.statusCode;
+      final transient = status == 429 ||
+          status == 503 ||
+          e.type == DioExceptionType.connectionTimeout ||
+          e.type == DioExceptionType.receiveTimeout ||
+          e.type == DioExceptionType.connectionError;
+      if (!transient || attempt >= delays.length) rethrow;
+      await Future<void>.delayed(delays[attempt]);
+    }
+  }
+}

package/templates/firebase/lib/core/utils/image_bytes_loader_web.dart

@@ -0,0 +1,56 @@
+import 'dart:async';
+import 'dart:js_interop';
+
+import 'package:web/web.dart' as web;
+
+/// Downloads image bytes on web by loading the URL through an `<img>` element
+/// and reading it back from a canvas.
+///
+/// Browsers serve `<img>` requests reliably, while some CDNs (notably Google's
+/// `lh3.googleusercontent.com`) throttle programmatic `fetch()`/XHR with HTTP
+/// 429 - which is what an HTTP client like dio uses. The image is requested with
+/// CORS (`crossOrigin = 'anonymous'`) so the canvas is not tainted and its
+/// pixels can be exported. Returns null on any failure, so the caller keeps its
+/// fallback avatar.
+Future<List<int>?> loadImageBytes(String url) async {
+  final image = web.HTMLImageElement()..crossOrigin = 'anonymous';
+  final loaded = Completer<bool>();
+  image.addEventListener(
+    'load',
+    (web.Event _) {
+      if (!loaded.isCompleted) loaded.complete(true);
+    }.toJS,
+  );
+  image.addEventListener(
+    'error',
+    (web.Event _) {
+      if (!loaded.isCompleted) loaded.complete(false);
+    }.toJS,
+  );
+  image.src = url;
+
+  final ok = await loaded.future
+      .timeout(const Duration(seconds: 10), onTimeout: () => false);
+  if (!ok || image.naturalWidth == 0) return null;
+
+  final canvas = web.HTMLCanvasElement()
+    ..width = image.naturalWidth
+    ..height = image.naturalHeight;
+  final context = canvas.getContext('2d') as web.CanvasRenderingContext2D?;
+  if (context == null) return null;
+  context.drawImage(image, 0, 0);
+
+  final blobReady = Completer<web.Blob?>();
+  canvas.toBlob(
+    (web.Blob? blob) {
+      blobReady.complete(blob);
+    }.toJS,
+    'image/jpeg',
+    0.92.toJS,
+  );
+  final blob = await blobReady.future;
+  if (blob == null) return null;
+
+  final buffer = await blob.arrayBuffer().toDart;
+  return buffer.toDart.asUint8List();
+}

package/templates/firebase/lib/core/web_screen_width.dart

@@ -0,0 +1,15 @@
+/// Reads the physical screen width (logical/CSS px) so the desktop web scale can
+/// compensate for high OS display scaling WITHOUT reacting to mere window resize.
+///
+/// The browser window width (what the layout uses) changes whenever the user
+/// drags the window narrower — using it to decide the scale made the whole UI
+/// shrink unnecessarily. The *screen* width, on the other hand, only shrinks when
+/// the OS display scale goes up (Windows 150%, Mac scaled modes), which is exactly
+/// when the compensation is actually wanted.
+///
+/// Both implementations expose `currentScreenWidth()`; it returns null off the web
+/// (where the scaling path is never reached anyway).
+library;
+
+export 'web_screen_width_io.dart'
+    if (dart.library.js_interop) 'web_screen_width_web.dart';

package/templates/firebase/lib/core/web_screen_width_io.dart

@@ -0,0 +1,3 @@
+/// Non-web stub: there is no browser screen off the web, and the scaling path is
+/// gated on [kIsWeb] anyway, so this always returns null.
+double? currentScreenWidth() => null;

package/templates/firebase/lib/core/web_screen_width_web.dart

@@ -0,0 +1,10 @@
+import 'package:web/web.dart' as web;
+
+/// The screen width in logical (CSS) px. This shrinks when the OS display scale
+/// goes up (Windows 150%, Mac scaled modes) but does NOT change when the user
+/// merely resizes the browser window — exactly the signal the desktop scale
+/// compensation needs. Returns null if the value is unavailable (0/invalid).
+double? currentScreenWidth() {
+  final int width = web.window.screen.width;
+  return width > 0 ? width.toDouble() : null;
+}

package/templates/firebase/lib/core/web_viewport_scale.dart

@@ -1,32 +1,73 @@
 import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/widgets.dart';
+import 'package:kasy_kit/core/web_screen_width.dart';
 
-/// Maximum render scale applied to the app on web (used on wide viewports).
+/// Maximum render scale applied to the app on web (desktop breakpoint only).
 ///
 /// Flutter web tends to render ~10% larger than equivalent HTML apps at the
 /// browser's 100% zoom, so the whole UI feels oversized on desktop. `0.95`
 /// brings it to the proportion the design targets (i.e. what 95% zoom looked
-/// like) without the user having to touch the browser zoom. On narrower
-/// viewports the effective scale is reduced further (see [kWebViewportScaleTargetWidth]).
+/// like) without the user having to touch the browser zoom. It acts as the cap:
+/// a desktop whose logical width is below the design target (high OS scale)
+/// reduces it further to pin the layout (see [kWebViewportScaleTargetWidth]).
+///
+/// Mobile and tablet web are deliberately left at 1.0 — same as native and as the
+/// device preview, so a developer previewing a phone/tablet sees exactly what the
+/// native build renders. NATIVE is never scaled: the mechanism is gated on
+/// [kIsWeb], so iOS/Android/macOS/Windows apps render at 1.0 and keep respecting
+/// the user's system text-size (accessibility).
 const double kWebViewportScale = 0.95;
 
 /// Design target width (logical px) the desktop shell is laid out against.
 ///
-/// A high-DPI display with OS scaling (Windows at 125/150/175%) reports a
-/// smaller logical viewport width than a Mac at the same physical size, so a
-/// fixed [kWebViewportScale] left the shell laid out narrower than the design
-/// target and it looked cropped (the user had to Ctrl-minus). Scaling by
-/// `width / kWebViewportScaleTargetWidth` instead pins the logical layout width
-/// to this target on those displays, so Mac and Windows render the same.
+/// A display with high OS scaling (Windows at 125/150/175%, or a Mac in a scaled
+/// "more space"/"larger text" mode) reports a smaller logical SCREEN width, so the
+/// `0.95` baseline alone left the shell cramped/cropped (the user had to
+/// Ctrl-minus). When the screen is below this target the scale drops further
+/// (`screenWidth / kWebViewportScaleTargetWidth`) so the full design still fits.
+/// Compared against the SCREEN width, not the window width — see
+/// [webViewportEffectiveScale].
 const double kWebViewportScaleTargetWidth = 1280;
 
-/// Minimum real viewport width (logical px) at which the web scale kicks in.
+/// Viewport width (logical px) where the desktop shell begins.
+///
+/// Below it the layout is mobile/tablet (web renders at natural 1.0); at and above
+/// it the desktop scale applies. Uses the WINDOW width (the layout follows the
+/// window). Tied to the responsive system's desktop breakpoint so they stay in sync.
+const double kWebViewportScaleDesktopBreakpoint = 1024; // DeviceType.large.breakpoint
+
+/// Effective web render scale (pure math, unit-testable — see
+/// web_viewport_scale_test.dart).
+///
+/// [windowWidth] is the browser window width (drives the desktop breakpoint, since
+/// the layout follows the window). [screenWidth] is the physical screen width in
+/// logical px (null = unknown/native).
 ///
-/// The "oversized" problem only shows up on tablet/desktop layouts. On mobile
-/// web (a narrow browser) the app should render at its natural size — exactly
-/// like the native iOS/Android build, which never scales. Tied to the tablet
-/// breakpoint so the rule stays in sync with the rest of the responsive system.
-const double kWebViewportScaleMinWidth = 768; // DeviceType.medium.breakpoint
+/// Returns 1.0 below the desktop breakpoint ([kWebViewportScaleDesktopBreakpoint]):
+/// tablet/phone web render at natural size — same as native and the device preview,
+/// so previewing a phone/tablet shows what the native build does.
+///
+/// On desktop it returns the flat [maxScale] cap (0.95) and only drops BELOW it
+/// when the SCREEN is small (high OS scale), via
+/// `screenWidth / kWebViewportScaleTargetWidth`. Keying off the screen — not the
+/// window — is the whole point: merely resizing the browser window narrower does
+/// NOT shrink the UI (the layout just reflows); the extra shrink happens only when
+/// the screen itself is cramped, which is what the compensation is for. With
+/// [screenWidth] null (native, or web before the screen is known) it stays at the
+/// flat cap.
+///
+/// This is web-only semantics: native never reaches the scaling path (the
+/// [WebViewportScale] widget short-circuits when not on web, via [kIsWeb]), so
+/// iOS/Android and macOS/Windows apps always render at 1.0.
+double webViewportEffectiveScale(
+  double windowWidth, {
+  double? screenWidth,
+  double maxScale = kWebViewportScale,
+}) {
+  if (windowWidth < kWebViewportScaleDesktopBreakpoint) return 1.0;
+  final double basis = screenWidth ?? double.infinity;
+  return (basis / kWebViewportScaleTargetWidth).clamp(0.5, maxScale);
+}
 
 /// Renders [child] uniformly scaled by [scale] on web (no-op elsewhere).
 ///
@@ -52,16 +93,11 @@ class WebViewportScale extends StatelessWidget {
   Widget build(BuildContext context) {
     if (!kIsWeb || scale == 1.0) return child;
     final MediaQueryData mq = MediaQuery.of(context);
-    // Mobile web (narrow browser) renders at its natural size, just like the
-    // native build. The scale only applies from the tablet breakpoint up.
-    if (mq.size.width < kWebViewportScaleMinWidth) return child;
-    // Width-aware scale: on a wide viewport keep [scale] (0.95); on a high-DPI
-    // display with OS scaling the browser reports a smaller logical width, so
-    // scale down just enough to lay the shell out at the design target width
-    // instead of cropping it. Mac (wide) stays at 0.95; Windows at 125/150/175%
-    // shrinks proportionally so both look identical.
-    final double effectiveScale =
-        (mq.size.width / kWebViewportScaleTargetWidth).clamp(0.5, scale);
+    final double effectiveScale = webViewportEffectiveScale(
+      mq.size.width,
+      screenWidth: currentScreenWidth(),
+      maxScale: scale,
+    );
     if (effectiveScale == 1.0) return child;
     final Size logicalSize = Size(
       mq.size.width / effectiveScale,