flet-box 1.1.1 → 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/create.js

@@ -546,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/utils/bundleConfig.js

@@ -9,7 +9,8 @@
  * comparison that drives the OTA is the `hash` — the version is a human label.
  *
  * Update source URL resolution order:
- *   1. `update.url` in `fletbox.config.json` (explicit wins)
+ *   1. `update.url` in `fletbox.config.json`, when it is set and is no longer
+ *      the scaffold placeholder (explicit wins over the derivation below)
  *   2. derived from the `repository` field of the project's package.json,
  *      mapped to its GitHub Pages URL: https://<user>.github.io/<repo>/
  *   3. derived from the CURRENT PROJECT's git remote `origin` (when it is a
@@ -69,6 +70,23 @@ export const parseGithubRepo = (repository) => {
   return null;
 };
 
+/**
+ * True when a declared `update.url` is still the scaffold placeholder — the two
+ * tokens `flet-box create` writes when it was not told where the app will live
+ * (`OTA_PLACEHOLDER_URL` in `templates.js`, and the same tokens in the generated
+ * workflow header).
+ *
+ * A placeholder is not a decision, so it must not outrank derivation: a bundle
+ * that carries it points an installed app at a host that does not exist, and the
+ * OTA check fails on every launch in silence — OTA is built never to break the
+ * app, so the only symptom is that an update is never offered.
+ *
+ * @param {*} url
+ * @returns {boolean}
+ */
+export const isPlaceholderUpdateUrl = (url) =>
+  typeof url === "string" && /TU-USUARIO|TU-REPO/.test(url);
+
 /**
  * Resolves the OTA update URL for a project.
  *
@@ -82,9 +100,15 @@ export const resolveUpdateUrl = (projectRoot) => {
     {},
   );
 
-  // 1. Explicit configuration always wins.
+  // 1. Explicit configuration wins — over the derivations below, not over the
+  // truth. An unfilled placeholder falls through, so a project whose origin
+  // remote is a GitHub repo gets its real Pages address without editing a file.
   const explicit = fletboxConfig?.update?.url;
-  if (typeof explicit === "string" && explicit.trim()) {
+  if (
+    typeof explicit === "string" &&
+    explicit.trim() &&
+    !isPlaceholderUpdateUrl(explicit)
+  ) {
     return explicit.endsWith("/") ? explicit : `${explicit}/`;
   }
 
@@ -107,6 +131,26 @@ export const resolveUpdateUrl = (projectRoot) => {
   return null;
 };
 
+/**
+ * Reads only what the project itself declares as its update source, without
+ * resolving or deriving anything.
+ *
+ * The build prints this when the URL that landed in the manifest came from
+ * derivation instead of from the file: a bundle pointing at a real site while
+ * `fletbox.config.json` still holds the placeholder is a half-filled config, and
+ * only the person editing that file can tell the two apart.
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {*} The declared `update.url`, or null when the file does not say.
+ */
+export const declaredUpdateUrl = (projectRoot) => {
+  const declared = readJsonSafe(
+    path.join(projectRoot, "fletbox.config.json"),
+    {},
+  )?.update?.url;
+  return typeof declared === "string" && declared.trim() ? declared : null;
+};
+
 /**
  * The `<meta>` tags a social scraper resolves against its own machine.
  *

package/bin/utils/templates.js

@@ -1296,14 +1296,21 @@ export const githubWorkflow = (appName = "FletBox App", siteUrl = null) => {
   const site = /^https?:\/\//i.test(String(siteUrl || ""))
     ? String(siteUrl).replace(/\/?$/, "/")
     : `https://TU-USUARIO.github.io/${slug}/`;
-  // Only when the owner is still a guess: the address lives in two files, and a
-  // developer who edits one and not the other ships an app that polls a site
-  // that is not where the bundle is.
+  // Only when the owner is still a guess. The build no longer trusts the
+  // placeholder in fletbox.config.json (createBundle derives the real Pages
+  // address from this repository), so what is left to correct here is the
+  // address a human reads before reading a single step.
   const todo = site.includes("TU-USUARIO")
     ? `# The owner above is a placeholder: this project was created without \`--repo\`,
-# so the folder name is only a guess at the repo name. Write the real address in
-# both files that state it — this header, and fletbox.config.json (update.url),
-# which is the URL an installed app polls for an update.
+# so the folder name is only a guess at the repo name. Put the real owner here
+# once the repository exists.
+#
+# \`fletbox.config.json\` may keep its own placeholder: the build recognises it as
+# "not configured" and derives the address from this repo's repository field or
+# git remote, so an installed app polls the site this workflow deploys. The URL
+# that landed in the manifest is printed by the build and by the
+# \`Where this lives\` step below. Set \`update.url\` by hand only when this app
+# will live on another host.
 `
     : "";
   return `name: Deploy ${appName}
@@ -1779,9 +1786,12 @@ Two workflow files ship with the project, and they answer to different triggers:
 The address this project publishes to is written at the top of
 \`.github/workflows/build.yml\`. \`flet-box create <name> --repo <user>/<repo>\`
 fills it in from the repo; without \`--repo\` it stays
-\`https://TU-USUARIO.github.io/<name>/\`, and the header says which two files to
-edit. That is a sub-path, so \`index.html\` uses relative asset paths and works
-without changes.
+\`https://TU-USUARIO.github.io/<name>/\`, and the header explains what is still a
+guess. The build ignores that placeholder in \`fletbox.config.json\` and derives
+the real address from this repository, so the OTA feed is correct either way.
+
+The Pages address is a sub-path, so \`index.html\` uses relative asset paths and
+works without changes.
 
 **Why a push does not update anyone's app:** this same address is the OTA feed
 installed apps poll, and the update check compares bundle **hashes**, not version
@@ -1871,9 +1881,10 @@ updates:
 \`\`\`
 
 - The GitHub repository **must be public**.
-- Replace \`TU-USUARIO\` with your GitHub username and \`TU-REPO\` with the
-  repository name, or set \`update.url\` to any HTTPS host that serves your
-  \`config.json\` + bundle.
+- \`TU-USUARIO\`/\`TU-REPO\` are a placeholder, not a setting: the build sees them as
+  "not configured" and derives the Pages address from this project's \`repository\`
+  field or git remote, so pushing the folder is enough. Edit \`update.url\` only
+  when the app lives on another HTTPS host that serves your \`config.json\` + bundle.
 - Enable GitHub Pages: **Settings → Pages → Source: GitHub Actions**. Without
   that the deploy step is green and no site exists.
 - Cut a release with \`flet-box release --push\` (bumps the version, rebuilds

package/docs/README.md

@@ -71,4 +71,25 @@ Front cover (this page)
 
 - [Server toolkit](server/README.md) — Express/SQLite/Redis backend helpers (separate toolkit).
 - [Architecture](arquitectura.md) — how the framework is built inside.
-- [Contributing](CONTRIBUTING.md) — for people who add code or docs to FletBox.
+- [Contributing](CONTRIBUTING.md) — for people who add code or docs to FletBox.
+
+## Read this book as an app
+
+The same pages are also a FletBox application: **[flet-box-docs](https://github.com/kuko53348/flet-box-docs)**, published to npm as its own package.
+
+```bash
+npm install flet-box-docs        # then: cd node_modules/flet-box-docs && npm install && npm run dev
+```
+
+It is a normal FletBox project — the router, a categorized index, cross-document
+Previous/Next, a light/dark toggle, an offline cache, and Capacitor wrappers for
+Android and iOS — and every page is rendered by the framework's own `Markdown`
+widget, so the book is also a live demo of the widget that writes it.
+
+Its `docs/` folder is a **snapshot** of this folder, refreshed before each
+release; when the app is online it reads the published source instead, so a page
+added here arrives on an installed device without a new build. That is why
+`flet-box-docs` carries a version of its own: it is a shipping app, and its
+`npm run build` refuses to bundle until `src/constants.js` states both versions
+out loud — the app's own, which must match its `package.json`, and the framework
+release its pages describe.

package/docs/cli/README.md

@@ -21,14 +21,17 @@ npm --version
 
 ## Install FletBox
 
-Inside the FletBox package directory:
+FletBox is published to npm, so the CLI is one install away:
 
 ```bash
-npm install
-npm link
+npm install -g flet-box
 ```
 
-After linking, the `flet-box` command is available globally on your computer.
+Or run it without installing anything globally — `npx` fetches the same package:
+
+```bash
+npx flet-box create my-app
+```
 
 Check that it works:
 
@@ -37,12 +40,22 @@ flet-box --version
 flet-box --help
 ```
 
-When using the published package, install it in a project with:
+Inside a project the framework itself is an ordinary dependency:
 
 ```bash
 npm install flet-box
 ```
 
+Cloning the repository and linking it is the exception, and it is for people
+editing the framework:
+
+```bash
+git clone https://github.com/kuko53348/flet-box.git
+cd flet-box
+npm install
+npm link                          # the `flet-box` command now points at this checkout
+```
+
 ## Your first project
 
 Create a project with the default template:
@@ -84,9 +97,12 @@ CI:      .github/workflows/build.yml publishes the web to GitHub Pages on every
 ```
 
 The first positional argument is always the project name; a flag that arrives
-before it is read as the name. Without `--repo` nothing is invented — the
-placeholder stays in both files and the workflow says which two to edit. The
-reason the workflow log, not the header, is the authority on the live address is
+before it is read as the name. Without `--repo` nothing is invented: the
+placeholder stays in `fletbox.config.json` and in the workflow header, and the
+header says which part of it is still a guess. `flet-box createBundle` reads that
+placeholder as "not configured" and derives the real Pages address from the
+project, so the manifest is never aimed at a host that does not exist. The reason
+the workflow log, not the header, is the authority on the live address is
 explained in [The Pages address of a generated app](../guides/online-updates.md).
 
 ## Project templates
@@ -636,9 +652,17 @@ For normal application development, `npm install flet-box` is usually enough.
 
 ### `flet-box: command not found`
 
-The CLI is not linked or installed globally. From the FletBox package directory, run:
+The CLI is not installed globally. Install the published package:
+
+```bash
+npm install -g flet-box
+```
+
+If you are working from a clone of the framework instead, link that checkout so the
+command points at the code you are editing:
 
 ```bash
+cd flet-box
 npm install
 npm link
 ```

package/docs/guides/first-app.md

@@ -4,24 +4,23 @@ This page is for **absolute beginners**. You do not need to know any trick — y
 
 ## Before you start
 
-FletBox is not published to the npm registry, so first you install the CLI once and link it globally:
+You need Node.js 20.9 or newer and one command, because FletBox is published on npm:
 
 ```bash
-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
 ```
 
-Then create an empty project, link the framework into it, and start the dev server:
+Then create an empty project, install the framework into it, and start the dev server:
 
 ```bash
-cd ..
 flet-box create my-app
 cd my-app
-npm link flet-box                 # or: npm install ../path/to/flet-box
+npm install                       # flet-box itself, from the registry
 npm run dev
 ```
 
+If you would rather not install anything globally, `npx flet-box create my-app` does the same thing.
+
 Open your browser at `http://localhost:8000`. You should see "Hello FletBox" (or a small welcome screen). If you do, everything is working.
 
 ## Step 1: the smallest app

package/docs/guides/online-updates.md

@@ -116,7 +116,7 @@ Every bundle ships a small manifest at `www/config.json`. This is what a running
 
 `update.url` is resolved automatically, in this order:
 
-1. `update.url` in `fletbox.config.json` at your project root (explicit wins).
+1. `update.url` in `fletbox.config.json` at your project root (explicit wins) — unless it is still the scaffold placeholder, which is not a choice. See [The Pages address of a generated app](#the-pages-address-of-a-generated-app).
 2. Derived from the `repository` field of `package.json`, mapped to GitHub Pages: `https://<user>.github.io/<repo>/`.
 3. Derived from the **current project's** git remote `origin` (when it is a GitHub URL). This means `flet-box createBundle` always points at the project it is built in, never at the flet-box framework installed as a dependency.
 4. If none of these exist, OTA is **disabled** and the bundle simply runs what shipped in it.
@@ -152,10 +152,22 @@ things at once:
 - writes that address into the header of the generated `.github/workflows/build.yml`;
 - prints it in the closing summary, with the one-time setting Pages needs.
 
-Without `--repo` nothing is invented. `fletbox.config.json` keeps the generic
-placeholder `https://TU-USUARIO.github.io/TU-REPO/`, the workflow header names a
-guess built from the folder name, and the workflow says so in its own comment:
-write the real address in both files that state it.
+Without `--repo` nothing is invented at scaffold time. `fletbox.config.json` keeps
+the generic placeholder `https://TU-USUARIO.github.io/TU-REPO/`, the workflow
+header names a guess built from the folder name, and the workflow says in its own
+comment which part of that address still has to be checked by hand.
+
+The build does not trust that placeholder. `TU-USUARIO` and `TU-REPO` mean "not
+configured yet", so `flet-box createBundle` falls through to rules 2 and 3 and
+writes the address it derived — and prints that it derived, because a manifest
+pointing at a real site next to a file that still says `TU-REPO` is a half-filled
+config you should either finish or leave alone. A project with no GitHub remote
+yet gets `update.url: null`: OTA is off, the bundle runs what shipped in it, and
+nothing polls a host that does not exist.
+
+That matters because the failure used to be silent. The app compares bundle
+**hashes**, and OTA is built never to break the app, so a placeholder URL that
+reached a bundle produced no error, no dialog and no update — ever.
 
 **The workflow log is the authority.** The header names the address you typed at
 scaffold time; the `Where this lives` step prints the address the run *actually*
@@ -274,7 +286,7 @@ Requirements: a **public** GitHub repository, GitHub Pages enabled (Settings →
 | Symptom | Likely cause |
 | --- | --- |
 | Build prints "THIS APP DOES NOT SUPPORT OTA UPDATES" | No public GitHub repo is reachable from the project (no `origin` remote, a non-GitHub remote, or nothing configured). The app still works — it runs the bundle it shipped with. Create the repo, push it, and rebuild. |
-| No dialog, app runs old code | `update.url` missing/incorrect, or no `v*` tag was published — a normal push updates the site but deliberately leaves the manifest out, so there is nothing to compare against. |
+| No dialog, app runs old code | `update.url` wrong — a real address that is not where the bundle is (the scaffold placeholder is not one of those: the build derives the address and prints it). Or no `v*` tag was published — a normal push updates the site but deliberately leaves the manifest out, so there is nothing to compare against. |
 | `hash mismatch` in console | The published `config.json` and bundle are from different builds. Re-run `flet-box release` so both are published together. |
 | Dialog appears but download fails | The Pages site is not reachable/CORS-blocked from the app origin. Pages serves with permissive headers; check you are not behind a proxy that strips them. |
 | Update applies but reverts on next launch | Cache Storage unavailable (private browsing). The bundle runs once but cannot persist. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Declarative, zero-dependency UI framework in vanilla JS — ship web, PWA, Android and iOS from one codebase",
   "type": "module",
   "main": "src/index.js",