flet-box 1.0.6 → 1.0.8

package/docs/widget/Row.md

@@ -45,10 +45,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Skeleton.md

@@ -48,10 +48,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Slider.md

@@ -59,10 +59,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Stack.md

@@ -41,10 +41,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Stepper.md

@@ -58,10 +58,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Switch.md

@@ -41,10 +41,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Tabs.md

@@ -39,19 +39,19 @@ Tabs({
 | `onChange` | function | — | Fired with the new index when the tab changes. |
 | `variant` | `'underline'`/`'filled'`/`'slider'`/`'pills'` | `'underline'` | Visual treatment of the tab bar. |
 | `size` | `'small'`/`'medium'`/`'large'` | `'medium'` | Font, padding, icon, and height presets. |
-| `textColor` | Color | `colors.text` | Inactive label/icon color. |
-| `activeTextColor` | Color | `colors.white` | Active label/icon color. |
+| `textColor` | Color | `colors.textSecondary` | Inactive label/icon color. |
+| `activeTextColor` | Color | ink on `slider`, `colors.text` otherwise | Active label/icon color. |
 | `bgColor` | Color | `colors.gray100` | Bar background for `slider`/`filled` variants. |
-| `buttonColor` | Color | `colors.secondary` | Background of the `slider` indicator and `pills`. |
+| `buttonColor` | Color | `color` | Background of the `slider` indicator. |
 | `dividerColor` | Color | `colors.border` | Bottom border for the `underline` variant (when `showDivider`). |
 | `fullWidth` | boolean | `true` | Tabs share the full width; otherwise they hug their content. |
 | `showDivider` | boolean | `true` | Bottom divider under an `underline` bar. |
 | `showIcon` | boolean | `false` | Show the per-tab `icon`. |
-| `iconPosition` | `'left'`/`'right'`/`'top'`/`'bottom'` | `'left'` | Where the icon sits: `'left'` places it before the label; any other value places it after. |
+| `iconPosition` | `'left'`/`'right'`/`'top'`/`'bottom'` | `'left'` | Where the icon sits: `'left'` before the label, `'right'` after it, `'top'`/`'bottom'` stacked above/below the label row. |
 | `iconSize` | number | `18` | Icon size in pixels. |
 | `badges` | array | `[]` | Badge values per tab (`badges[i]`), or set them inline via `{ badge }`. |
 | `alignment` | `'left'`/`'center'`/`'right'` | `'left'` | Accepted for API compatibility; currently has no visual effect. |
-| `color` | Color | `colors.primary` | Accepted for API compatibility; active styling uses `activeTextColor`/`buttonColor` instead. |
+| `color` | Color | `colors.primary` | Accent: the `underline` indicator, the `pills` tint, and the default `buttonColor`. |
 
 These are the props specific to `Tabs`. It also accepts every [common prop](COMMON_PROPS.md).
 

package/docs/widget/Text.md

@@ -49,10 +49,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Tooltip.md

@@ -26,7 +26,8 @@ const tip = Tooltip({
 | `text` | `string` | Visible text content. |
 | `child` | `Widget` | A single child widget. Alias: `children` for a list. |
 | `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | CSS `position` value, or `stack` for centered stacking. |
-| `delay` | `number` | Delay before the animation starts, in milliseconds. |
+| `delay` | `number` | Milliseconds the pointer has to stay on the widget before the tooltip appears. |
+| `tooltipDelay` | `number` | Deprecated alias of `delay`. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
 | `textColor` | `Color` | Color of the button label. |
 | `fontSize` | `number` | Size of the font. |
@@ -56,10 +57,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
@@ -109,24 +114,20 @@ const tip = Tooltip({
 
 ## Tips
 
-- Attach it to any widget via child; the tooltip is a separate portal, so overflow
-- hidden ancestors do not cut it off.
-- delay controls how long the pointer must rest before the tooltip appears; lower it
-- for dense toolbars, raise it for error-prone hints.
-- The bubble is clamped to the viewport edges, so top/left placements can sit slightly
-- inside the window bounds.
+- Attach it to any widget via child; the tooltip is a separate portal, so overflow hidden ancestors do not cut it off.
+- delay controls how long the pointer must rest before the tooltip appears; lower it for dense toolbars, raise it for error-prone hints.
+- The bubble is clamped to the viewport edges, so top/left placements can sit slightly inside the window bounds.
 
 ## Accessibility
 
-- The wrapped child keeps its focus handlers, so keyboard users tabbing onto it get
-- the same tooltip as mouse hover.
+- The wrapped child keeps its focus handlers, so keyboard users tabbing onto it get the same tooltip as mouse hover.
 
 ## Behavior
 
-- The tooltip hides itself on window scroll or resize and removes its body portal plus
-- listeners on unmount.
-- The wrapped child gains showTooltip, hideTooltip, updateContent, and updatePosition
-- helpers for imperative control.
+- The tooltip hides itself on window scroll or resize and removes its body portal plus listeners on unmount.
+- The wrapped child gains showTooltip, hideTooltip, updateContent, and updatePosition helpers for imperative control.
+- A pointer that leaves before the wait is over never shows the bubble: leaving clears the timer.
+- tooltipDelay is the old name of delay. When both are given, delay wins.
 
 ## Related widgets
 

package/docs/widget/TreeView.md

@@ -72,10 +72,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Video.md

@@ -44,10 +44,14 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
@@ -121,7 +125,7 @@ const clip = Video({
 ## Continue reading
 
 - **Previous:** [Audio](Audio.md)
-- **Next:** [DraggBox](DraggBox.md)
+- **Next:** [Maps](Maps.md)
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 7 · Media and drag & drop** (2 of 4).
+You are reading **Chapter 7 · Media and drag & drop** (2 of 5).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Declarative, zero-dependency UI framework in vanilla JS — ship web, PWA, Android and iOS from one codebase",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,7 @@
     "dev": "node bin/cli.js run --hot",
     "build": "node bin/cli.js createBundle",
     "release": "node bin/cli.js release",
-    "test": "node scripts/check-widgets.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-router-base.mjs && node scripts/check-cli-install.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
+    "test": "node scripts/check-widgets.mjs && node scripts/check-widget-scale.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-api-propscan.mjs && node scripts/check-router-base.mjs && node scripts/check-clean-ui.mjs && node scripts/check-ota-assets.mjs && node scripts/check-pwa-shell.mjs && node scripts/check-cli-install.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
     "test:browser": "node scripts/run-browser-tests.mjs"
   },
   "keywords": [

package/src/animations/AnimatedBox.js

@@ -381,7 +381,10 @@ const generateKeyframes = (animations) => {
 
     animations.forEach((anim) => {
       const effect = effectMap[anim.effect] || anim.effect;
-      const { from, to, reverse = true } = anim;
+      // Straight `from → to` is the default: a one-shot entry animation must hold
+      // `to`. Cycling back is opt-in, or every documented `opacity 0 → 1` faded
+      // to invisible again at 100%.
+      const { from, to, reverse = false } = anim;
 
       // A descriptor without `from`/`to` is malformed. Skip it with a warning
       // rather than throwing a TypeError out of the caller's entire render.

package/src/animations/MatrixRain.js

@@ -219,8 +219,9 @@ export const MatrixRain = (props = {}) => {
   // above), because the canvas has no parent until the caller appends it.
 
   /**
-   * Stops the animation loop, removes event listeners, disconnects the
-   * ResizeObserver, and removes the canvas from the DOM.
+   * Stops the animation loop, removes the window listeners and disconnects the
+   * ResizeObserver. The canvas stays where it is: the caller owns the element and
+   * decides whether to remove it, which is what the module contract documents.
    *
    * @returns {void}
    */
@@ -228,7 +229,6 @@ export const MatrixRain = (props = {}) => {
     if (animationId) cancelAnimationFrame(animationId);
     window.removeEventListener("resize", handleResize);
     if (resizeObserver) resizeObserver.disconnect();
-    if (canvas && canvas.parentNode) canvas.parentNode.removeChild(canvas);
   };
 
   // Chain cleanup so any previously assigned _cleanup is also called

package/src/core/hmr-client.js

@@ -1,4 +1,5 @@
 // src/core/hmr-client.js
+import { getAllRam, saveRam } from "../services/RamStore.js";
 
 /** @type {WebSocket|null} Active WebSocket connection to the HMR server. */
 let ws = null;
@@ -11,6 +12,83 @@ let ws = null;
  */
 let modules = new Map();
 
+/** sessionStorage key that carries `useState` RAM across a hot reload. */
+const STATE_KEY = "__fletbox_hmr_state";
+
+/** How many seconds to keep retrying after the server drops the socket. */
+const MAX_RETRIES = 30;
+
+let retries = 0;
+let everOpened = false;
+let retryTimer = null;
+
+/**
+ * The live state, JSON-safe.
+ *
+ * `useState` lives in a plain Map, so a value that cannot cross a page reload
+ * (a DOM node, a circular graph, a function) is skipped rather than poisoning
+ * the whole snapshot.
+ *
+ * @returns {Object}
+ */
+const snapshotRam = () => {
+  const snapshot = {};
+  for (const [key, value] of Object.entries(getAllRam())) {
+    try {
+      JSON.stringify(value);
+      snapshot[key] = value;
+    } catch (e) {
+      // Not serialisable: this key starts from its default on the next page.
+    }
+  }
+  return snapshot;
+};
+
+/**
+ * Reload the page without losing the developer's place: state is written to
+ * sessionStorage first and put back by `initHMR` on the next load.
+ *
+ * @returns {void}
+ */
+const reloadKeepingState = () => {
+  try {
+    sessionStorage.setItem(STATE_KEY, JSON.stringify(snapshotRam()));
+  } catch (e) {
+    // Private mode, quota, no sessionStorage: reload anyway.
+  }
+  window.location.reload();
+};
+
+/**
+ * Push a previous snapshot back into the RAM store.
+ *
+ * Runs after the app module has already rendered, which is fine: `saveRam`
+ * notifies subscribers, so every `useState` binding repaints with the value it
+ * had before the reload.
+ *
+ * @returns {number} keys restored
+ */
+const restoreRam = () => {
+  let raw = null;
+  try {
+    raw = sessionStorage.getItem(STATE_KEY);
+  } catch (e) {
+    return 0;
+  }
+  if (!raw) return 0;
+  let saved;
+  try {
+    saved = JSON.parse(raw);
+  } catch (e) {
+    return 0;
+  }
+  let restored = 0;
+  for (const [key, value] of Object.entries(saved)) {
+    if (saveRam(key, value)) restored++;
+  }
+  return restored;
+};
+
 /**
  * Initialises the Hot Module Replacement (HMR) client.
  *
@@ -23,19 +101,44 @@ let modules = new Map();
  * - `hmr` — a file changed; delegates to `handleHMR`.
  * - `reload` — the server requests a full page reload.
  *
- * On disconnect the client waits 500 ms then reloads the page so the
- * developer always sees a fresh state.
+ * A dropped socket is retried, not reloaded: reloading into a server that is
+ * still restarting (or a tunnel that closed an idle socket) produced an error
+ * page and then a reload loop. When the connection *re*-establishes, the code
+ * the page runs is stale and the page reloads — with its state.
+ *
+ * @returns {void}
  */
 export const initHMR = () => {
+  const restored = restoreRam();
+  if (restored) console.log(`♻️ HMR restored ${restored} state key(s)`);
+  connect();
+};
+
+/**
+ * @returns {void}
+ */
+const connect = () => {
   const protocol = location.protocol === "https:" ? "wss:" : "ws:";
   ws = new WebSocket(`${protocol}//${location.host}`);
 
   ws.onopen = () => {
+    retries = 0;
+    if (everOpened) {
+      console.log("🔥 HMR reconnected — the page is stale, reloading");
+      reloadKeepingState();
+      return;
+    }
+    everOpened = true;
     console.log("🔥 HMR connected");
   };
 
   ws.onmessage = (event) => {
-    const data = JSON.parse(event.data);
+    let data;
+    try {
+      data = JSON.parse(event.data);
+    } catch (e) {
+      return; // a proxy or tunnel injecting a non-JSON frame must not kill the client
+    }
 
     if (data.type === "request-modules") {
       // Send the list of registered module URLs back to the server.
@@ -50,14 +153,19 @@ export const initHMR = () => {
     }
 
     if (data.type === "reload") {
-      console.log("🔄 Full reload triggered");
-      window.location.reload();
+      console.log("🔄 Reload triggered by the server");
+      reloadKeepingState();
     }
   };
 
   ws.onclose = () => {
-    console.log("🔄 HMR disconnected, reloading...");
-    setTimeout(() => window.location.reload(), 500);
+    if (retries >= MAX_RETRIES) {
+      console.warn("🔌 HMR gave up: the dev server is unreachable. Refresh to retry.");
+      return;
+    }
+    retries++;
+    clearTimeout(retryTimer);
+    retryTimer = setTimeout(connect, 1000);
   };
 };
 
@@ -68,16 +176,13 @@ export const initHMR = () => {
  *
  * - `css` — hot-reloads matching `<link>` stylesheets by appending a cache-
  *   busting timestamp to their `href`, avoiding a full page reload.
- * - `exports-changed` — the module's public API changed in a way that cannot
- *   be patched in-place; triggers a full reload.
- * - anything else — re-imports the changed module via a dynamic `import()` and
- *   dispatches an `hmr:update` CustomEvent so components can react. Falls back
- *   to a full reload if the import fails.
+ * - anything else — the module graph cannot be rebound in place, so the page
+ *   reloads and the `useState` RAM is restored from the snapshot.
  *
  * @param {{ file: string, changeType: string }} data - The HMR payload from the server.
  * @param {string} data.file - Relative path of the changed file.
- * @param {string} data.changeType - The kind of change (`"css"`,
- *   `"exports-changed"`, or any other string for a JS hot-swap).
+ * @param {string} data.changeType - The kind of change (`"css"`, or any other
+ *   string for a reload with the state kept).
  */
 const handleHMR = (data) => {
   const { file, changeType } = data;
@@ -97,26 +202,16 @@ const handleHMR = (data) => {
     return;
   }
 
-  if (changeType === "exports-changed") {
-    console.log(`📦 Exports changed in ${file}, reloading...`);
-    window.location.reload();
-    return;
-  }
-
-  // JS code change — attempt a hot swap via dynamic import.
-  console.log(`🔥 Hot reloading: ${file}`);
-  const url = `/${file}?t=${Date.now()}`;
-  import(url)
-    .then((module) => {
-      // Notify any listening components that the module was updated.
-      window.dispatchEvent(
-        new CustomEvent("hmr:update", { detail: { file, module } }),
-      );
-    })
-    .catch((err) => {
-      console.error("HMR import failed:", err);
-      window.location.reload();
-    });
+  if (changeType === "exports-changed") console.log(`📦 Exports changed in ${file}`);
+  // A JS change reloads the page and puts the state back.
+  //
+  // Re-importing the file is not a swap: a widget that already closed over the
+  // old function keeps the old function, and the fresh module instance nobody
+  // references changes nothing on screen. What the developer should see is the
+  // new code, so the module graph is re-fetched — and because `useState` RAM
+  // survives the reload, that is not paid for with the form you were filling.
+  console.log(`🔥 Reload with state: ${file}`);
+  reloadKeepingState();
 };
 
 /**