flet-box 1.0.6 → 1.0.8

package/bin/commands/pruneAssets.js

@@ -0,0 +1,170 @@
+/**
+ * @file bin/commands/pruneAssets.js
+ * @description `flet-box prune-assets` — deletes the images a generated app never
+ * names.
+ *
+ * This exists because of what `flet-box create` ships: a demo asset library
+ * (dishes, drinks, gallery photos) that no screen of a fresh app imports, which
+ * weighs the repository down and — worse — gets copied into any release whose
+ * asset glob is broad enough to catch it. The failure is silent: the site works,
+ * the bundle is 1.5 GB, and the visitor on a bad connection never sees the
+ * difference because those files were never requested.
+ *
+ * A file is kept when its path or its exact filename appears in the app's own
+ * sources. `www/` is deliberately not a source: it is generated output, so a name
+ * that only appears there is a stale bundle, not a consumer.
+ *
+ * Deletion is the one thing this command will not do unasked: it reports, and
+ * `--apply` deletes. Everything it removes is a tracked file in a generated
+ * project, so `git checkout -- assets/` puts it back.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { c, section, dot } from "../utils/colors.js";
+import { readAppSources, references, protectedMaster } from "../utils/appSources.js";
+
+const USAGE = `Usage: flet-box prune-assets [dir] [options]
+
+  dir                 Asset folder to clean (default: ./assets)
+
+Options:
+  --apply             Actually delete. Without it this is a report only.
+  --root <dir>        Project root the sources are read from (default: .)
+  --keep <name>       Extra filename to protect, repeatable
+  --quiet             Only the summary line
+  --help              This page`;
+
+const IMAGE_FILE = /\.(png|jpe?g|webp|gif|svg|ico|avif)$/i;
+const SKIPPED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".cache", "www", "vendor", "ios", "android"]);
+
+const size = (bytes) =>
+  bytes >= 1024 * 1024
+    ? `${(bytes / 1024 / 1024).toFixed(1)} MB`
+    : bytes >= 1024
+      ? `${Math.round(bytes / 1024)} KB`
+      : `${bytes} B`;
+
+/**
+ * @param {string} dir
+ * @returns {string[]} Image files under it, absolute, sorted.
+ */
+const collectImages = (dir) => {
+  const found = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIPPED_DIRS.has(entry.name)) walk(full);
+        continue;
+      }
+      if (entry.isFile() && IMAGE_FILE.test(entry.name)) found.push(full);
+    }
+  };
+  if (fs.existsSync(dir)) walk(dir);
+  return found.sort();
+};
+
+/**
+ * Runs the report, and the deletion if asked.
+ *
+ * @param {string[]} args - CLI arguments after the command name.
+ * @returns {Promise<{exitCode: number}>}
+ */
+export const pruneAssets = async (args = []) => {
+  const has = (flag) => args.includes(flag);
+  const valueOf = (flag) => {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+
+  if (has("--help") || has("-h")) {
+    console.log(USAGE);
+    return { exitCode: 0 };
+  }
+
+  const apply = has("--apply");
+  const quiet = has("--quiet");
+  const root = path.resolve(valueOf("--root") || ".");
+  const handKeep = new Set(args.filter((_, i) => args[i - 1] === "--keep"));
+
+  // Resolved against --root, not against the shell's cwd: a caller that names a
+  // project root means that project's assets, and the two arguments disagreeing
+  // is how a cleanup run ends up pointing at someone else's folder.
+  const positional = args.filter((a, i) => !a.startsWith("--") && !["--root", "--keep"].includes(args[i - 1]));
+  const dir = path.resolve(root, positional[0] || "assets");
+  if (!dir.startsWith(root)) {
+    console.log(c("red", `Refusing: ${dir} is outside the project root ${root}.`));
+    return { exitCode: 1 };
+  }
+  if (!fs.existsSync(dir)) {
+    console.log(c("red", `No such folder: ${path.relative(root, dir) || dir}`));
+    return { exitCode: 1 };
+  }
+
+  const text = readAppSources(root);
+  const images = collectImages(dir);
+  const dead = [];
+  const alive = [];
+  const protectedByHand = [];
+  for (const file of images) {
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    const master = protectedMaster(rel);
+    if (master) {
+      alive.push(file);
+      protectedByHand.push({ rel, why: master.why });
+      continue;
+    }
+    if (handKeep.has(rel) || handKeep.has(path.basename(file))) {
+      alive.push(file);
+      protectedByHand.push({ rel, why: "kept by hand" });
+      continue;
+    }
+    (references(text, rel) ? alive : dead).push(file);
+  }
+
+  // Measured before anything is deleted: the report that runs after `--apply`
+  // would otherwise stat files that no longer exist and crash on its own summary.
+  const sizes = new Map(images.map((f) => [f, fs.statSync(f).size]));
+  const bytesOf = (list) => list.reduce((s, f) => s + sizes.get(f), 0);
+
+  if (!quiet) {
+    console.log(section("🧹", `prune-assets — ${path.relative(root, dir) || "."}`));
+    if (!dead.length) console.log(`  ${dot("#34d399")} every one of the ${images.length} images here is referenced.`);
+    for (const file of dead.slice(0, 40)) {
+      console.log(`  ${dot("#ef4444")} ${path.relative(root, file)} — ${c("dim", size(sizes.get(file)))}`);
+    }
+    if (dead.length > 40) console.log(c("gray", `  … ${dead.length - 40} more`));
+    for (const { rel, why } of protectedByHand) {
+      console.log(`  ${dot("#34d399")} ${rel} — kept: ${why}`);
+    }
+  }
+
+  const summary = `${images.length} images · ${alive.length} referenced (${size(bytesOf(alive))}) · ${dead.length} unreferenced (${size(bytesOf(dead))})`;
+  if (!dead.length) {
+    console.log(`\n  ${summary}\n`);
+    return { exitCode: 0 };
+  }
+  if (!apply) {
+    console.log(`\n  ${summary}`);
+    console.log(c("yellow", "  dry run — nothing deleted. Add --apply to remove them.\n"));
+    return { exitCode: 0 };
+  }
+
+  const emptied = new Set();
+  for (const file of dead) {
+    fs.rmSync(file, { force: true });
+    emptied.add(path.dirname(file));
+  }
+  // A directory the purge emptied is dead weight in the repo and in every future
+  // glob, so it goes with its files.
+  for (const d of [...emptied].sort().reverse()) {
+    if (d !== dir && fs.existsSync(d) && fs.readdirSync(d).length === 0) fs.rmSync(d, { recursive: true, force: true });
+  }
+  console.log(`\n  ${summary}`);
+  console.log(c("green", `  deleted ${dead.length} files (${size(bytesOf(dead))}).`));
+  console.log(c("gray", "  Undo while the delete is uncommitted:  git checkout -- assets/\n"));
+  return { exitCode: 0 };
+};
+
+export default pruneAssets;

package/bin/commands/release.js

@@ -27,6 +27,7 @@ import fs from "fs";
 import path from "path";
 import { c, banner, gradient } from "../utils/colors.js";
 import { createBundle } from "./createBundle.js";
+import { resolveUpdateUrl } from "../utils/bundleConfig.js";
 import { INITIAL_VERSION, incrementVersion, isValidVersion } from "../utils/version.js";
 
 /**
@@ -183,7 +184,39 @@ export const release = async (argv = []) => {
       c("gray", `      ⬆️  Publish it: ${gradient(`git push && git push origin ${tag}`, "#22d3ee", "#38bdf8")}`),
     );
   }
+
+  // The live URL is the first thing people look for after a release, and the
+  // Actions run page hides it (it appears under the environment chip, never in
+  // the log) — so print the exact address this bundle was built for, plus the
+  // two steps that decide whether it is serving yet.
+  const siteUrl = resolveUpdateUrl(projectRoot);
+  console.log(
+    c("gray", "      🌐 Web:    ") +
+      (siteUrl
+        ? gradient(siteUrl, "#22d3ee", "#38bdf8")
+        : c("yellow", "unknown — no origin remote set yet")),
+  );
   console.log(
-    c("dim", "      ℹ️  CI deploys www/ to GitHub Pages on the tag; open apps self-update from config.json."),
+    c(
+      "dim",
+        `      Deploys: every push to main publishes www/ to GitHub Pages, so the\n` +
+        `               site is already live. Only the OTA feed is gated: the build\n` +
+        `               keeps www/config.json when its commit carries a v* tag, and\n` +
+        `               drops it otherwise, so an ordinary push never offers itself\n` +
+        `               to installed apps.\n` +
+        `      Release: a tag push cannot deploy — the github-pages environment\n` +
+        `               refuses runs that do not start from the default branch. So\n` +
+        `               after ${tag} exists, run the workflow once more by hand\n` +
+        `               (Actions → Deploy → Run workflow) to publish the feed.\n` +
+        `      Where:   Actions → the run → Deploy to Pages → the link under the\n` +
+        `               "github-pages" environment box. Not in the log.\n` +
+        `      Setup:   Settings → Pages → Source = "GitHub Actions", or even a\n` +
+        `               green build leaves the old site standing.`,
+    ),
   );
+  if (push) {
+    console.log(
+      c("gray", `      ⏳ CI is publishing ${tag} now — open the run to follow it.`),
+    );
+  }
 };

package/bin/commands/runCloudflare.js

@@ -1,21 +1,34 @@
 // bin/commands/runCloudflare.js
 import { spawn, spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
 import { c, banner, divider } from "../utils/colors.js";
 import { spinner } from "../utils/spinner.js";
+import { createBundle } from "./createBundle.js";
 import { runDevServer } from "./runServer.js";
 
 const TUNNEL_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 
 /**
- * Starts the local dev server and exposes it through a free Cloudflare quick
+ * Builds the production bundle and exposes it through a free Cloudflare quick
  * tunnel (no account required), printing the public HTTPS link to the console.
  *
- * @param {{ port?: number, logRequests?: boolean }} [options]
+ * The bundle is the thing on the tunnel, never the source tree: `index.html`
+ * maps the bare `flet-box` specifier to `./node_modules/...`, so serving `src/`
+ * publicly only works once `npm install` has run on that machine, and a fresh
+ * clone, a phone on 4G or a deep link showed a module-resolution error instead
+ * of the app. `createBundle` inlines the framework, so what the visitor gets is
+ * exactly what would be deployed.
+ *
+ * @param {{ target?: string, port?: number, logRequests?: boolean }} [options]
  * @returns {Promise<void>}
  */
-export const runCloudflareDemo = async (options = {}) => {
-  const { port = 8000, logRequests = false } = options;
-
+export const runCloudflareDemo = async ({
+  target = "www",
+  port = 8000,
+  logRequests = false,
+} = {}) => {
+  // Check the tunnel binary before spending a build on a command that cannot run.
   const probe = spawnSync("cloudflared", ["--version"], { encoding: "utf-8" });
   if (probe.error) {
     console.error(c("red", "❌ cloudflared is not installed"));
@@ -27,11 +40,36 @@ export const runCloudflareDemo = async (options = {}) => {
     process.exit(1);
   }
 
-  console.log(banner("☁️  FletBox Cloudflare Demo", "public HTTPS tunnel"));
+  console.log(banner("☁️  FletBox Cloudflare Demo", `bundle ${target}/ → public HTTPS tunnel`));
+
+  await createBundle(target);
+
+  // The bundle's `update.url` points at the production OTA source (the GitHub
+  // Pages site). A tunnel is not that origin, so every visitor's first action was
+  // a cross-origin fetch that the browser logged as a CORS error. Same-origin is
+  // both quieter and honest: the demo checks itself and reports "up to date".
+  try {
+    const configPath = path.join(process.cwd(), target, "config.json");
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    if (cfg?.update) {
+      cfg.update.url = "/";
+      fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2) + "\n");
+    }
+  } catch (e) {
+    console.warn(c("yellow", `⚠️  Could not retarget the OTA url: ${e.message}`));
+  }
+
+  console.log(
+    `\n  ${c("gray", `Bundle built · serving ${target}/ (SPA, hot reload OFF)`)}\n`,
+  );
+
+  // Serve from inside the bundle so every relative path the visitor requests
+  // resolves against the build output.
+  process.chdir(target);
 
   await runDevServer({
-    spaMode: false,
-    hotReload: true,
+    spaMode: true,
+    hotReload: false,
     port,
     askPort: false,
     logRequests,
@@ -53,7 +91,7 @@ export const runCloudflareDemo = async (options = {}) => {
     console.log(c("brightCyan", "  🌐 Public link (open this):"));
     console.log(`  ${c("bold", c("brightGreen", url))}`);
     console.log("");
-    console.log(c("gray", `  Local:  http://localhost:${port}`));
+    console.log(c("gray", `  Local:  http://localhost:${port} · ${target}/`));
     console.log(
       c("gray", "  The tunnel stays alive while this process runs. Ctrl+C to stop."),
     );

package/bin/commands/runServer.js

@@ -3,7 +3,7 @@ import http from "http";
 import fs from "fs";
 import path from "path";
 import readline from "readline";
-import { WebSocketServer } from "ws";
+import { WebSocketServer, WebSocket } from "ws";
 import chokidar from "chokidar";
 import { c, banner, rainbow, dot, typewriter } from "../utils/colors.js";
 import { spinner } from "../utils/spinner.js";
@@ -59,7 +59,12 @@ export const runDevServer = async (options = {}) => {
   let watcher = null;
   let PORT = Number(port) || 8000;
 
-  console.log(banner("📡 FletBox Server", spaMode ? "SPA + Hot Reload" : "Static"));
+  console.log(
+    banner(
+      "📡 FletBox Server",
+      `${spaMode ? "SPA" : "Static"}${hotReload ? " + Hot Reload" : ""}`,
+    ),
+  );
 
   // Interactive port: if no --port was passed and there is a TTY, ask
   if (options.askPort && process.stdin.isTTY) {
@@ -80,6 +85,8 @@ export const runDevServer = async (options = {}) => {
     ".json": "application/json",
     ".png": "image/png",
     ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
     ".gif": "image/gif",
     ".svg": "image/svg+xml",
     ".ico": "image/x-icon",
@@ -89,8 +96,11 @@ export const runDevServer = async (options = {}) => {
 
   const broadcast = (message) => {
     const msg = typeof message === "string" ? message : JSON.stringify(message);
+    // `readyState` is a `WebSocket` constant, not a `WebSocketServer` one:
+    // comparing against `WebSocketServer.OPEN` (undefined) matched no client and
+    // silently disabled hot reload for everybody.
     clients.forEach((client) => {
-      if (client.readyState === WebSocketServer.OPEN) {
+      if (client.readyState === WebSocket.OPEN) {
         client.send(msg);
       }
     });
@@ -144,7 +154,11 @@ export const runDevServer = async (options = {}) => {
         url = req.url;
       }
 
-      const safePath = path.normalize(url).replace(/^(\.\.[\/\\])+/, "");
+      // The query is part of the request, not of the file name: `?theme=dark`
+      // and the CSS hot-swap's `?t=` cache-buster were being resolved on disk
+      // and answered with a 404.
+      const pathname = url.split("?")[0].split("#")[0];
+      const safePath = path.normalize(pathname).replace(/^(\.\.[\/\\])+/, "");
       let filePath = path.join(
         projectRoot,
         safePath === "/" ? "index.html" : safePath,
@@ -153,9 +167,11 @@ export const runDevServer = async (options = {}) => {
 
       fs.access(filePath, fs.constants.F_OK, (err) => {
         // SPA fallback: if the file doesn't exist and has no extension, serve index.html
+        let isFallback = false;
         if (err && spaMode && (!ext || ext === "")) {
           filePath = path.join(projectRoot, "index.html");
           ext = ".html";
+          isFallback = true;
         }
 
         fs.readFile(filePath, (err2, content) => {
@@ -170,6 +186,23 @@ export const runDevServer = async (options = {}) => {
 
           const contentType = mimeTypes[ext] || "text/plain";
 
+          // A rewritten deep link is served from `index.html`, but the browser
+          // still resolves `./loader.js` against `/demo/forms/`, so the page came
+          // up blank on every shared link. Anchoring the page at the served root
+          // keeps the app's relative URLs working whatever the route is.
+          //
+          // The root document needs the same anchor: a client router pushes
+          // `/widget/Button` without a reload, and from then on the browser
+          // re-resolves a relative `<link rel="icon">` against that path. The
+          // favicon then 404s on every in-app navigation.
+          if (spaMode && ext === ".html" && (isFallback || safePath === "/")) {
+            let html = content.toString("utf-8");
+            if (!/<base [^>]*href=/i.test(html)) {
+              html = html.replace(/<head(\s[^>]*)?>/i, (m) => `${m}\n<base href="/">`);
+            }
+            content = html;
+          }
+
           if (logRequests) {
             const sizeKB = (content.length / 1024).toFixed(1);
             console.log(
@@ -195,29 +228,40 @@ export const runDevServer = async (options = {}) => {
                   c("blue", "🔧 Framework mode: using direct HMR import"),
                 );
             } else {
-              // ✅ Normal project: import from the npm module
+              // A static import, not `import('flet-box').then(...)`: the client
+              // restores the state snapshot and that must run before the app's
+              // own `useState` call. A `.then()` is a microtask later, so the
+              // app would already have booted with defaults.
               hmrScript = `
                                 <script type="module">
-                                    import('flet-box').then(({ initHMR }) => {
-                                        if (typeof initHMR === 'function') {
-                                            initHMR();
-                                        }
-                                    }).catch(e => console.warn('HMR not available:', e));
+                                    import { initHMR } from 'flet-box';
+                                    initHMR();
                                 </script>
                             `;
             }
 
             if (!html.includes("initHMR")) {
-              if (html.includes("</body>")) {
+              // Inserted before the app's module tag, so module execution order
+              // puts the restore first; `</head>` and `</body>` are the fallbacks
+              // for a page that has no module script yet.
+              const anchor = /<script[^>]*type=["']module["'][^>]*>/i.exec(html);
+              if (anchor)
+                html = html.slice(0, anchor.index) + hmrScript + html.slice(anchor.index);
+              else if (html.includes("</head>"))
+                html = html.replace("</head>", `${hmrScript}</head>`);
+              else if (html.includes("</body>"))
                 html = html.replace("</body>", `${hmrScript}</body>`);
-              } else {
-                html += hmrScript;
-              }
+              else html += hmrScript;
               content = html;
             }
           }
 
-          res.writeHead(200, { "Content-Type": contentType });
+          // A dev server that lets the browser cache a module is a hot reload
+          // that "does nothing": the page reloads and re-gets the old code.
+          res.writeHead(200, {
+            "Content-Type": contentType,
+            "Cache-Control": "no-store, no-cache, must-revalidate",
+          });
           res.end(content);
         });
       });
@@ -296,11 +340,21 @@ export const runDevServer = async (options = {}) => {
   // WebSocket para HMR
   if (hotReload) {
     const wss = new WebSocketServer({ server });
-    wss.on("error", onServerError);
+
+    // A browser tab that vanishes mid-flight (a tunnel closing an idle socket is
+    // enough) makes `ws` emit "error". With no listener that is an uncaught
+    // exception and the dev server dies with the tab — the usual reason hot
+    // reload "crashes" during a live demo.
+    wss.on("error", (err) => {
+      console.warn(c("yellow", `⚠️  HMR socket error: ${err && err.message}`));
+    });
 
     wss.on("connection", (ws) => {
       clients.add(ws);
-      console.log(c("green", "🔌 HMR client connected"));
+      if (logRequests) console.log(c("green", "🔌 HMR client connected"));
+      ws.on("error", () => {
+        // The peer is already gone; `close` follows and drops it from the set.
+      });
       ws.send(JSON.stringify({ type: "request-modules" }));
       ws.on("message", (data) => {
         try {
@@ -317,16 +371,16 @@ export const runDevServer = async (options = {}) => {
       });
       ws.on("close", () => {
         clients.delete(ws);
-        console.log(c("gray", "🔌 HMR client disconnected"));
+        if (logRequests) console.log(c("gray", "🔌 HMR client disconnected"));
       });
     });
 
-    const watchPaths = [
-      "src/**/*.js",
-      "src/**/*.mjs",
-      "src/**/*.css",
-      "index.html",
-    ];
+    // chokidar 4 removed glob support: `src/**/*.js` is watched as a literal
+    // path that never exists, so the watcher silently reported "Watching…" and
+    // never fired once. Watch the real roots and filter by extension instead.
+    const watchPaths = ["src", "index.html"];
+    const isWatched = (filePath) =>
+      /\.(js|mjs|css)$/.test(filePath) || filePath === "index.html";
     const moduleVersions = new Map();
 
     watcher = chokidar.watch(watchPaths, {
@@ -334,22 +388,32 @@ export const runDevServer = async (options = {}) => {
       persistent: true,
       cwd: projectRoot,
       ignoreInitial: true,
+      // An editor saves in two or three writes (write, rename, chmod). Firing on
+      // each one reloads the page several times per Ctrl+S.
+      awaitWriteFinish: { stabilityThreshold: 150, pollInterval: 25 },
     });
 
+    const lastSent = new Map();
+
     watcher.on("change", async (filePath) => {
+      if (!isWatched(filePath)) return;
       const fullPath = path.join(projectRoot, filePath);
       try {
         const newContent = fs.readFileSync(fullPath, "utf-8");
         const oldContent = moduleVersions.get(filePath);
         const changeType = getChangeType(filePath, oldContent, newContent);
         moduleVersions.set(filePath, newContent);
+        const key = `${filePath}:${changeType}`;
+        const now = Date.now();
+        if (now - (lastSent.get(key) || 0) < 700) return;
+        lastSent.set(key, now);
         console.log(c("yellow", `📝 Changed: ${filePath} (${changeType})`));
         broadcast(
           JSON.stringify({
             type: "hmr",
             file: filePath,
             changeType,
-            timestamp: Date.now(),
+            timestamp: now,
           }),
         );
       } catch (err) {
@@ -358,11 +422,13 @@ export const runDevServer = async (options = {}) => {
     });
 
     watcher.on("add", (filePath) => {
+      if (!isWatched(filePath)) return;
       console.log(c("green", `➕ Added: ${filePath}`));
       broadcast(JSON.stringify({ type: "reload", reason: "file-added" }));
     });
 
     watcher.on("unlink", (filePath) => {
+      if (!isWatched(filePath)) return;
       console.log(c("red", `➖ Removed: ${filePath}`));
       broadcast(JSON.stringify({ type: "reload", reason: "file-removed" }));
     });