flet-box 1.0.7 → 1.0.9

package/bin/commands/create.js

@@ -108,6 +108,21 @@ const askRepo = () =>
     );
   });
 
+/**
+ * The GitHub Pages address a repo value implies, or null when the value is not
+ * a GitHub repo. Kept apart from `resolveOtaUrl` because the workflow header
+ * names the *Pages* site: a custom-domain OTA URL is not an address this file
+ * can publish to, so it must not be printed as one.
+ *
+ * @param {string|null} input - "user/repo" or a github.com URL.
+ * @returns {string|null} Base URL ending in "/", or null.
+ */
+const pagesSiteUrl = (input) => {
+  if (!input) return null;
+  const gh = parseGithubRepo(input.trim());
+  return gh ? `https://${gh.user}.github.io/${gh.repo}/` : null;
+};
+
 /**
  * Normalizes the user's OTA target into a base URL ending in "/".
  * - "user/repo" (or any GitHub URL shape) → GitHub Pages URL.
@@ -123,8 +138,7 @@ const resolveOtaUrl = (input) => {
   if (/^https?:\/\//i.test(value)) {
     return value.endsWith("/") ? value : `${value}/`;
   }
-  const gh = parseGithubRepo(value);
-  return gh ? `https://${gh.user}.github.io/${gh.repo}/` : null;
+  return pagesSiteUrl(value);
 };
 
 /**
@@ -167,6 +181,10 @@ export const createProject = async (projectName, rawArgs = []) => {
     repoInput = await askRepo();
   }
   const otaUrl = resolveOtaUrl(repoInput);
+  // The Pages address the workflow file prints as its own header. Derived from
+  // the repo alone: `flet-box create myapp --repo me/my-website` says so in
+  // build.yml, and a missing or unparsable repo leaves the placeholder to edit.
+  const siteUrl = pagesSiteUrl(repoInput);
   if (repoInput && !otaUrl) {
     console.warn(
       c(
@@ -198,6 +216,8 @@ export const createProject = async (projectName, rawArgs = []) => {
     ".fletbox/api",
     ".fletbox/memory/notes",
     ".claude",
+    ".claude/skills/fletbox-clean-ui",
+    ".qoder/skills/fletbox-clean-ui",
     ".cursor/rules",
   ];
   const extraDirs =
@@ -228,7 +248,7 @@ export const createProject = async (projectName, rawArgs = []) => {
   createFile(path.join(projectPath, ".gitignore"), templates.gitignore());
   createFile(
     path.join(projectPath, ".github/workflows/build.yml"),
-    templates.githubWorkflow(finalName),
+    templates.githubWorkflow(finalName, siteUrl),
   );
   createFile(
     path.join(projectPath, ".github/workflows/build-native.yml"),
@@ -416,6 +436,29 @@ export const createProject = async (projectName, rawArgs = []) => {
     path.join(projectPath, ".cursor/rules/fletbox.mdc"),
     templates.cursorRules(),
   );
+
+  // The clean-UI skill. Claude Code loads `.claude/skills/<name>/SKILL.md` by
+  // description, so the agent picks it up whenever it touches a screen without
+  // being told. `.qoder/skills/` holds a byte-identical copy because Qoder reads
+  // the same shape from a different root — one text, two loaders, never two edits.
+  const cleanUiSkill = templates.cleanUiSkill();
+  createFile(
+    path.join(projectPath, ".claude/skills/fletbox-clean-ui/SKILL.md"),
+    cleanUiSkill,
+  );
+  createFile(
+    path.join(projectPath, ".qoder/skills/fletbox-clean-ui/SKILL.md"),
+    cleanUiSkill,
+  );
+  createFile(
+    path.join(projectPath, ".cursor/rules/fletbox-clean-ui.mdc"),
+    templates.cleanUiCursorRule(),
+  );
+  createFile(
+    path.join(projectPath, "scripts/check-ui.mjs"),
+    templates.checkUiScript(finalName),
+  );
+
   createFile(
     path.join(projectPath, ".fletbox/memory/MEMORY.md"),
     templates.memoryIndexMd(finalName),
@@ -494,8 +537,9 @@ export const createProject = async (projectName, rawArgs = []) => {
     c(
       "gray",
       "CI:      .github/workflows/build.yml publishes the web to GitHub Pages on every push.\n" +
-      "         Enable it once: Settings → Pages → Source: GitHub Actions. The job prints the URL.\n" +
-      "         Android and iOS are manual: .github/workflows/build-native.yml, Run workflow.\n",
+        `         It goes live at: ${siteUrl || `https://TU-USUARIO.github.io/${finalName}/`}\n` +
+        "         Enable it once: Settings → Pages → Source: GitHub Actions. The job prints the URL.\n" +
+        "         Android and iOS are manual: .github/workflows/build-native.yml, Run workflow.\n",
     ),
   );
   console.log(

package/bin/commands/createBundle.js

@@ -18,6 +18,7 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { c, banner, gradient, section } from "../utils/colors.js";
 import { buildBundleConfig, collectAssets, getGitRemoteUrl, resolveAssetPatterns, absoluteShareTags } from "../utils/bundleConfig.js";
+import { normaliseManifest, writeSpaFallback } from "../utils/pwaShell.js";
 import { INITIAL_VERSION, incrementVersion, isValidVersion } from "../utils/version.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -57,6 +58,7 @@ const copyFolderSync = (src, dest) => {
  * ```
  * <target>/
  *   index.html
+ *   404.html          ← copy of the shell, so a refresh on a deep link serves the app
  *   manifest.json
  *   service-worker.js
  *   run.sh
@@ -408,6 +410,25 @@ export const createBundle = async (targetArg) => {
     }
   }
 
+  // ---- Installable, deep-linkable output ----------------------------------
+  // Both corrections belong to the deployable folder, not to the project: the
+  // app's own manifest.json stays host-agnostic and this bundle is what a static
+  // host serves. See bin/utils/pwaShell.js for the two failure modes.
+  const manifestFixes = normaliseManifest(targetDir);
+  if (manifestFixes.length) {
+    console.log(c("green", `✅ manifest.json → ${manifestFixes.length} correction(s)`));
+    for (const fix of manifestFixes) console.log(c("gray", `      ${fix}`));
+  }
+
+  if (writeSpaFallback(targetDir)) {
+    console.log(
+      c(
+        "green",
+        "✅ 404.html → copy of the shell (hosts without SPA rewrites now serve the app on a refresh)",
+      ),
+    );
+  }
+
   // Preserve the app source tree so the in-app "View code" feature can read it.
   for (const dir of ["modules", "screens", "database", "components"]) {
     const src = path.join(srcDir, dir);

package/bin/commands/runServer.js

@@ -154,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,
@@ -186,7 +190,12 @@ export const runDevServer = async (options = {}) => {
           // 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.
-          if (isFallback && ext === ".html") {
+          //
+          // 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="/">`);

package/bin/utils/pwaShell.js

@@ -0,0 +1,137 @@
+/**
+ * @file bin/utils/pwaShell.js
+ * @description Two build-time corrections that make a bundle deployable as a PWA
+ * on a static host, which is where every generated app actually ends up
+ * (GitHub Pages, S3, any bucket under `/repo/`).
+ *
+ * Neither can be left to the app author to remember, because both fail silently
+ * on the developer's own machine and only show up once deployed:
+ *
+ *  1. `writeSpaFallback` — a single-page app has routes the host does not know.
+ *     GitHub Pages has no rewrite rule, so a refresh on `/repo/menu` is answered
+ *     with Pages' own "Page not found": the app looks broken exactly on the
+ *     entry point a shared link or a reload produces. `404.html` is the portable
+ *     remedy: every static host serves that file for a missing path, so copying
+ *     the built shell over it hands the deep link to the router instead.
+ *
+ *  2. `normaliseManifest` — a generated `manifest.json` says `"start_url": "/"`
+ *     and `"scope": "/"`. Resolved against the manifest's own URL that is the
+ *     host root, i.e. `https://user.github.io/`, which is outside the app's
+ *     directory and outside its service worker's scope. Chrome then refuses to
+ *     offer the install at all: the site renders, works offline, and never shows
+ *     "Add to Home Screen". Icons have the quieter version of the same bug — a
+ *     copied logo declared as `192x192` that is really 512 px wide.
+ *
+ * Both only touch the bundle output. The project's own `manifest.json` and
+ * `index.html` stay host-agnostic so the same folder still runs on `:8000`.
+ */
+
+import fs from "fs";
+import path from "path";
+
+/**
+ * Read the intrinsic size of a PNG from its IHDR chunk.
+ *
+ * @param {string} filePath - Absolute path to the candidate icon.
+ * @returns {{width: number, height: number}|null} Nothing for a non-PNG file.
+ */
+export const pngDimensions = (filePath) => {
+  const header = Buffer.alloc(24);
+  let handle;
+  try {
+    handle = fs.openSync(filePath, "r");
+    if (fs.readSync(handle, header, 0, 24, 0) !== 24) return null;
+  } catch {
+    return null;
+  } finally {
+    if (handle !== undefined) fs.closeSync(handle);
+  }
+
+  const isPng =
+    header[0] === 0x89 &&
+    header.subarray(12, 16).toString("ascii") === "IHDR";
+  if (!isPng) return null;
+  return { width: header.readUInt32BE(16), height: header.readUInt32BE(20) };
+};
+
+/**
+ * Make the bundled `manifest.json` launch and stay inside the app it ships with.
+ *
+ * `start_url` and `scope` are resolved against the manifest URL, so `"/"` means
+ * the host root. Rewriting only that value (and an empty string) to `"./"` keeps
+ * a root-hosted app identical to what it was while pulling a sub-path app back
+ * inside its own directory; any other value is a deliberate base path and is left
+ * alone. Each icon's declared `sizes` is corrected to the pixels the file really
+ * has, which is also what makes the 192 px requirement provable to the browser.
+ *
+ * @param {string} targetDir - Absolute path of the bundle directory.
+ * @returns {string[]} Human-readable description of each correction made.
+ */
+export const normaliseManifest = (targetDir) => {
+  const manifestPath = path.join(targetDir, "manifest.json");
+  if (!fs.existsSync(manifestPath)) return [];
+
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, "utf8");
+  } catch {
+    return [];
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+
+  const changes = [];
+
+  // "/" escapes the app on a sub-path host; "" is the same mistake written
+  // differently. Anything else was typed on purpose.
+  for (const field of ["start_url", "scope"]) {
+    if (manifest[field] === "/" || manifest[field] === "") {
+      manifest[field] = "./";
+      changes.push(`${field}: "/" → "./"`);
+    }
+  }
+
+  if (Array.isArray(manifest.icons)) {
+    for (const icon of manifest.icons) {
+      if (!icon || typeof icon.src !== "string") continue;
+      // Strip any query/hash and the leading "./" before hitting the disk; the
+      // bundle keeps icons relative to its own directory.
+      const clean = icon.src.split(/[?#]/)[0].replace(/^\.\//, "");
+      const size = pngDimensions(path.join(targetDir, clean));
+      if (!size) continue;
+      const actual = `${size.width}x${size.height}`;
+      if (icon.sizes !== actual) {
+        const declared = icon.sizes;
+        icon.sizes = actual;
+        changes.push(`${clean}: sizes now ${actual} (was ${declared})`);
+      }
+    }
+  }
+
+  if (changes.length) {
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  }
+  return changes;
+};
+
+/**
+ * Copy the finished shell to `404.html` so unknown paths serve the app.
+ *
+ * Called last, after the OTA loader is wired and the share tags are absolute, so
+ * the fallback document is byte-identical to `index.html` and boots the same
+ * bundle. Idempotent: rebuilding the project always rewrites it.
+ *
+ * @param {string} targetDir - Absolute path of the bundle directory.
+ * @returns {boolean} False when there is no `index.html` to copy.
+ */
+export const writeSpaFallback = (targetDir) => {
+  const index = path.join(targetDir, "index.html");
+  if (!fs.existsSync(index)) return false;
+  fs.copyFileSync(index, path.join(targetDir, "404.html"));
+  return true;
+};