flet-box 1.1.0 → 1.1.2

package/README.md

@@ -38,21 +38,24 @@ Real DOM · No Virtual DOM · No build config to learn.
 
 ## Installation
 
-FletBox isn't on the npm registry, so clone it and link the CLI locally:
+FletBox is on npm, and it drags nothing in with it — `"dependencies": {}`:
 
 ```bash
-brew install node                 # macOS/Linux: ensure Node >= 18
-
-git clone https://github.com/kuko53348/flet-box.git
-cd flet-box
-npm link                          # link the flet-box CLI globally
+npm install -g flet-box           # the CLI, once (Node >= 20.9)
 
 flet-box create appName           # scaffold your first app
 cd appName
-npm link flet-box                 # link FletBox into the new project
-flet-box run-spa                  # run as SPA with hot reload
+npm install                       # pulls flet-box itself from the registry
+flet-box run                      # dev server with hot reload
 ```
 
+Nothing to install at all: `npx flet-box create appName` runs the same scaffolder
+straight from the registry, and the project it writes declares `flet-box` as a
+normal dependency.
+
+Cloning the repository and `npm link`ing it is still how you *develop the framework
+itself* — see [CONTRIBUTING](docs/CONTRIBUTING.md).
+
 ## Quick start
 
 ```javascript
@@ -80,7 +83,7 @@ runApp(App);
 ## Features
 
 - Declarative, widget-based UI · reactive state with `useState` · router for SPAs
-- Zero runtime dependencies; ESM only, Node >= 18 · real DOM, no Virtual DOM
+- Zero runtime dependencies; ESM only, Node >= 20.9 · real DOM, no Virtual DOM
 - Local storage, HTTP services, theme, PWA, and production builds
 - Android & iOS from the CLI (APK, simulator `.app`, `.xcarchive`)
 - Utility API for layout, text, color, animation, and more
@@ -137,12 +140,11 @@ invent against.
 
 ## Android and iOS
 
-`flet-box create` ships the Capacitor config, so the same SPA builds for both platforms. FletBox isn't on the npm registry — link it before installing:
+`flet-box create` ships the Capacitor config, so the same SPA builds for both platforms. The generated project already declares `flet-box` as a dependency, so one install covers everything:
 
 ```bash
 flet-box create my-app && cd my-app
