flet-box 1.0.5 → 1.0.7

package/bin/ota/loader.js

@@ -24,6 +24,10 @@
  * SECURITY: the downloaded bundle is only run if its sha256 matches the hash in
  * the remote config.json. If Web Crypto is unavailable (non-secure context) OTA
  * is skipped rather than running unverified code.
+ *
+ * Extra release files (`config.json` → `assets`) are served to the app through
+ * `globalThis.__FLETBOX_OTA_ASSET__(path)`: cached copy, then the published one
+ * (verified against its manifest hash), then the copy baked into this build.
  */
 
 const SHIPPED_BUNDLE = "./src/app.js";
@@ -235,6 +239,9 @@ async function checkAndUpdate(shippedConfig, activeHash) {
     return false;
   }
   if (!remote || typeof remote.hash !== "string") return false;
+  // Even when this release turns out to be the one already running, its asset
+  // list is the newest truth about where the app's files live.
+  rememberAssets(remote, update.url);
   if (remote.hash === activeHash) {
     log("up to date (" + (remote.version || activeHash.slice(0, 8)) + ")");
     return false;
@@ -328,6 +335,88 @@ async function checkAndUpdate(shippedConfig, activeHash) {
   return true;
 }
 
+// ---- Release assets -----------------------------------------------------
+// config.json may name files a release serves beside the bundle (markdown docs,
+// JSON data, images). OTA replaces the bundle and nothing else, so an app
+// packaged two builds ago still has the old copy of those files on disk — the
+// symptom is an updated catalog pointing at pages the device does not have.
+// The app calls globalThis.__FLETBOX_OTA_ASSET__(path) and gets a Response, or
+// null when the file exists in neither place.
+const SHIPPED_BASE = new URL("./", import.meta.url).href;
+
+let assetSource = null; // base URL of the newest release the loader has seen
+let assetHashes = null; // Map "<path>" -> expected sha256
+
+const rememberAssets = (config, base) => {
+  if (!config || !Array.isArray(config.assets) || !config.assets.length) return;
+  assetSource = base;
+  assetHashes = new Map(
+    config.assets
+      .filter((a) => a && typeof a.path === "string" && typeof a.hash === "string")
+      .map((a) => [a.path, a.hash]),
+  );
+};
+
+const openAssetCache = async () =>
+  "caches" in globalThis ? await caches.open(OTA_CACHE) : null;
+
+globalThis.__FLETBOX_OTA_ASSET__ = async (relPath) => {
+  const clean = String(relPath || "").replace(/^\.?\//, "");
+  if (!clean) return null;
+  const shippedUrl = new URL(clean, SHIPPED_BASE).href;
+  const url = assetSource ? new URL(clean, assetSource).href : shippedUrl;
+
+  try {
+    const cache = await openAssetCache();
+    const hit = cache && (await cache.match(url));
+    if (hit) return hit;
+  } catch (e) {
+    log("asset cache unreadable:", e.message);
+  }
+
+  if (url !== shippedUrl) {
+    try {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+      const res = await fetch(url, { cache: "no-store", signal: ctrl.signal });
+      clearTimeout(timer);
+      if (res.ok) {
+        const text = await res.text();
+        const type = res.headers.get("Content-Type") || "application/octet-stream";
+        const expected = assetHashes && assetHashes.get(clean);
+        const digest = expected ? await sha256(text) : null;
+        if (digest && digest !== expected) {
+          warn("asset hash mismatch for " + clean + " — using this build's copy");
+        } else {
+          try {
+            const cache = await openAssetCache();
+            if (cache) {
+              await cache.put(
+                url,
+                new Response(text, { headers: { "Content-Type": type } }),
+              );
+            }
+          } catch (e) {
+            log("asset not cached:", e.message);
+          }
+          return new Response(text, { headers: { "Content-Type": type } });
+        }
+      }
+    } catch (e) {
+      log("asset fetch failed for " + clean + ":", e.message);
+    }
+  }
+
+  // Offline, unpublished, or it failed verification: ship what this build holds.
+  try {
+    const res = await fetch(shippedUrl);
+    return res.ok ? res : null;
+  } catch (e) {
+    log("asset missing from this build (" + clean + "):", e.message);
+    return null;
+  }
+};
+
 (async function main() {
   let shippedConfig = null;
   try {
@@ -340,6 +429,7 @@ async function checkAndUpdate(shippedConfig, activeHash) {
   } catch (e) {
     warn("no shipped config.json:", e.message);
   }
+  rememberAssets(shippedConfig, SHIPPED_BASE);
 
   const installed = readInstalled();
   const activeHash = installed

package/bin/utils/appSources.js

@@ -0,0 +1,101 @@
+/**
+ * @file bin/utils/appSources.js
+ * @description What a generated app's own sources actually name.
+ *
+ * Two CLI commands need this question and must not answer it two ways:
+ * `prune-assets` deletes the image files no source references, and `images
+ * --referenced` refuses to build a WebP the app never asks for (an assets folder
+ * routinely holds the declared `favicon.png` and a social-preview JPG, and
+ * converting them would add files nothing loads).
+ *
+ * `www/` is not a source: it is generated output, so a name that appears only
+ * there is a stale bundle, not a consumer.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const SOURCE_FILE = /\.(js|mjs|css|html|json|md)$/i;
+const SKIPPED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".cache", "www", "vendor", "ios", "android"]);
+
+/**
+ * Roots a reference may legitimately live in.
+ *
+ * `scripts/` counts because the native icon steps sit there, and a template that
+ * moves a filename into one of them must not have its master deleted.
+ */
+export const SOURCE_ROOTS = ["src", "index.html", "scripts", "fletbox.config.json", "package.json", "README.md", "AGENTS.md"];
+
+/**
+ * Reads the app's sources into one string, with comments taken out.
+ *
+ * A note like `mojito.jpg is the frappé` is documentation, not a load, and
+ * keeping a dead file alive because of it defeats the command.
+ *
+ * @param {string} root - Absolute project root.
+ * @returns {string}
+ */
+export const readAppSources = (root) => {
+  const parts = [];
+  const walk = (target) => {
+    if (!fs.existsSync(target)) return;
+    const stack = [target];
+    while (stack.length) {
+      const p = stack.pop();
+      const stat = fs.statSync(p);
+      if (stat.isDirectory()) {
+        for (const entry of fs.readdirSync(p)) {
+          if (SKIPPED_DIRS.has(entry)) continue;
+          stack.push(path.join(p, entry));
+        }
+        continue;
+      }
+      if (SOURCE_FILE.test(p)) {
+        try {
+          parts.push(fs.readFileSync(p, "utf8"));
+        } catch {
+          /* unreadable text is not evidence of anything */
+        }
+      }
+    }
+  };
+  for (const rel of SOURCE_ROOTS) walk(path.resolve(root, rel));
+  return parts
+    .join("\n")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .split("\n")
+    .filter((line) => !/^\s*(\/\/|#|\*)/.test(line))
+    .join("\n");
+};
+
+/**
+ * Files a cleanup or a conversion must not touch, whatever the sources say.
+ *
+ * `assets/logo.png` is the app icon: the native build scripts read it and resize
+ * it into launcher icons and splash screens, so it has to stay the lossless
+ * master the sensor produced. A text scan alone cannot be trusted to notice it —
+ * those scripts build the path with `path.join(root, "assets", "logo.png")`, so
+ * the string `assets/logo.png` never appears in them — and a lossy WebP at a
+ * 40 KB budget would silently become the icon on every phone.
+ *
+ * Matched by project-relative path or by exact filename.
+ */
+export const PROTECTED_MASTERS = [
+  { rel: "assets/logo.png", why: "the app icon master: native icons and splash screens are resized from it" },
+];
+
+/**
+ * @param {string} text - The corpus from `readAppSources`.
+ * @param {string} rel - Path relative to the project root, e.g. `assets/x.webp`.
+ * @returns {boolean} Whether the app names it — by path, or by exact filename.
+ */
+export const references = (text, rel) => text.includes(rel) || text.includes(path.basename(rel));
+
+/**
+ * @param {string} rel - Project-relative path with `/` separators.
+ * @returns {{rel: string, why: string}|null} The protection that covers it, if any.
+ */
+export const protectedMaster = (rel) =>
+  PROTECTED_MASTERS.find((entry) => entry.rel === rel || entry.rel.split("/").pop() === path.basename(rel)) || null;
+

package/bin/utils/bundleConfig.js

@@ -107,6 +107,40 @@ export const resolveUpdateUrl = (projectRoot) => {
   return null;
 };
 
+/**
+ * The `<meta>` tags a social scraper resolves against its own machine.
+ *
+ * Facebook, WhatsApp and X do not run the page and do not resolve `./assets/…`
+ * the way a browser does, so a relative `og:image` produces a share card with no
+ * picture — the silent kind of breakage, because the site itself looks perfect
+ * when somebody opens it.
+ */
+export const SHARE_TAGS = ["og:image", "og:url", "twitter:image", "twitter:url"];
+
+/**
+ * Rewrite the share-card tags in a built `index.html` to absolute URLs.
+ *
+ * Only the bundle copy is touched: the project's own `index.html` stays
+ * host-agnostic, which is what lets one folder run on `:8000`, through a tunnel
+ * and on Pages. Values that already carry a scheme are left alone, so building
+ * twice over the same output cannot produce `https://…/https://…`.
+ *
+ * @param {string} html - The built index.html.
+ * @param {string|null} base - Site origin ending in "/", or null to leave as is.
+ * @returns {string}
+ */
+export const absoluteShareTags = (html, base) => {
+  if (!base || !base.endsWith("/")) return html;
+  return html.replace(/<meta\b[^>]*>/gi, (tag) => {
+    const key = tag.match(/\b(?:property|name)\s*=\s*(["'])([^"']+)\1/i)?.[2];
+    if (!key || !SHARE_TAGS.includes(key)) return tag;
+    const found = tag.match(/\bcontent\s*=\s*(["'])([^"']*)\1/i);
+    if (!found || !found[2] || /^(https?:)?\/\//i.test(found[2])) return tag;
+    const absolute = base + found[2].replace(/^\.?\//, "");
+    return tag.slice(0, found.index) + `content="${absolute}"` + tag.slice(found.index + found[0].length);
+  });
+};
+
 /**
  * Returns the `origin` remote URL of the git repo at `projectRoot`, or null.
  *
@@ -127,6 +161,126 @@ export const getGitRemoteUrl = (projectRoot) => {
   }
 };
 
+/**
+ * Directories never worth walking when resolving release assets: they are either
+ * tooling output or would turn a small build into a filesystem scan.
+ */
+const PRUNED_DIRS = new Set(["node_modules", "dist", "www", "build", "coverage"]);
+
+/**
+ * Translates an asset glob into a regular expression over bundle-relative paths
+ * that always use forward slashes. Supports `**` (any depth, and zero dirs when
+ * written as `a/** /b`), `*` (one segment) and `?`.
+ *
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+const globToRegExp = (pattern) => {
+  let source = "";
+  for (let i = 0; i < pattern.length; i += 1) {
+    const char = pattern[i];
+    if (char === "*") {
+      if (pattern[i + 1] === "*") {
+        i += 1;
+        const trailingSlash = pattern[i + 1] === "/";
+        if (trailingSlash) i += 1;
+        source += trailingSlash ? "(?:.*/)?" : ".*";
+      } else {
+        source += "[^/]*";
+      }
+    } else if (char === "?") {
+      source += "[^/]";
+    } else {
+      source += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+  }
+  return new RegExp(`^${source}$`);
+};
+
+/**
+ * Lists every file under `dir` (relative to `projectRoot`) as a forward-slash
+ * path, skipping tooling folders and dot-directories.
+ *
+ * @param {string} projectRoot
+ * @param {string} dir - "" for the project root itself.
+ * @param {string[]} found - Accumulator, mutated.
+ * @returns {string[]}
+ */
+const listFiles = (projectRoot, dir, found) => {
+  let entries;
+  try {
+    entries = fs.readdirSync(path.join(projectRoot, dir), { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const entry of entries) {
+    const rel = dir ? `${dir}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (PRUNED_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+      listFiles(projectRoot, rel, found);
+    } else if (entry.isFile()) {
+      found.push(rel);
+    }
+  }
+  return found;
+};
+
+/**
+ * Reads the asset globs a project declares for its OTA releases
+ * (`update.assets` in `fletbox.config.json`).
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {string[]} Absolute-free glob list, empty when none is configured.
+ */
+export const resolveAssetPatterns = (projectRoot) => {
+  const fletboxConfig = readJsonSafe(
+    path.join(projectRoot, "fletbox.config.json"),
+    {},
+  );
+  const patterns = fletboxConfig?.update?.assets;
+  if (!Array.isArray(patterns)) return [];
+  return patterns
+    .filter((p) => typeof p === "string" && p.trim())
+    .map((p) => p.trim().replace(/^\.\//, "").replace(/^\/+/, ""));
+};
+
+/**
+ * Resolves asset globs into the manifest entries a release ships next to the
+ * bundle. Each file is hashed so a running app can verify what it downloads.
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @param {string[]} patterns - Globs relative to the project root.
+ * @returns {Array<{path: string, hash: string, size: number}>} Sorted by path.
+ */
+export const collectAssets = (projectRoot, patterns = []) => {
+  const globs = patterns.map((p) => globToRegExp(p));
+  if (!globs.length) return [];
+
+  // Start the walk at each pattern's literal first segment when there is one,
+  // so `docs/**` never reads the rest of the project.
+  const starts = new Set(
+    patterns.map((pattern) => {
+      const first = pattern.split("/")[0];
+      if (/[*?]/.test(first)) return "";
+      const absolute = path.join(projectRoot, first);
+      return fs.existsSync(absolute) && fs.statSync(absolute).isDirectory()
+        ? first
+        : "";
+    }),
+  );
+
+  const files = [];
+  for (const start of starts) listFiles(projectRoot, start, files);
+
+  return [...new Set(files)]
+    .filter((file) => globs.some((re) => re.test(file)))
+    .sort()
+    .map((file) => {
+      const content = fs.readFileSync(path.join(projectRoot, file));
+      return { path: file, hash: sha256(content), size: content.length };
+    });
+};
+
 /**
  * Builds the OTA config manifest object for a freshly written bundle.
  *
@@ -136,12 +290,16 @@ export const getGitRemoteUrl = (projectRoot) => {
  *   `app.js` (after the version header is stamped), used for the hash + size.
  * @param {string} [opts.bundlePath="src/app.js"] - Bundle path, relative to
  *   the bundle root, as the loader should request it.
+ * @param {Array<{path: string, hash: string, size: number}>} [opts.assets=[]]
+ *   Extra files the release serves at `update.url`, as returned by
+ *   {@link collectAssets}. `hash` still describes only the bundle.
  * @returns {object} The config.json manifest.
  */
 export const buildBundleConfig = ({
   projectRoot,
   bundleContent,
   bundlePath = "src/app.js",
+  assets = [],
 }) => {
   const pkg = readJsonSafe(path.join(projectRoot, "package.json"), {});
   const fletboxConfig = readJsonSafe(
@@ -159,6 +317,14 @@ export const buildBundleConfig = ({
     builtAt: new Date().toISOString(),
     bundle: bundlePath,
     size: content.length,
+    // Files the release serves beside the bundle (markdown, JSON, images). An
+    // installed app reads them through the loader's asset helper; without this
+    // list they are frozen at whatever version the APK/IPA was built with.
+    assets: Array.isArray(assets)
+      ? assets
+          .filter((a) => a && typeof a.path === "string" && typeof a.hash === "string")
+          .map((a) => ({ path: a.path, hash: a.hash, size: Number(a.size) || 0 }))
+      : [],
     // Minimum native (APK/IPA) version this bundle is compatible with. When the
     // installed native shell is older, the loader must fall back to a store
     // update instead of applying the OTA. Defaults to "0.0.0" (always compatible).

package/bin/utils/dtsProps.js

@@ -172,6 +172,153 @@ export const resolveInterfaceProps = (interfaces, name, seen = new Set()) => {
   return resolved;
 };
 
+/**
+ * Index of the character closing the pair opened at `open`, or -1.
+ *
+ * @param {string} text
+ * @param {number} open
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+const matching = (text, open, left, right) => {
+  if (text[open] !== left) return -1;
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === left) depth++;
+    else if (text[i] === right) {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+};
+
+/**
+ * Read one type expression starting at `from`: balanced brackets keep nested
+ * object types whole, and the type ends at the first `;` or newline outside them.
+ *
+ * @param {string} code
+ * @param {number} from
+ * @returns {string}
+ */
+const readType = (code, from) => {
+  let depth = 0;
+  let text = "";
+  for (let i = from; i < code.length; i++) {
+    const ch = code[i];
+    if (ch === "=" && code[i + 1] === ">") {
+      text += "=>";
+      i++;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(" || ch === "<") depth++;
+    else if (ch === "}" || ch === "]" || ch === ")" || ch === ">") {
+      if (depth === 0) break;
+      depth--;
+    } else if (depth === 0 && (ch === ";" || ch === "\n")) break;
+    text += ch;
+  }
+  return text.trim().replace(/\s+/g, " ");
+};
+
+/**
+ * Split a declared parameter list into `{ name, type, optional }` fields.
+ *
+ * Commas only separate parameters at depth 0, so
+ * `(name: string, options?: { a: number, b: number })` stays two parameters.
+ *
+ * @param {string} params Text between the declaration's parentheses.
+ * @returns {Array<{ name: string, type: string, optional: boolean }>}
+ */
+const parseParams = (params) => {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of params) {
+    if (ch === "{" || ch === "[" || ch === "(" || ch === "<") depth++;
+    else if (ch === "}" || ch === "]" || ch === ")" || ch === ">") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  parts.push(current);
+  return parts
+    .map((part) =>
+      /^\s*([A-Za-z_$][\w$]*)\s*(\??)\s*:\s*([\s\S]+)$/.exec(part.trim()),
+    )
+    .filter(Boolean)
+    .map((m) => ({ name: m[1], optional: m[2] === "?", type: m[3].trim() }));
+};
+
+/**
+ * Read how each exported function is called and what it produces.
+ *
+ * Props say what a widget receives; the signature says what you hand it and what
+ * you get back, and that is the difference between `App({ … })`, `Modal({ … }).open()`
+ * and `Inspector(element, 2)`. Both declaration shapes in `index.d.ts` work:
+ *
+ *   export function Modal(props: ModalProps): { open(): void };
+ *   export const ThemeProvider: (props: { … }) => Widget;
+ *
+ * @param {string} source Full `.d.ts` text.
+ * @returns {Map<string, { params: Array<{ name: string, type: string, optional: boolean }>, returns: string }>}
+ */
+export const parseSignatures = (source) => {
+  const signatures = new Map();
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+  for (const m of code.matchAll(/export\s+function\s+([A-Za-z_$][\w$]*)\s*\(/g)) {
+    const open = m.index + m[0].length - 1;
+    const close = matching(code, open, "(", ")");
+    if (close < 0) continue;
+    let after = close + 1;
+    while (after < code.length && /\s/.test(code[after])) after++;
+    if (code[after] !== ":") continue;
+    signatures.set(m[1], {
+      params: parseParams(code.slice(open + 1, close)),
+      returns: readType(code, after + 1),
+    });
+  }
+  for (const m of code.matchAll(/export\s+(?:declare\s+)?const\s+([A-Za-z_$][\w$]*)\s*:\s*/g)) {
+    const type = readType(code, m.index + m[0].length);
+    if (!type.startsWith("(")) continue; // a constant, not a factory
+    const close = matching(type, 0, "(", ")");
+    if (close < 0) continue;
+    const rest = type.slice(close + 1);
+    const arrow = rest.indexOf("=>");
+    if (arrow < 0) continue;
+    signatures.set(m[1], {
+      params: parseParams(type.slice(1, close)),
+      returns: rest.slice(arrow + 2).trim(),
+    });
+  }
+  return signatures;
+};
+
+/**
+ * List the members of a returned object type: `open()` means a method,
+ * `isOpen: boolean` a property. Empty for plain types like `Widget`.
+ *
+ * @param {string} type A return type produced by `parseSignatures`.
+ * @returns {string[]}
+ */
+export const membersOf = (type) => {
+  const open = type?.indexOf("{");
+  if (open === undefined || open < 0 || !type.trim().endsWith("}")) return [];
+  const body = type.slice(open + 1, type.lastIndexOf("}"));
+  return splitMembers(body)
+    .map((member) => {
+      const method = /^([A-Za-z_$][\w$]*)\s*(\??)\s*\(/.exec(member);
+      if (method) return `${method[1]}()`;
+      const field = /^([A-Za-z_$][\w$]*)\s*(\??)\s*:/.exec(member);
+      return field ? field[1] : null;
+    })
+    .filter(Boolean);
+};
+
 /**
  * Find the declaration that types a widget's props object.
  *