flet-box 1.0.2 → 1.0.4

package/bin/ota/loader.js

@@ -331,7 +331,12 @@ async function checkAndUpdate(shippedConfig, activeHash) {
 (async function main() {
   let shippedConfig = null;
   try {
-    shippedConfig = await fetchJson("./config.json");
+    // Anchored to this script, not the document: on a static host with SPA
+    // fallback (GitHub Pages) the app can boot from a deep URL, where a
+    // document-relative "./config.json" would resolve to the wrong folder.
+    shippedConfig = await fetchJson(
+      new URL("./config.json", import.meta.url).href,
+    );
   } catch (e) {
     warn("no shipped config.json:", e.message);
   }

package/bin/utils/templates.js

@@ -607,9 +607,13 @@ echo "✅ Bundle listo: \$TARGET/   Prueba: cd \$TARGET && bash run.sh"
 
 export const serviceWorkerJs = () => `// service-worker.js - PWA offline support
 const CACHE_NAME = 'fletbox-v2';
+// Deployment prefix: a worker's own URL always sits at the app root, so this
+// is '/' at the host root and '/repo-name/' on a GitHub Pages project site.
+// Hard-coded '/' entries would miss every file under a subpath.
+const BASE = new URL('./', self.location).pathname;
 // The shipped (baked-in) shell, precached so the app opens with no connection.
 // loader.js owns a SEPARATE cache ('fletbox-ota') for downloaded bundles.
-const PRECACHE = ['/', '/index.html', '/loader.js', '/config.json', '/src/app.js'];
+const PRECACHE = [BASE, BASE + 'index.html', BASE + 'loader.js', BASE + 'config.json', BASE + 'src/app.js'];
 
 self.addEventListener('install', event => {
   event.waitUntil(
@@ -690,7 +694,7 @@ self.addEventListener('fetch', event => {
         const cached = await cache.match(req);
         if (cached) return cached;
         if (req.mode === 'navigate') {
-          const shell = await cache.match('/index.html');
+          const shell = await cache.match(BASE + 'index.html');
           if (shell) return shell;
         }
         return Response.error();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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,8 @@
     "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"
+    "test": "node scripts/check-widgets.mjs && node scripts/check-api-surface.mjs",
+    "test:browser": "node scripts/run-browser-tests.mjs"
   },
   "keywords": [
     "fletbox",

package/src/animations/AnimatedBox.js

@@ -334,6 +334,24 @@ const interpolateGradient = (gradient1, gradient2, t) => {
  * @param {string} keyframes - The keyframe body (everything inside `@keyframes name { … }`).
  * @returns {void}
  */
+/**
+ * Stable hash of a keyframe body, used as the generated animation name so that
+ * identical keyframes are injected only once.
+ *
+ * @param {string} keyframes
+ * @returns {string}
+ */
+const hashKeyframes = (keyframes) => {
+  let h1 = 0x811c9dc5;
+  let h2 = 0x01000193;
+  for (let i = 0; i < keyframes.length; i++) {
+    const c = keyframes.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193);
+    h2 = Math.imul(h2 + c, 0x85ebca6b) ^ (h2 >>> 13);
+  }
+  return (h1 >>> 0).toString(36) + (h2 >>> 0).toString(36);
+};
+
 const injectKeyframes = (name, keyframes) => {
   if (injectedKeyframes.has(name)) return;
   const style = document.createElement("style");
@@ -365,6 +383,15 @@ const generateKeyframes = (animations) => {
       const effect = effectMap[anim.effect] || anim.effect;
       const { from, to, reverse = true } = 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.
+      if (from === undefined || to === undefined) {
+        console.warn(
+          `⚠️ [AnimatedBox] Skipping animation "${anim.effect}": "from" and "to" are required.`,
+        );
+        return;
+      }
+
       let value;
       let color;
 
@@ -589,8 +616,12 @@ export const AnimatedBox = ({
       child.style.background = firstAnim.from;
     }
 
-    const name = `anim-${Date.now()}-${animationCounter++}`;
     const keyframes = generateKeyframes(animations);
+    // The name is derived from the keyframe body so identical animations reuse a
+    // single <style>. A per-call unique name (`Date.now()`) made the dedupe check
+    // in `injectKeyframes` dead code: every call appended a permanent <style> to
+    // document.head, and AnimatedText calls this once per letter.
+    const name = `anim-${hashKeyframes(keyframes)}`;
     injectKeyframes(name, keyframes);
 
     const duration = animations[0]?.duration || 500;

package/src/animations/AnimatedText.js

@@ -39,9 +39,13 @@ export const AnimatedText = ({
   if (!child) return null;
   if (!animations || animations.length === 0) return child;
 
-  // Extract text content and props from the original Text widget
-  const originalText = child._props?.text || child.textContent || "";
-  const originalProps = { ...(child._props || {}) };
+  // Extract text content and props from the original Text widget. The factory
+  // stores props in `_originalProps`; `_props` is never assigned by anything, so
+  // reading it here silently dropped every style (font, size, colour) and the
+  // documented per-letter inheritance never happened.
+  const sourceProps = child._originalProps || child._props || {};
+  const originalText = sourceProps.text || child.textContent || "";
+  const originalProps = { ...sourceProps };
   // Ensure no background animation styles bleed into individual letter widgets
   delete originalProps.animations;
 

package/src/animations/MatrixRain.js

@@ -52,6 +52,11 @@ export const MatrixRain = (props = {}) => {
   let drops = [];
   let columns = 0;
   let resizeObserver = null;
+  let observedParent = null;
+  // The canvas is returned to the caller and appended afterwards, so it is NOT
+  // connected when the animation starts. `wasConnected` tracks that first mount
+  // so the loop can stop when the canvas is later removed from the document.
+  let wasConnected = false;
 
   /**
    * Determines the canvas dimensions based on positioning mode.
@@ -84,14 +89,17 @@ export const MatrixRain = (props = {}) => {
    */
   const resizeCanvas = () => {
     if (!canvas) return;
-    if (
-      position === "absolute" &&
-      !resizeObserver &&
-      typeof ResizeObserver !== "undefined" &&
-      canvas.parentElement
-    ) {
-      resizeObserver = new ResizeObserver(resizeCanvas);
-      resizeObserver.observe(canvas.parentElement);
+    // The canvas is returned to the caller and appended afterwards, so on the
+    // first call there is no parent yet. Create the observer once and (re)attach
+    // it whenever the canvas ends up living in a different parent.
+    if (position === "absolute" && typeof ResizeObserver !== "undefined") {
+      if (!resizeObserver) resizeObserver = new ResizeObserver(resizeCanvas);
+      const parent = canvas.parentElement;
+      if (parent && observedParent !== parent) {
+        if (observedParent) resizeObserver.unobserve(observedParent);
+        resizeObserver.observe(parent);
+        observedParent = parent;
+      }
     }
     const { width, height } = getCanvasSize();
     canvas.width = width;
@@ -154,6 +162,25 @@ export const MatrixRain = (props = {}) => {
   const draw = () => {
     if (!ctx || !canvas) return;
 
+    // The canvas is handed back to the caller and appended afterwards, so it is
+    // disconnected while the animation starts. Once it HAS been mounted, a
+    // disconnect means it was removed from the document — stop there.
+    //
+    // Nothing else covers that path: `runApp`'s teardownTree and Scaffold's
+    // observer call `_cleanup()`, but the lifecycle observer in
+    // `src/widget-factory/lifecycle.js` only fires `onUnmount`, and a raw canvas
+    // has no such hook. Without this guard the loop would keep re-arming at
+    // 60fps painting into a detached canvas, forever.
+    if (canvas.isConnected) {
+      if (!wasConnected) {
+        wasConnected = true;
+        resizeCanvas(); // size to the real parent and attach the observer
+      }
+    } else if (wasConnected) {
+      cleanup();
+      return;
+    }
+
     // Semi-transparent black overlay produces the trailing-fade effect
     ctx.fillStyle = `rgba(0, 0, 0, ${fadeAmount})`;
     ctx.fillRect(0, 0, canvas.width, canvas.height);
@@ -188,10 +215,8 @@ export const MatrixRain = (props = {}) => {
   };
 
   window.addEventListener("resize", handleResize);
-  if (position === "absolute" && typeof ResizeObserver !== "undefined") {
-    resizeObserver = new ResizeObserver(resizeCanvas);
-    if (canvas.parentElement) resizeObserver.observe(canvas.parentElement);
-  }
+  // NOTE: the parent ResizeObserver is attached from `resizeCanvas()` (see
+  // above), because the canvas has no parent until the caller appends it.
 
   /**
    * Stops the animation loop, removes event listeners, disconnects the

package/src/animations/ParallaxBox.js

@@ -341,12 +341,16 @@ export const ParallaxBox = (props = {}) => {
 
   const originalCleanup = container._cleanup;
   /**
-   * Removes all event listeners, cancels pending animation frames, clears
-   * timers, and calls any previously assigned `_cleanup` function.
+   * Removes all event listeners, cancels pending animation frames and clears
+   * timers. Idempotent, because it runs from BOTH teardown paths: the lifecycle
+   * observer fires `onUnmount`, while runApp/Scaffold call `_cleanup`.
    *
    * @returns {void}
    */
-  container._cleanup = () => {
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
     if (type === "scroll") {
       window.removeEventListener("scroll", handleScroll);
     } else {
@@ -360,6 +364,15 @@ export const ParallaxBox = (props = {}) => {
     if (initialTimer) clearTimeout(initialTimer);
     transitionTimers.forEach((timer) => clearTimeout(timer));
     transitionTimers.clear();
+  };
+
+  // The lifecycle observer fires `onUnmount` on a plain DOM disconnect but never
+  // calls `_cleanup`, so without this the window scroll listener and the timers
+  // survived every removal that was not a full app rebuild.
+  container.onUnmount(dispose);
+
+  container._cleanup = () => {
+    dispose();
     if (originalCleanup) originalCleanup();
   };
 

package/src/animations/animate.js

@@ -114,7 +114,13 @@ const getEasing = (type, t) => {
 const readAnimatedValue = (widget, property) => {
   if (property === "scale") return 1;
   if (widget?.style && property in widget.style) {
-    return widget.style[property];
+    const inline = widget.style[property];
+    // An inline-unset property reads as "" and `interpolate` turns that into the
+    // string "NaN", which the browser silently drops — so `animate(el, "opacity",
+    // undefined, 1, 300)` (the documented API) wrote "NaN" every frame and never
+    // animated anything. Fall back to the property's neutral value.
+    if (inline !== "" && inline !== null && inline !== undefined) return inline;
+    return property === "opacity" ? 1 : 0;
   }
   return widget?.[property];
 };
@@ -180,13 +186,21 @@ export const animate = (
   duration = 300,
   easing = "linear",
 ) => {
+  // A negative duration makes elapsed/duration increasingly negative, so the
+  // loop re-armed forever and the property was driven backwards. Clamping the
+  // progress is not enough (it just sits at 0 and `0 < 1` stays true), so
+  // sanitise the duration itself. `0` collapses to a single frame.
+  duration = Math.max(0, Number(duration) || 0);
   const startTime = performance.now();
   const startValue = from !== undefined ? from : readAnimatedValue(widget, property);
   const endValue = to;
 
   const step = (currentTime) => {
     const elapsed = currentTime - startTime;
-    const progress = Math.min(1, elapsed / duration);
+    // Clamp both ends. A negative `duration` makes elapsed/duration increasingly
+    // negative, so `progress` never reached 1 and the loop re-armed forever (and
+    // `animateAsync` never resolved). `duration: 0` yields Infinity, clamped to 1.
+    const progress = Math.max(0, Math.min(1, elapsed / duration));
     const easedProgress = getEasing(easing, progress);
     const currentValue = interpolate(startValue, endValue, easedProgress);
 
@@ -224,6 +238,9 @@ export const animateAsync = (
   duration = 300,
   easing = "linear",
 ) => {
+  // See `animate`: a negative duration would keep the loop alive forever and this
+  // promise would never resolve.
+  duration = Math.max(0, Number(duration) || 0);
   return new Promise((resolve) => {
     const startTime = performance.now();
     const startValue = from !== undefined ? from : readAnimatedValue(widget, property);
@@ -231,7 +248,9 @@ export const animateAsync = (
 
     const step = (currentTime) => {
       const elapsed = currentTime - startTime;
-      const progress = Math.min(1, elapsed / duration);
+      // Same clamp as `animate`: a negative `duration` would otherwise never
+      // reach progress 1 and this promise would never resolve.
+      const progress = Math.max(0, Math.min(1, elapsed / duration));
       const easedProgress = getEasing(easing, progress);
       const currentValue = interpolate(startValue, endValue, easedProgress);
 

package/src/core/runApp.js

@@ -9,6 +9,7 @@ import {
 } from "../utils/themes.js";
 import { Container } from "../widgets/Container.js";
 import { setGlobalRender } from "../tools/useState.js";
+import { beginRenderPass, endRenderPass } from "../widget-factory/reactiveValue.js";
 
 /**
  * Mounts a FletBox application into the DOM and manages its full lifecycle.
@@ -182,7 +183,18 @@ export const runApp = (
       currentMainContainer = null;
     }
 
-    const appContent = typeof App === "function" ? App() : App;
+    // Wrap the component call in a render pass. A reactive value the component
+    // reads *here* — a template literal, a conditional, a list — is a structural
+    // read, so its key is flagged for an app render. Reads the factory performs
+    // while filling props are not flagged, which is what keeps a directly-passed
+    // state value surgical.
+    beginRenderPass();
+    let appContent;
+    try {
+      appContent = typeof App === "function" ? App() : App;
+    } finally {
+      endRenderPass();
+    }
 
     const mainContainer = Container({
       margin: 0,

package/src/create-index.sh

@@ -60,7 +60,7 @@ export {
     Scaffold, AppBar, Drawer, BottomNavigation, Tabs, DrawerItem,
     openDrawer, closeDrawer, toggleDrawer, destroyDrawer,
     initRouter, goTo, goBack, goForward, replace,
-    getCurrentPath, getCurrentRoute, getCurrentRouteConfig,
+    getCurrentPath, getBasePath, getCurrentRoute, getCurrentRouteConfig,
     getRoute, isActive, subscribe, useParams, useQueryParams,
     buildUrl, clearRouter
 } from './src/navigations/index.js';
@@ -178,7 +178,7 @@ export { Drawer, openDrawer, closeDrawer, toggleDrawer, destroyDrawer } from './
 export { BottomNavigation } from './BottomNavigation.js';
 export { Tabs } from './Tabs.js';
 export { DrawerItem } from './DrawerItem.js';
-export { initRouter, goTo, goBack, goForward, replace, getCurrentPath, getCurrentRoute, getCurrentRouteConfig, getRoute, isActive, subscribe, useParams, useQueryParams, buildUrl, clearRouter } from './Router.js';
+export { initRouter, goTo, goBack, goForward, replace, getCurrentPath, getBasePath, getCurrentRoute, getCurrentRouteConfig, getRoute, isActive, subscribe, useParams, useQueryParams, buildUrl, clearRouter } from './Router.js';
 EOF
 echo "✅ Created: src/navigations/index.js"