-npm link flet-box              # or: npm install ../path/to/flet-box
-npm install                    # Capacitor CLI, sharp, platform package
+npm install                    # flet-box from the registry, plus the Capacitor toolchain
 ```
 
 - **Android** — Node >= 20.9, a JDK, and the Android SDK. `flet-box build android` → debug APK; `flet-box build android --release [--aab]` → unsigned release artifact to sign yourself (`apksigner` / Play App Signing).
@@ -160,6 +162,8 @@ They are **one continuous book** — the cover maps every page: [The FletBox Boo
 
 Rather than read, click: **[the live widget gallery](https://kuko53348.github.io/flet-box-widgets-exemples/)** gives every widget its own page, renders each example in the browser it was written for, and prints the exact call underneath it. The theme toggle in the corner shows the same screen in light and dark, which is the honest way to judge a default color.
 
+And the book itself is an app: **[`flet-box-docs`](https://www.npmjs.com/package/flet-box-docs)** (`npm install flet-box-docs`) renders these same pages with the framework's own `Markdown` widget, with an index, a theme toggle, an offline cache and Android/iOS wrappers.
+
 - [Your first app](docs/guides/first-app.md) — build a working todo app in 20 minutes
 - [The widget book](docs/widget/README.md) — every widget with property tables and examples
 - [State, Router & Services](docs/guides/state.md) — shared state, routing, storage, and HTTP

package/bin/commands/checkUi.js

@@ -120,8 +120,9 @@ export const INFO_CODES = new Set([
  * Which design rule each code proves, and the number the finding prints.
  *
  * The gate is the machine half of a contract whose human half is
- * `skills/fletbox-design/SKILL.md`: 25 numbered rules, read by the agent that
- * builds the screen. A finding that says `OFF_SCALE_SPACING` tells the reader the
+ * `skills/fletbox-design/SKILL.md`: 38 numbered rules across two parts, of which
+ * this table cites the enforceable 00-24 (25-37 are the visual atlas, judgement
+ * no static pass can prove). A finding that says `OFF_SCALE_SPACING` tells the reader the
  * value is wrong; a finding that says `OFF_SCALE_SPACING — rule 07` tells them to
  * open rule 07 and learn *why*, which is the only way the next screen is right
  * without being told twice. `scripts/check-skills.mjs` fails if a code is missing
@@ -390,7 +391,9 @@ export const entriesOf = (code, open, close) => {
 };
 
 /**
- * Numeric literals written in a value, skipping the ones inside strings.
+ * Numeric literals written in a value, skipping the ones inside strings. This is
+ * a lexical scan, not an evaluation: use `measuredNumbers` before judging a
+ * value against a scale, or `base * 1.5` is read as a 1.5 size.
  *
  * @param {string} value
  * @returns {Array<{number: number, offset: number}>}
@@ -415,6 +418,143 @@ export const numbersIn = (value) => {
   return found;
 };
 
+/**
+ * Tokenise an arithmetic expression made only of number literals operators and
+ * parentheses. Anything else — an identifier, a member access, a call, a
+ * ternary, an object or array — returns null, because its value is decided at
+ * runtime and a static pass that guessed it would report a number the screen
+ * never paints.
+ *
+ * @param {string} text
+ * @returns {Array<{type: string, value?: number}> | null}
+ */
+const arithmeticTokens = (text) => {
+  const tokens = [];
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
+    if (/[0-9]/.test(ch) || (ch === "." && /[0-9]/.test(text[i + 1] ?? ""))) {
+      const match = /^\d*\.?\d+(?:[eE][+-]?\d+)?/.exec(text.slice(i));
+      tokens.push({ type: "number", value: Number(match[0]) });
+      i += match[0].length;
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(ch)) return null;
+    if ("+-*/%()".includes(ch)) {
+      tokens.push({ type: ch });
+      i++;
+      continue;
+    }
+    return null;
+  }
+  return tokens;
+};
+
+/**
+ * Evaluate a token list by recursive descent. Null means "not provable", which
+ * is never the same answer as "off the scale".
+ *
+ * @param {Array<{type: string, value?: number}>} tokens
+ * @returns {number | null}
+ */
+const foldArithmetic = (tokens) => {
+  let i = 0;
+  const bad = () => {
+    throw new Error("unmeasurable");
+  };
+  const primary = () => {
+    const token = tokens[i++];
+    if (!token) bad();
+    if (token.type === "number") return token.value;
+    if (token.type === "(") {
+      const value = expression();
+      if (tokens[i++]?.type !== ")") bad();
+      return value;
+    }
+    return bad();
+  };
+  const unary = () => {
+    if (tokens[i]?.type === "-") {
+      i++;
+      return -unary();
+    }
+    if (tokens[i]?.type === "+") {
+      i++;
+      return unary();
+    }
+    return primary();
+  };
+  const term = () => {
+    let value = unary();
+    while (["*", "/", "%"].includes(tokens[i]?.type)) {
+      const op = tokens[i++].type;
+      const right = unary();
+      if (op === "*") value *= right;
+      else if (right === 0) bad();
+      else value = op === "/" ? value / right : value % right;
+    }
+    return value;
+  };
+  const expression = () => {
+    let value = term();
+    while (["+", "-"].includes(tokens[i]?.type)) {
+      const op = tokens[i++].type;
+      value = op === "+" ? value + term() : value - term();
+    }
+    return value;
+  };
+  try {
+    if (!tokens.length) return null;
+    const value = expression();
+    if (i !== tokens.length || !Number.isFinite(value)) return null;
+    return value;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The numbers a prop value provably paints, and whether the pass can say at all.
+ *
+ * A value is measured when it is a literal (`24`), arithmetic over literals
+ * (`8 * 3`), a quoted pixel shorthand (`"12px 20px"`), or any other literal
+ * string (a preset name has no numbers and is therefore on no scale to break).
+ * It is unmeasured when its value depends on an identifier, a ternary, a call or
+ * a member access — `size: base * 1.5`, `sz.h - 8`, `padding: size > 20 ? … : 0`.
+ * The distinction is the point: a lexical scan reads the `1.5` inside
+ * `base * 1.5` as the size and reports a value the screen never renders.
+ *
+ * @param {string} value raw prop value
+ * @returns {{measured: boolean, numbers: number[]}}
+ */
+export const measuredNumbers = (value) => {
+  const text = value.trim();
+  if (!text) return { measured: true, numbers: [] };
+  const quote = text[0];
+  if (isQuote(quote)) {
+    const end = skipString(text, 0);
+    if (end !== text.length) return { measured: false, numbers: [] };
+    const body = text.slice(1, end - 1);
+    if (/\\|\$\{/.test(body)) return { measured: false, numbers: [] };
+    if (/\b(?:var|calc|clamp|min|max|rgb|rgba|hsl|hsla)\s*\(|%/.test(body)) {
+      return { measured: false, numbers: [] };
+    }
+    const numbers = [...body.matchAll(/-?\d+(?:\.\d+)?px|\b0\b/g)].map((match) =>
+      match[0].endsWith("px") ? Number(match[0].slice(0, -2)) : 0,
+    );
+    return { measured: true, numbers };
+  }
+  const tokens = arithmeticTokens(text);
+  if (!tokens) return { measured: false, numbers: [] };
+  const folded = foldArithmetic(tokens);
+  if (folded === null) return { measured: false, numbers: [] };
+  return { measured: true, numbers: [folded] };
+};
+
 /**
  * `#rgb`/`#rrggbb`/`#rrggbbaa` or a functional color typed as a literal.
  *
