flet-box 1.0.2 → 1.0.4

package/src/tools/useState.js

@@ -1,5 +1,6 @@
 // src/tools/useState.js
 import { saveRam, getRam, subscribeRam } from "../services/RamStore.js";
+import { createReactiveValue, setImperativeReadListener } from "../widget-factory/reactiveValue.js";
 
 // Store callbacks for each state key
 const subscribers = new Map();
@@ -7,6 +8,13 @@ const subscribers = new Map();
 // 🔥 Store widgets by state key for automatic updates
 const widgetsByKey = new Map();
 
+// Keys the component reads *structurally* — inside a template literal, a
+// conditional, a list. Those need the app render even when a widget is bound to
+// the key, because a surgical prop patch cannot change what the component
+// computes. A key passed straight into a prop is never listed here.
+const imperativeKeys = new Set();
+setImperativeReadListener((key) => imperativeKeys.add(key));
+
 // Global render function (set by runApp)
 let globalRender = null;
 let renderTimeout = null;
@@ -35,6 +43,56 @@ const triggerRender = () => {
   }, 0);
 };
 
+let ramDispatcherReady = false;
+
+/**
+ * Installs **one** RamStore subscriber that dispatches to the widgets and
+ * callbacks registered for the key that actually changed.
+ *
+ * RamStore walks a flat subscriber array on every `saveRam`, so registering one
+ * subscriber per key made a single state change cost O(number of keys) — with
+ * every callback immediately rejecting the key. One dispatcher makes the lookup
+ * O(1), and the work proportional to what the key really has bound.
+ *
+ * @returns {void}
+ */
+const ensureRamDispatcher = () => {
+  if (ramDispatcherReady) return;
+  ramDispatcherReady = true;
+
+  const unsubscribe = subscribeRam((changedKey, newValue, oldValue) => {
+    const callbacks = subscribers.get(changedKey);
+    // A key nobody ever passed to `useState` has no listeners: ignore it.
+    if (!callbacks) return;
+
+    // 1. Surgical update: patch only the widgets bound to this key.
+    const bound = widgetsByKey.get(changedKey);
+    let handled = 0;
+    if (bound) {
+      bound.forEach((propNames, widget) => {
+        if (!widget || typeof widget.update !== "function") return;
+        propNames.forEach((propName) => {
+          widget.update({ [propName]: newValue });
+          handled++;
+        });
+      });
+    }
+
+    // 2. Notify the manual subscribers.
+    callbacks.forEach((callback) => callback(newValue, oldValue));
+
+    // 3. Re-render the app when nothing was bound, or when the component also
+    // reads this key structurally (a template literal, a conditional, a list):
+    // the surgical patch above cannot change what the component computes.
+    if (handled === 0 || imperativeKeys.has(changedKey)) triggerRender();
+  });
+
+  if (typeof window !== "undefined") {
+    if (!window._useStateCleanups) window._useStateCleanups = [];
+    window._useStateCleanups.push(unsubscribe);
+  }
+};
+
 /**
  * Registers a widget instance so it receives automatic prop updates whenever
  * the state value associated with `key` changes.
@@ -45,31 +103,54 @@ const triggerRender = () => {
  * @returns {void}
  */
 export const registerWidget = (key, widget, propName) => {
-  if (!widgetsByKey.has(key)) {
-    widgetsByKey.set(key, new Set());
+  // Two levels — key -> widget -> prop names — so looking a widget up is O(1).
+  // A flat Set with a linear scan made registering N widgets on the same key
+  // O(N^2): 1,600 widgets on one key cost ~44 ms.
+  let perWidget = widgetsByKey.get(key);
+  if (!perWidget) {
+    perWidget = new Map();
+    widgetsByKey.set(key, perWidget);
+  }
+  let propNames = perWidget.get(widget);
+  if (!propNames) {
+    propNames = new Set();
+    perWidget.set(widget, propNames);
   }
-  widgetsByKey.get(key).add({ widget, propName });
+  // Idempotent: rebuilding the same widget position must not stack duplicates.
+  const already = propNames.has(propName);
+  propNames.add(propName);
 
-  // Set initial value if the state already exists
+  // Push the current value straight away when the widget can already take it.
+  // (During construction `update` does not exist yet — the value has just been
+  // applied by the factory, so there is nothing to push.)
   const currentValue = getRam(key);
   if (currentValue !== undefined && widget && widget.update) {
     widget.update({ [propName]: currentValue });
   }
 
-  // Patch the widget's cleanup to also remove it from the registry when destroyed
-  const originalCleanup = widget._cleanup;
-  widget._cleanup = () => {
-    const widgets = widgetsByKey.get(key);
-    if (widgets) {
-      for (const item of widgets) {
-        if (item.widget === widget) {
-          widgets.delete(item);
-          break;
-        }
-      }
-    }
-    if (originalCleanup) originalCleanup();
+  if (already) return;
+
+  // Release the binding through `onUnmount`, which the framework fires on BOTH
+  // teardown paths. Patching `_cleanup` here (the previous approach) leaked: the
+  // lifecycle observer never calls `_cleanup`, so a widget removed without a full
+  // app rebuild stayed registered forever and kept receiving updates.
+  const release = () => {
+    const map = widgetsByKey.get(key);
+    const props = map && map.get(widget);
+    if (!props) return;
+    props.delete(propName);
+    if (props.size === 0) map.delete(widget);
   };
+
+  if (typeof widget.onUnmount === "function") {
+    widget.onUnmount(release);
+  } else {
+    const originalCleanup = widget._cleanup;
+    widget._cleanup = () => {
+      release();
+      if (originalCleanup) originalCleanup();
+    };
+  }
 };
 
 /**
@@ -80,15 +161,8 @@ export const registerWidget = (key, widget, propName) => {
  * @returns {void}
  */
 export const unregisterWidget = (key, widget) => {
-  const widgets = widgetsByKey.get(key);
-  if (widgets) {
-    for (const item of widgets) {
-      if (item.widget === widget) {
-        widgets.delete(item);
-        break;
-      }
-    }
-  }
+  const perWidget = widgetsByKey.get(key);
+  if (perWidget) perWidget.delete(widget);
 };
 
 /**
@@ -117,36 +191,13 @@ export const useState = (key, initialState, widget = null, propName = null) => {
     saveRam(key, currentValue);
   }
 
-  // Set up a single RamStore subscriber per key
-  if (!subscribers.has(key)) {
-    subscribers.set(key, new Set());
-
-    // Listen to RamStore changes for this key
-    const unsubscribe = subscribeRam((changedKey, newValue, oldValue) => {
-      if (changedKey === key) {
-        // 🔥 Push the new value to all registered widgets for this key
-        const widgets = widgetsByKey.get(key);
-        if (widgets) {
-          widgets.forEach(({ widget, propName }) => {
-            if (widget && widget.update) {
-              widget.update({ [propName]: newValue });
-            }
-          });
-        }
-
-        // Notify all subscriber callbacks
-        const callbacks = subscribers.get(key);
-        callbacks.forEach((callback) => callback(newValue, oldValue));
-
-        // Trigger a global re-render
-        triggerRender();
-      }
-    });
-
-    // Track the unsubscribe handle for hot-reload cleanup
-    if (!window._useStateCleanups) window._useStateCleanups = [];
-    window._useStateCleanups.push(unsubscribe);
-  }
+  // Register the key so the shared dispatcher knows it has listeners. Previously
+  // every key installed its OWN RamStore subscriber, and RamStore notifies all of
+  // them on every save — so one state change cost O(number of keys), each callback
+  // rejecting the key immediately. One dispatcher makes it O(1) + the work for the
+  // key that actually changed.
+  if (!subscribers.has(key)) subscribers.set(key, new Set());
+  ensureRamDispatcher();
 
   // 🔥 Register the widget for automatic updates if one was provided
   if (widget && propName) {
@@ -194,18 +245,11 @@ export const useState = (key, initialState, widget = null, propName = null) => {
     };
   };
 
-  // 🔥 Create a reactive value object so WidgetFactory can detect state bindings automatically
-  const reactiveValue = {
-    _isReactive: true,
-    _stateKey: key,
-    _value: currentValue,
-    valueOf() {
-      return this._value;
-    },
-    toString() {
-      return String(this._value);
-    },
-  };
+  // 🔥 A LIVE reactive value: reads the store on every access (so it never goes
+  // stale) and carries the key, so WidgetFactory can auto-bind any prop it is
+  // passed to. That binding is what makes a state change update **only the widget
+  // that uses it** instead of rebuilding the app.
+  const reactiveValue = createReactiveValue(() => getRam(key), key);
 
   // Return an array matching React's useState pattern: [value, setter, subscriber]
   return [reactiveValue, setState, subscribe];
@@ -242,6 +286,9 @@ export const cleanupUseState = () => {
   }
   subscribers.clear();
   widgetsByKey.clear();
+  imperativeKeys.clear();
+  // The dispatcher was unsubscribed above, so a later call must reinstall it.
+  ramDispatcherReady = false;
   globalRender = null;
   if (renderTimeout) clearTimeout(renderTimeout);
 };

package/src/utils/getWidgetProps.js

@@ -10,7 +10,9 @@
  * // { text: 'Click', variant: 'filled', color: '#007aff' }
  */
 export const getWidgetProps = (widget) => {
-  return { ...(widget._props || {}) };
+  // The factory stores props in `_originalProps`. `_props` was never written by
+  // anything, so this always returned `{}` — Inspector printed no props at all.
+  return { ...(widget._originalProps || {}) };
 };
 
 /**
@@ -20,7 +22,7 @@ export const getWidgetProps = (widget) => {
  * @returns {any} Prop value or undefined
  */
 export const getWidgetProp = (widget, propName) => {
-  return widget._props ? widget._props[propName] : undefined;
+  return widget._originalProps ? widget._originalProps[propName] : undefined;
 };
 
 /**
@@ -29,7 +31,7 @@ export const getWidgetProp = (widget, propName) => {
  * @returns {string} Formatted props string
  */
 export const stringifyWidgetProps = (widget) => {
-  return JSON.stringify(widget._props || {}, null, 2);
+  return JSON.stringify(widget._originalProps || {}, null, 2);
 };
 
 export default { getWidgetProps, getWidgetProp, stringifyWidgetProps };

package/src/widget-factory/assignProps.js

@@ -1,5 +1,6 @@
 // core/assignProps.js
 import { setStyles } from "./tools.js";
+import { resolveReactive } from "./reactiveValue.js";
 
 /**
  * Extracts the real value from a prop that may be a reactive accessor or a
@@ -14,15 +15,7 @@ import { setStyles } from "./tools.js";
  * @param {*} val - The raw prop value (may be reactive or plain).
  * @returns {*} The resolved runtime value.
  */
-const getValue = (val) => {
-  if (typeof val === "function" && val._isReactive) {
-    return val();
-  }
-  if (val && typeof val === "object" && val._isReactive === true) {
-    return val._value !== undefined ? val._value : val.valueOf();
-  }
-  return val;
-};
+const getValue = resolveReactive;
 
 /**
  * HTML attributes whose mere presence means "true". Writing them through
@@ -110,7 +103,11 @@ export const assignProps = (widget, props) => {
     // ============================================================
     // 2. TEXT
     // ============================================================
-    if (props.textContent !== undefined) {
+    // `null` is `processProps`' sentinel for "this prop set carries no text".
+    // Only an explicitly present value (including "") may touch textContent:
+    // assigning null stringifies to "" and therefore REMOVES every child, which
+    // silently wiped widgets on any `update()` that did not re-pass `child`.
+    if (props.textContent !== undefined && props.textContent !== null) {
       const textValue = getValue(props.textContent);
       if (widget.tagName === "INPUT" || widget.tagName === "TEXTAREA") {
         if (widget.value !== textValue) widget.value = textValue;

package/src/widget-factory/processProps.js

@@ -1,6 +1,7 @@
 // core/processProps.js
 import { getPropDefinition, ATTRIBUTE_DOM_SET } from "./translateProps.js";
 import { toREM } from "./remTool.js"; // Centralized REM conversion utility
+import { resolveReactive } from "./reactiveValue.js";
 
 /**
  * Processes raw props and classifies them into:
@@ -26,8 +27,12 @@ export const processProps = (props, tag = "div", widgetName = null) => {
   // Derive widget name from tag (e.g., 'div' → 'Div', 'span' → 'Span')
   const name = widgetName || tag.charAt(0).toUpperCase() + tag.slice(1);
 
-  for (const [key, value] of Object.entries(props)) {
-    if (value === undefined || value === null) continue;
+  for (const [key, rawValue] of Object.entries(props)) {
+    if (rawValue === undefined || rawValue === null) continue;
+    // Resolve the reactive-prop protocol once, here. A live value must be READ
+    // now so `width: count` yields a number (and gets its px/rem unit), and a
+    // function must never reach a CSS assignment.
+    const value = resolveReactive(rawValue);
 
     // `style` is deliberately NOT part of the API: FletBox uses flat, aliased
     // CSS props. Fail loudly instead of silently ignoring the object.

package/src/widget-factory/reactiveValue.js

@@ -0,0 +1,147 @@
+/**
+ * @file reactiveValue.js
+ * @description
+ * The reactive-prop protocol shared by `useState`, the widget factory and the
+ * prop pipeline.
+ *
+ * A prop value may be a *reactive value*: an object or function flagged with
+ * `_isReactive` that reports the current value of a state key. The factory
+ * resolves it whenever the prop is applied, and — when the value carries a
+ * `_stateKey` — it also **subscribes** the widget to that key so a later change
+ * updates only this widget instead of re-rendering the whole app.
+ *
+ * Two shapes are supported:
+ *
+ *  - **Live** (what `useState` returns): a callable that reads the store on every
+ *    call. `valueOf`/`toString` also read live, so `${count}`, `count + 1` and
+ *    CSS assignment all get the current value.
+ *  - **Snapshot** (legacy): an object with a frozen `_value`. Still resolved, but
+ *    it cannot auto-subscribe because it has no live source.
+ *
+ * @module widget-factory/reactiveValue
+ */
+
+/**
+ * True while `resolveReactive` is reading a value on behalf of the factory.
+ *
+ * The distinction matters: a read the FACTORY performs (to fill a prop) is a
+ * direct binding, but a read the COMPONENT performs (`${count}`, `count > 3`,
+ * `count.valueOf()`) means the value also drives structure or computation, so the
+ * app has to re-run as well. Reconciling the two is what keeps
+ * `Text({ text: count })` surgical without breaking a sibling conditional.
+ */
+let resolving = false;
+
+/**
+ * Depth of the component-render pass, so reads in an event handler or a timer
+ * (which run outside the pass) do not mark a key as structurally read.
+ */
+let renderPassDepth = 0;
+
+/** Called with the state key when the component reads a reactive value. */
+let onImperativeRead = null;
+
+/**
+ * Registers the listener told about structural reads. The state module uses it to
+ * know which keys still need the app render in addition to the surgical patch.
+ *
+ * @param {(key: string) => void} listener
+ * @returns {void}
+ */
+export const setImperativeReadListener = (listener) => {
+  onImperativeRead = listener;
+};
+
+/** Marks the start of a component-render pass. */
+export const beginRenderPass = () => {
+  renderPassDepth++;
+};
+
+/** Marks the end of a component-render pass. */
+export const endRenderPass = () => {
+  if (renderPassDepth > 0) renderPassDepth--;
+};
+
+/**
+ * True when `val` is a reactive value (live or snapshot).
+ *
+ * @param {*} val
+ * @returns {boolean}
+ */
+export const isReactive = (val) => Boolean(val) && val._isReactive === true;
+
+/**
+ * The state key a reactive value is bound to, or `null` when it is not bound.
+ *
+ * @param {*} val
+ * @returns {string|null}
+ */
+export const reactiveKeyOf = (val) => (isReactive(val) ? val._stateKey ?? null : null);
+
+/**
+ * Resolves a reactive value to its current value. Plain values pass through.
+ *
+ * A live value is invoked, which is what makes it stay current: every time the
+ * prop is re-applied the store is read again. The read is flagged as a factory
+ * read so it is not mistaken for a structural one.
+ *
+ * @param {*} val
+ * @returns {*}
+ */
+export const resolveReactive = (val) => {
+  if (typeof val === "function" && val._isReactive) {
+    resolving = true;
+    try {
+      return val();
+    } finally {
+      resolving = false;
+    }
+  }
+  if (val && typeof val === "object" && val._isReactive === true) {
+    return val._value !== undefined ? val._value : val.valueOf();
+  }
+  return val;
+};
+
+/**
+ * Builds the live reactive value returned by `useState`.
+ *
+ * It is a **function** (so `resolveReactive` calls it and always gets the
+ * current value) decorated with `valueOf`/`toString` (so template literals and
+ * arithmetic work) and a `_value` getter (so the legacy `state._value` read
+ * keeps working — now live instead of frozen).
+ *
+ * Every read that the component itself performs during a render pass is reported
+ * through `onImperativeRead`, because such a read means the value is consumed
+ * structurally and the app must re-render too.
+ *
+ * @param {() => *} read - Reads the current value from the store.
+ * @param {string} key - The state key this value is bound to.
+ * @returns {Function} The live reactive value.
+ */
+export const createReactiveValue = (read, key) => {
+  const live = () => {
+    const value = read();
+    if (!resolving && renderPassDepth > 0 && onImperativeRead) onImperativeRead(key);
+    return value;
+  };
+  live._isReactive = true;
+  live._stateKey = key;
+  live.valueOf = () => live();
+  live.toString = () => String(live());
+  Object.defineProperty(live, "_value", {
+    get: () => live(),
+    configurable: true,
+  });
+  return live;
+};
+
+export default {
+  isReactive,
+  reactiveKeyOf,
+  resolveReactive,
+  createReactiveValue,
+  setImperativeReadListener,
+  beginRenderPass,
+  endRenderPass,
+};

package/src/widget-factory/warnings.js

@@ -7,6 +7,14 @@ const IS_DEV = typeof FLETBOX_DEV !== 'undefined' ? FLETBOX_DEV : true;
 const suggestionCache = new Map();
 let propNames = [];
 
+// Props already reported. Without this, every prop *application* re-printed the
+// whole block — a captured stack trace plus ~8 styled console calls — so a widget
+// carrying a single unknown prop paid ~137 µs on every `update()`, roughly 400×
+// the cost of a known prop. Because `update()` re-applies every original prop, one
+// unknown prop slowed that widget for its whole lifetime.
+const warnedProps = new Set();
+const warnedDeprecated = new Set();
+
 export function setPropNames(names) {
   propNames = names;
   try { if (typeof window !== 'undefined') window.__FLETBOX_PROP_NAMES = names; } catch(e){}
@@ -216,6 +224,9 @@ function printDocs(prop) {
 
 export function warnUnknownProp(propName, context = {}) {
   if (!IS_DEV) return;
+  // Report each unknown prop once, not once per application.
+  if (warnedProps.has(propName)) return;
+  warnedProps.add(propName);
 
   const suggestions = getSuggestions(propName);
   const location = getCallLocation();
@@ -231,6 +242,10 @@ export function warnUnknownProp(propName, context = {}) {
 
 export function warnDeprecatedProp(propName, replacement = null, context = {}) {
   if (!IS_DEV) return;
+  // Same reasoning as `warnUnknownProp`: one report per prop/replacement pair.
+  const deprecatedKey = `${propName}\u0000${replacement || ""}`;
+  if (warnedDeprecated.has(deprecatedKey)) return;
+  warnedDeprecated.add(deprecatedKey);
 
   const location = getCallLocation();
 

package/src/widget-factory/widgetFactory.js

@@ -8,6 +8,29 @@ import { processProps } from "./processProps.js";
 import { assignProps } from "./assignProps.js";
 import { stackPosition } from "./stackPosition.js";
 import { addChildren, removePropChildren } from "./addChildren.js";
+import { reactiveKeyOf } from "./reactiveValue.js";
+import { registerWidget } from "../tools/useState.js";
+
+/**
+ * Auto-binds reactive props to their state key.
+ *
+ * A prop whose value is a live reactive (what `useState` returns) carries the key
+ * it came from, so the factory can subscribe this widget to that key. A later
+ * change then updates **only this widget** instead of rebuilding the whole app —
+ * which is what makes the plain
+ * `const [color, setColor] = useState("color", "red"); Widget({ bgColor: color })`
+ * syntax surgical.
+ *
+ * @param {HTMLElement} widget - The widget being built or updated.
+ * @param {Object} props - The props to scan.
+ * @returns {void}
+ */
+const bindReactiveProps = (widget, props) => {
+  for (const [prop, value] of Object.entries(props || {})) {
+    const key = reactiveKeyOf(value);
+    if (key) registerWidget(key, widget, prop);
+  }
+};
 
 /**
  * Main widget factory. Creates a fully functional DOM widget with reactivity,
@@ -96,6 +119,7 @@ export function WidgetFactory(tag, customProps = {}) {
   // ============================================================
   const initialProps = processProps(finalProps, finalTag, widgetName);
   assignProps(widget, initialProps);
+  bindReactiveProps(widget, finalProps);
   stackPosition(widget, finalProps);
 
   if (finalProps.child !== undefined) {
@@ -160,6 +184,9 @@ export function WidgetFactory(tag, customProps = {}) {
 
       const processed = processProps(merged, finalTag, widgetName);
       assignProps(widget, processed);
+      // Only the incoming keys can introduce a new binding; the ones present at
+      // construction were registered then.
+      bindReactiveProps(widget, normalized);
       stackPosition(widget, merged);
 
       if (hasChild || hasChildren) {

package/src/widgets/Accordion.js

@@ -156,11 +156,12 @@ export const Accordion = (props) => {
     titleElement.style.fontSize = `${currentTitleSize}px`;
     titleElement.style.fontWeight = currentTitleWeight;
 
-    // Swap icon based on current expanded state
-    iconElement.setAttribute(
-      "name",
-      isExpanded ? currentIconExpanded : currentIconCollapsed,
-    );
+    // Swap icon based on current expanded state. `Icon` renders its glyph as
+    // TEXT (a material-icons ligature), so setting a `name` attribute changed
+    // nothing and the chevron stayed on `chevron_right` forever.
+    iconElement.textContent = isExpanded
+      ? currentIconExpanded
+      : currentIconCollapsed;
     iconElement.style.color = currentIconColor;
     iconElement.style.fontSize = `${currentIconSize}px`;
 

package/src/widgets/Audio.js

@@ -74,6 +74,9 @@ export const Audio = (props) => {
   let duration = 0;
   let durationPoll = null;
   let audioContextFallbackAttempted = false;
+  // Set on unmount so deferred work (the duration fallback, in-flight fetches)
+  // never touches a discarded widget.
+  let disposed = false;
 
   /**
    * Recalculates the current playback position and fires the progress callbacks.
@@ -139,19 +142,25 @@ export const Audio = (props) => {
    * cannot determine duration without fully downloading the file.
    */
   const fallbackGetDuration = async () => {
-    if (audioContextFallbackAttempted) return;
+    if (audioContextFallbackAttempted || disposed) return;
     audioContextFallbackAttempted = true;
 
     try {
       const response = await fetch(src);
       const arrayBuffer = await response.arrayBuffer();
+      if (disposed) return;
       const audioContext = new (
         window.AudioContext || window.webkitAudioContext
       )();
-      const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
-      const durationSeconds = audioBuffer.duration;
-      setDuration(durationSeconds);
-      audioContext.close();
+      // `close()` must run even when decoding fails: AudioContexts are a capped
+      // resource (~6 per page in Chromium) and leaking them makes every later
+      // context fail to start, which breaks the fallback for good.
+      try {
+        const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+        setDuration(audioBuffer.duration);
+      } finally {
+        audioContext.close();
+      }
     } catch (err) {
       console.warn("[Audio] Fallback duration fetch failed:", err);
     }
@@ -178,16 +187,29 @@ export const Audio = (props) => {
   audio.addEventListener("error", (e) => console.warn("[Audio] Error:", e));
 
   // Kick off duration detection immediately; if unavailable after 2 s, use fetch fallback
+  let fallbackTimer = null;
   if (!tryGetDurationFromAudio()) {
     pollDuration();
-    setTimeout(() => {
+    fallbackTimer = setTimeout(() => {
+      fallbackTimer = null;
       if (!duration) fallbackGetDuration();
     }, 2000);
   }
 
-  // Cancel the duration polling interval when the widget unmounts
+  // Release everything the widget owns on unmount. The 2 s fallback timer was
+  // never stored, so after teardown it still fetched the whole file and spun up
+  // an AudioContext (and called onLoad) for a widget that no longer exists — and
+  // a tree rebuild does that on every state change.
   audio.onUnmount(() => {
-    if (durationPoll) clearInterval(durationPoll);
+    disposed = true;
+    if (durationPoll) {
+      clearInterval(durationPoll);
+      durationPoll = null;
+    }
+    if (fallbackTimer) {
+      clearTimeout(fallbackTimer);
+      fallbackTimer = null;
+    }
   });
 
   // ========== PUBLIC PLAYBACK API ==========