@@ -695,6 +835,68 @@ const finding = (ctx, line, code, message, detail) => ({
  * @param {object} ctx resolved package data
  * @returns {object[]} findings
  */
+/**
+ * Is the `{` at `brace` a function body? Looks back over the parameter list and
+ * asks what closes it: `function`, an arrow, or a method name. Control blocks
+ * (`if`, `for`, `switch`, `catch`, `try`, `else`) and object literals — including
+ * a widget's own `Widget({ … })` — are not function bodies.
+ *
+ * @param {string} code
+ * @param {number} brace index of `{`
+ * @returns {boolean}
+ */
+const opensFunction = (code, brace) => {
+  let i = brace - 1;
+  let depth = 0;
+  while (i >= 0) {
+    const ch = code[i];
+    if (ch === ")" || ch === "]") depth++;
+    else if (ch === "(" || ch === "[") {
+      if (depth === 0) break;
+      depth--;
+    } else if (depth === 0 && (ch === ";" || ch === "{" || ch === "}" || ch === "\n")) {
+      break;
+    }
+    i--;
+  }
+  const head = code.slice(i + 1, brace).trim();
+  if (/^(?:async\s+)?function\b/.test(head)) return true;
+  if (/(?:^|[\s;}])(?:async\s+)?(?:\([^]*?\)|[A-Za-z_$][\w$]*)\s*=>$/.test(head)) return true;
+  const method = /^([A-Za-z_$][\w$]*)\s*\([^]*\)$/.exec(head);
+  return Boolean(
+    method &&
+      !["if", "for", "while", "switch", "catch", "with", "do", "else", "try"].includes(
+        method[1],
+      ),
+  );
+};
+
+/**
+ * The brace range of every function body in a file.
+ *
+ * @param {string} code
+ * @returns {Array<[number, number]>} `[open, close]` pairs
+ */
+export const functionBodies = (code) => {
+  const bodies = [];
+  const open = [];
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i];
+    if (isQuote(ch)) {
+      i = skipString(code, i) - 1;
+      continue;
+    }
+    if (ch === "{") {
+      open.push(i);
+      continue;
+    }
+    if (ch !== "}") continue;
+    const start = open.pop();
+    if (start !== undefined && opensFunction(code, start)) bodies.push([start, i]);
+  }
+  return bodies;
+};
+
 const checkFile = (file, ctx) => {
   const findings = [];
   const src = fs.readFileSync(file, "utf8");
@@ -716,6 +918,7 @@ const checkFile = (file, ctx) => {
     }
     return { ...call, props };
   });
+  const bodies = functionBodies(code);
 
   /**
    * The nearest enclosing call that says it paints a plate. Its props are handed
@@ -771,23 +974,27 @@ const checkFile = (file, ctx) => {
     );
   };
 
-  const namedByTooltip = (call) =>
-    enclosing(call).some((other) => other.name === "Tooltip" && other.props.has("text"));
-
   /**
    * A glyph control that carries its own accessible name is named, even when this
    * pass cannot see the wrapper: an app that builds the control inside a helper
-   * and wraps the *result* in a Tooltip has a `child: iconButton("share")` at the
-   * call site, and a lexical scan stops at the helper's own braces. `aria-*` is a
-   * routed passthrough (translateProps.js:948), so the name really does reach the
+   * and names the *result* at the call site has a `child: iconButton("share")` at
+   * the call site, and a lexical scan stops at the helper's own braces. `aria-*` is
+   * a routed passthrough (translateProps.js:948), so the name really does reach the
    * DOM — which is the sentence the finding asks for.
+   *
+   * A `Tooltip` is deliberately not on this list. It points `aria-describedby` at
+   * the bubble, and a description is not a name: a screen reader still announces
+   * "button" with no word for what it does.
    */
   const namedByAria = (call) =>
     [...call.props.keys()].some((key) => /^aria-(label|labelledby)$/i.test(key));
 
-  const isFilled = (call) =>
-    call.name === "Button" &&
-    !/['"`](outlined|text)['"`]/.test(call.props.get("variant")?.value ?? "");
+  const isFilled = (call) => {
+    if (call.name !== "Button") return false;
+    const variant = call.props.get("variant")?.value.trim();
+    if (variant === undefined) return true;
+    return /^(['"`])filled\1$/.test(variant);
+  };
 
   /** A width that caps the block: a number or a percentage below full bleed. */
   const capsWidth = (call) => {
@@ -811,7 +1018,8 @@ const checkFile = (file, ctx) => {
       if (SKIP_VALUE_KEYS.has(key)) continue;
       const kind = ctx.propKinds.get(key);
       const valueLine = lineOf(offsets, entry.valueStart);
-      const numbers = numbersIn(entry.value);
+      const measured = measuredNumbers(entry.value);
+      const numbers = measured.numbers;
 
       if (kind === "color" || COLOR_FALLBACK_KEYS.has(key)) {
         const literal = colorLiteralIn(entry.value);
@@ -834,45 +1042,35 @@ const checkFile = (file, ctx) => {
 
       if (kind === "spacing") {
         for (const n of numbers) {
-          if (SPACING_SCALE.has(Math.abs(n.number))) continue;
+          if (SPACING_SCALE.has(Math.abs(n))) continue;
           push(
             valueLine,
             "OFF_SCALE_SPACING",
-            `${call.name}.${key} = ${n.number} is not on the spacing scale.`,
+            `${call.name}.${key} = ${n} is not on the spacing scale.`,
             "Use 4 · 8 · 12 · 16 · 18 · 24 · 32 · 40 · 48 · 64 · 96. The scale is what makes two screens look like one app.",
           );
         }
         // A CSS shorthand still has to obey the scale: `padding: '12px 20px'` is
-        // the same mistake with a unit glued on.
-        if (!numbers.length) {
-          for (const match of entry.value.matchAll(/\d+(?:\.\d+)?px/g)) {
-            const value = Number(match[0].slice(0, -2));
-            if (SPACING_SCALE.has(value)) continue;
-            push(
-              valueLine,
-              "OFF_SCALE_SPACING",
-              `${call.name}.${key} = '${match[0]}' is not on the spacing scale.`,
-              "Use 4 · 8 · 12 · 16 · 18 · 24 · 32 · 40 · 48 · 64 · 96, or the plain number the factory prefers.",
-            );
-          }
-        }
+        // the same mistake with a unit glued on, and `measuredNumbers` already
+        // read it — an unmeasurable one (`calc`, `var`, a percentage) reports no
+        // numbers instead of the literals it happens to contain.
       } else if (kind === "radius") {
         for (const n of numbers) {
-          if (RADIUS_SCALE.has(Math.abs(n.number))) continue;
+          if (RADIUS_SCALE.has(Math.abs(n))) continue;
           push(
             valueLine,
             "OFF_SCALE_RADIUS",
-            `${call.name}.${key} = ${n.number} is not a scale radius.`,
-            "Use 4 · 8 · 12 · 16 · 999 (a pill). A radius between them is a shape no other card in this app has.",
+            `${call.name}.${key} = ${n} is not a scale radius.`,
+            "Use 4 · 8 · 12 · 16 · 20 · 24 · 999 (a pill). A radius between them is a shape no other card in this app has.",
           );
         }
       } else if (kind === "type" && (key === "fontSize" || call.name === "Text")) {
         for (const n of numbers) {
-          if (TYPE_SCALE.has(Math.abs(n.number))) continue;
+          if (TYPE_SCALE.has(Math.abs(n))) continue;
           push(
             valueLine,
             "OFF_SCALE_TYPE",
-            `${call.name}.${key} = ${n.number} is not a scale type size.`,
+            `${call.name}.${key} = ${n} is not a scale type size.`,
             "12 caption · 14 body-small · 16 body · 18 subtitle · 24 title · 32 headline · 40/48 display. One size per element, one weight per role.",
           );
         }
@@ -880,23 +1078,36 @@ const checkFile = (file, ctx) => {
 
       if (tappable && (key === "height" || key === "minHeight")) {
         for (const n of numbers) {
-          if (n.number <= 0 || n.number >= TAP_MINIMUM) continue;
+          if (n <= 0 || n >= TAP_MINIMUM) continue;
           push(
             valueLine,
             "SMALL_TAP_TARGET",
-            `${call.name} is pressable but only ${n.number}px tall.`,
+            `${call.name} is pressable but only ${n}px tall.`,
             `Fitts: a finger needs ${TAP_MINIMUM}x${TAP_MINIMUM}. Get there with \`height\`, not with padding.`,
           );
         }
       }
 
       if (tappable && ICON_WIDGETS.includes(call.name) && key === "size") {
+        // A glyph's target is its box, not its font size: `size: 16, padding: 12`
+        // is 40x40 and legal, while `size: 16` alone is the glyph and nothing else.
+        // A padding this pass cannot resolve makes the target unmeasured.
+        const padded = props.has("paddingVertical")
+          ? measuredNumbers(props.get("paddingVertical").value)
+          : props.has("padding")
+            ? measuredNumbers(props.get("padding").value)
+            : { measured: true, numbers: [0] };
+        const vertical = padded.measured ? Math.abs(padded.numbers[0] ?? 0) : null;
         for (const n of numbers) {
-          if (n.number >= TAP_MINIMUM || props.has("height")) continue;
+          if (vertical === null) break;
+          const target = n + vertical * 2;
+          if (target >= TAP_MINIMUM || props.has("height") || props.has("minHeight")) break;
           push(
             valueLine,
             "SMALL_TAP_TARGET",
-            `${call.name} is pressable at size ${n.number}, so its whole target is ${n.number}px.`,
+            `${call.name} is pressable at size ${n}${
+              vertical ? ` with ${vertical} of padding` : ""
+            }, so its whole target is ${target}px.`,
             `Wrap it in the ${TAP_MINIMUM}px box it needs, or use \`Button({ icon, onPress })\` and keep the glyph at 20.`,
           );
         }
@@ -956,14 +1167,13 @@ const checkFile = (file, ctx) => {
       ICON_WIDGETS.includes(call.name) &&
       tappable &&
       !labeledBySibling(call) &&
-      !namedByTooltip(call) &&
       !namedByAria(call)
     ) {
       push(
         line,
         "ICON_ONLY_CONTROL",
         `${call.name} is pressable and carries no name.`,
-        "Wrap it in `Tooltip({ text, child })`, put a `Text` beside it, or name the control itself with `\"aria-label\": \"Share\"`. A glyph with no words is a guess, and a screen reader says nothing at all.",
+        'A glyph with no words is a guess, and a screen reader says nothing at all. A `Tooltip` is a description (`aria-describedby`), not a name: put a `Text` beside the control or name it with `"aria-label": "Share"`.',
       );
     }
     if (
@@ -971,14 +1181,13 @@ const checkFile = (file, ctx) => {
       ["icon", "iconLeft", "iconRight"].some((key) => props.has(key)) &&
       !props.has("text") &&
       !labeledBySibling(call) &&
-      !namedByTooltip(call) &&
       !namedByAria(call)
     ) {
       push(
         line,
         "ICON_ONLY_CONTROL",
         "Button shows an icon and no label.",
-        "Give it `text`, or wrap it in `Tooltip({ text, child })`. Every person reads an unnamed glyph slightly differently.",
+        'Give it `text`, or name it with `"aria-label": "Share"`. A tooltip explains the control, it does not name it.',
       );
     }
 
@@ -1076,13 +1285,35 @@ const checkFile = (file, ctx) => {
     }
   }
 
-  // Rule 04 — one screen, one primary action. Emphasis is a budget, not a style.
+  // Rule 04 — one view, one primary action. Emphasis is a budget, not a style.
+  // The view is the function body a screen renders, not the file: a components
+  // module exports several screens, and two buttons in two components are never
+  // on the same screen. A `variant` this pass cannot resolve counts as neither,
+  // since the button may be outlined at runtime.
   const primaries = calls.filter(isFilled);
-  if (primaries.length > 1) {
+  const scopeOf = (call) => {
+    let scope = null;
+    for (const [start, end] of bodies) {
+      if (call.open > start && call.close < end && (scope === null || start > scope)) {
+        scope = start;
+      }
+    }
+    if (scope !== null) return `fn:${scope}`;
+    const root = enclosing(call).at(-1);
+    return root ? `root:${root.open}` : "file";
+  };
+  const views = new Map();
+  for (const call of primaries) {
+    const scope = scopeOf(call);
+    if (!views.has(scope)) views.set(scope, []);
+    views.get(scope).push(call);
+  }
+  for (const group of views.values()) {
+    if (group.length < 2) continue;
     push(
-      1,
+      lineOf(offsets, group[0].open),
       "MULTIPLE_PRIMARY_ACTIONS",
-      `${primaries.length} filled buttons in this file (lines ${primaries
+      `${group.length} filled buttons in this view (lines ${group
         .map((call) => lineOf(offsets, call.open))
         .join(", ")}).`,
       "Everything filled is competing with everything else. Keep one filled, make the next `variant: \"outlined\"`, and drop the rest to `variant: \"text\"`.",

package/bin/commands/create.js

@@ -249,6 +249,10 @@ export const createProject = async (projectName, rawArgs = []) => {
     path.join(projectPath, "package.json"),
     templates.packageJson(finalName),
   );
+  createFile(
+    path.join(projectPath, "jsconfig.json"),
+    templates.jsconfig(),
+  );
   createFile(
     path.join(projectPath, "fletbox.config.json"),
     templates.fletboxConfig(otaUrl || undefined),
@@ -542,7 +546,10 @@ export const createProject = async (projectName, rawArgs = []) => {
     console.log(
       c(
         "gray",
-        `⬆️  OTA: placeholder set — edit fletbox.config.json and replace TU-USUARIO/TU-REPO with your public GitHub repo.\n`,
+        `⬆️  OTA: ${templates.OTA_PLACEHOLDER_URL} is a placeholder, and the build knows it —\n` +
+          `         it derives the real Pages address from the project's \`repository\`/git remote.\n` +
+          `         So: push this folder to a public GitHub repo and build, or name the repo now\n` +
+          `         with ${c("brightCyan", "flet-box create <name> --repo user/repo")} / edit fletbox.config.json.\n`,
       ),
     );
   }

package/bin/commands/createBundle.js

@@ -17,7 +17,7 @@ import fs from "fs";
 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 { buildBundleConfig, collectAssets, getGitRemoteUrl, resolveAssetPatterns, absoluteShareTags, declaredUpdateUrl, isPlaceholderUpdateUrl } from "../utils/bundleConfig.js";
 import { normaliseManifest, writeSpaFallback } from "../utils/pwaShell.js";
 import { INITIAL_VERSION, incrementVersion, isValidVersion } from "../utils/version.js";
 
@@ -342,12 +342,24 @@ export const createBundle = async (targetArg) => {
         c("gray", "         (or set `update.url` in fletbox.config.json / `repository` in package.json)") +
         "\n",
     );
-  } else if (/TU-USUARIO|TU-REPO/.test(bundleConfig.update.url)) {
+  } else if (isPlaceholderUpdateUrl(declaredUpdateUrl(projectRoot))) {
+    // The file still says TU-USUARIO/TU-REPO, so this address was derived from
+    // the project's own repository — correct for a GitHub-hosted app, and worth
+    // saying out loud because the file the developer will read disagrees with it.
     console.log(
-      c(
-        "yellow",
-        "⚠️ update.url is still the placeholder — OTA points at a fake site. Replace TU-USUARIO/TU-REPO in fletbox.config.json before releasing.",
-      ),
+      c("green", "⬆️  OTA source: ") +
+        c("gray", bundleConfig.update.url) +
+        "\n" +
+        c(
+          "yellow",
+          "    derived from the project's `repository`/git remote: `fletbox.config.json` still holds the placeholder.",
+        ) +
+        "\n" +
+        c(
+          "gray",
+          "    Correct for a GitHub Pages site. Set `update.url` by hand if this app will live on another host.",
+        ) +
+        "\n",
     );
   } else {
     console.log(

package/bin/commands/createScreen.js

@@ -10,7 +10,7 @@
 
 import fs from "fs";
 import path from "path";
-import { c, banner, gradient, rainbow, section } from "../utils/colors.js";
+import { c, gradient, rainbow, section } from "../utils/colors.js";
 
 /**
  * Returns the source code for a new FletBox screen module.

package/bin/commands/runBundle.js

@@ -10,7 +10,7 @@
 
 import { createBundle } from "./createBundle.js";
 import { runDevServer } from "./runServer.js";
-import { c, banner, gradient, dot } from "../utils/colors.js";
+import { c, banner, dot } from "../utils/colors.js";
 
 /**
  * Builds the project bundle and serves it with a static dev server.