flet-box 1.0.5 → 1.0.7

package/docs/guides/online-updates.md

@@ -15,7 +15,11 @@ you edit source code
         v
 git tag v1.0.1 pushed to GitHub
         |
-        | GitHub Actions (on: tags v*)
+        | GitHub Actions — the web job deploys www/ on every push to main,
+        | and keeps www/config.json only when that commit carries a v* tag.
+        | A run started BY THE TAG cannot deploy (the github-pages environment
+        | accepts the default branch only), so publish the feed with one
+        | manual run on main: Actions → Deploy → Run workflow.
         v
 www/ deployed to GitHub Pages      <- the ONLY place an update is published
         |
@@ -33,7 +37,7 @@ loader.js fetches <update.url>/config.json
 
 Three invariants make this safe:
 
-1. **Updates are published only by release tags.** Ordinary `git push` runs CI (so breakage is caught) but never publishes, so a half-finished test build can never reach your users.
+1. **Only a release tag can be offered as an update.** The web workflow publishes your site on every push to main, so the preview is never stale — but it deletes `www/config.json` from any build whose commit carries no `v*` tag. With no manifest to read, an installed app logs `no remote config (offline or not deployed yet)` and keeps running the release it already has. So the site is live for reading while the update feed stays on tags, and a half-finished test build can never reach your users.
 2. **The app verifies integrity.** A downloaded bundle is executed only if its sha256 matches the hash in `config.json`.
 3. **The app always launches.** Offline, a wrong URL, a hash mismatch, or a declined dialog all fall back to the bundle already on the device. OTA can never brick the app.
 
@@ -54,7 +58,7 @@ flet-box release --push     # also push the commit and the tag to origin
 2. Bumps the version in `package.json` using the odometer scheme below.
 3. Rebuilds the production bundle (`www/`), which regenerates `www/config.json` with the new version and the sha256 of the new bundle.
 4. Commits the version bump and creates the annotated tag `vX.Y.Z`.
-5. Optionally pushes (`--push`), which triggers the CI deploy.
+5. Optionally pushes (`--push`), which deploys the site. The tag is what turns the update feed on, and a tag run cannot deploy by itself — after pushing, start the workflow once more from Actions (Run workflow, on main) and that build keeps `www/config.json`.
 
 If the build fails, the version bump is rolled back so a failed release leaves no trace.
 
@@ -79,6 +83,10 @@ Every bundle ships a small manifest at `www/config.json`. This is what a running
   "builtAt": "2026-10-11T19:53:24.524Z",
   "bundle": "src/app.js",
   "size": 36132,
+  "assets": [
+    { "path": "docs/widget/Maps.md", "hash": "b0f2…", "size": 4213 },
+    { "path": "data/catalog.json", "hash": "7ac9…", "size": 980 }
+  ],
   "minNativeVersion": "0.0.0",
   "update": {
     "url": "https://kuko53348.github.io/my-app/",
@@ -96,6 +104,7 @@ Every bundle ships a small manifest at `www/config.json`. This is what a running
 | `hash` | sha256 of the bundle. **This is what drives the update decision**, not the version. |
 | `bundle` | Path of the bundle relative to the update URL. |
 | `size` | Bundle size in bytes (shown in the dialog as KB). |
+| `assets` | Extra files this release publishes (see [Shipping extra files](#shipping-extra-files-release-assets)). Each entry is verified by its own `hash`; the bundle `hash` never covers them. |
 | `minNativeVersion` | Oldest native shell this bundle supports. Older shells are told to update from the store instead. |
 | `update.url` | Where `config.json` and the bundle are published (your GitHub Pages site). |
 | `update.mode` | `prompt` (ask the user, default) or `auto` (download silently). |
@@ -127,6 +136,44 @@ To configure it by hand, create `fletbox.config.json`:
 }
 ```
 
+## Shipping extra files (release assets)
+
+OTA swaps **one file**: `src/app.js`. Anything your app reads from disk at runtime — markdown pages, JSON data, per-tenant config — keeps the copy baked into the build the device installed. So an app installed three releases ago can run a bundle that was updated over the air and still be missing files the current catalog refers to. The symptom is not a crash, it is a "this page does not exist" for content that clearly exists online.
+
+Declare those files in `fletbox.config.json` and they become part of every release:
+
+```json
+{
+  "update": {
+    "assets": ["docs/**/*.md", "data/catalog.json"]
+  }
+}
+```
+
+Globs are relative to the project root and support `**`, `*` and `?`. At build time `flet-box createBundle` copies each match into `www/` at the same path, hashes it, and lists it in the manifest's `assets` array — which is also what your CI publishes to GitHub Pages.
+
+The app then reads them through the loader instead of `fetch`:
+
+```js
+const asset = await globalThis.__FLETBOX_OTA_ASSET__?.("docs/widget/Maps.md");
+const markdown = asset && asset.ok ? await asset.text() : await (await fetch("./docs/widget/Maps.md")).text();
+```
+
+It returns a `Response`, or `null` when the file exists in neither place. For each path it tries, in order:
+
+1. **The OTA cache** — the published copy already downloaded on a previous launch, so repeat reads and offline reads are free.
+2. **The published release** at `update.url`. The bytes are verified against the manifest hash; a mismatch is logged and ignored rather than trusted.
+3. **The copy inside this build**, exactly as `fetch` would return it.
+
+Because step 3 is always available, the helper can never leave you with less than you had before: an unpublished file, an offline device, or a tampered download all serve the shipped copy.
+
+Two rules keep this honest:
+
+- **A file only updates OTA if it is listed.** An empty or missing `assets` list means the manifest publishes nothing but the bundle.
+- **Bundle and assets are verified separately.** `hash` is the bundle; each asset entry carries its own hash, so one corrupted file cannot serve unverified content — and a bad asset never blocks a good bundle update.
+
+**Old shells have no helper.** `loader.js` is baked into the native build and OTA replaces the bundle, never the loader — so a store build made before this feature cannot fetch published assets, however many updates it accepts. That is what the `fetch` fallback in the snippet is for, and it closes only when you ship a new store build.
+
 ## What the app does on launch
 
 `www/loader.js` (wired in automatically as the module entry of every production bundle) runs **before** your app:
@@ -141,17 +188,17 @@ The dialog is plain HTML/CSS rendered by the loader itself, so it appears before
 
 ## What OTA can and cannot change
 
-OTA replaces the **web layer only** — the files inside `www/`.
+OTA replaces the **web layer only**: the `src/app.js` bundle plus whatever you list in `update.assets`. Everything else on the device is what the store build shipped.
 
 | Updates over the air | Needs a new store submission |
 | --- | --- |
 | UI, screens, widgets, styles | New native plugins / Capacitor version |
 | App logic and routing | New Android/iOS permissions |
-| Text, images, fonts, assets in `www/` | Changes to `AndroidManifest.xml` / `Info.plist` |
+| Release assets declared in `update.assets` (markdown, JSON, images) | Changes to `AndroidManifest.xml` / `Info.plist` |
 | Bug fixes and new JS features | Native code or signing changes |
 | Anything inside the bundle | Anything that changes the app's identity or purpose |
 
-Rule of thumb: if the change lives in `src/` (your FletBox code) it ships OTA; if it lives in the native shell it goes through the store. The `minNativeVersion` field exists for the boundary case where a new web bundle needs a newer shell: older shells skip the OTA and you direct users to the store update.
+Rule of thumb: if the change lives in `src/` (your FletBox code) it ships OTA; if it lives in the native shell it goes through the store. A data or content file ships OTA only when it is listed in `update.assets` — otherwise the device keeps the copy its store build baked in. The `minNativeVersion` field exists for the boundary case where a new web bundle needs a newer shell: older shells skip the OTA and you direct users to the store update.
 
 ## Store policy (read this before relying on OTA)
 
@@ -170,19 +217,20 @@ The generated service worker uses a hybrid strategy so OTA and offline coexist:
 - **Static assets** (fonts, icons, images, css): cache-first, since they are immutable per release.
 - **Cross-origin requests** (your remote `config.json` and bundle) are left to the network and are never cached by the worker.
 
-Downloaded OTA bundles live in a **separate** cache (`fletbox-ota`) owned by the loader, so a service-worker update never wipes an installed OTA bundle.
+Downloaded OTA bundles **and** release assets live in a **separate** cache (`fletbox-ota`) owned by the loader, so a service-worker update never wipes an installed OTA bundle. The loader fetches published assets with `cache: no-store`, so a stale service-worker copy of a file in `www/` cannot shadow the published one.
 
 ## Requirements and troubleshooting
 
-Requirements: a **public** GitHub repository, GitHub Pages enabled (Settings → Pages → Source = "GitHub Actions"), and the workflow from `flet-box create` (it already deploys `www/` on `v*` tags). GitHub Pages and Actions are free for public repos.
+Requirements: a **public** GitHub repository, GitHub Pages enabled (Settings → Pages → Source = "GitHub Actions"), and the workflow from `flet-box create` (`.github/workflows/build.yml` publishes `www/` on every push, and publishes the OTA manifest only for a `v*` tag; Android and iOS live in `build-native.yml`, which starts by hand). GitHub Pages and Actions are free for public repos.
 
 | 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 the tag was never pushed (CI never published). |
+| 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. |
 | `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. |
+| A data/content file is missing on the device but published online | It is not listed in `update.assets`, so OTA only ever replaced the bundle — or the installed shell predates release assets, in which case the app must fall back to its own copy. |
 | Want to force a clean state | Clear site data for the app origin (this removes the OTA cache and localStorage entry). |
 
 Because the decision is hash-based, two builds of identical source produce the same hash and no spurious update is offered; only a real content change triggers the dialog.

package/docs/widget/Accordion.md

@@ -58,6 +58,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/AdMob.md

@@ -57,6 +57,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/AdSense.md

@@ -51,6 +51,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/AnimatedBox.md

@@ -45,6 +45,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/AnimatedText.md

@@ -41,6 +41,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Audio.md

@@ -48,6 +48,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
@@ -132,4 +133,4 @@ const track = Audio({
 - **Next:** [Video](Video.md)
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 7 · Media and drag & drop** (1 of 4).
+You are reading **Chapter 7 · Media and drag & drop** (1 of 5).

package/docs/widget/Avatar.md

@@ -1,6 +1,6 @@
 # Avatar
 
-A compact identity chip that shows a profile image, the person's initials, or a fallback icon. It falls back gracefully when no image is available.
+A compact identity chip that shows a profile image, the person's initials, or a fallback icon. It falls back gracefully when no image is available and can carry a presence dot.
 
 ## When to use it
 
@@ -29,6 +29,8 @@ const user = Avatar({
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
 | `textColor` | `Color` | Color of the button label. |
 | `shape` | `'circle' \| 'rounded' \| 'square'` | The `shape` value for the widget. |
+| `online` | `boolean` | Shows a presence dot in the corner of the avatar. |
+| `badgeColor` | `Color` | Color of the presence dot. |
 | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
 
 ### Common props
@@ -43,6 +45,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
@@ -69,6 +72,7 @@ const user = Avatar({
   name: "Ada Lovelace",
   size: 48,
   shape: "circle",
+  online: true,
 });
 ```
 
@@ -84,14 +88,17 @@ const user = Avatar({
   shape: "rounded",
   bgColor: "#2563eb",
   textColor: "#ffffff",
+  online: true,
+  badgeColor: "#f59e0b",
   onPress: () => console.log("open profile"),
 });
 ```
 
 ## Tips
 
-- Provide both src and name so initials render if the image fails.
+- Provide both src and name so the initials are ready if you swap the image out.
 - Use shape: "circle" for people and shape: "rounded" for organizations or bots.
+- Leave badgeColor at its default for an available dot; pass another color to signal away or busy.
 
 ## Accessibility
 
@@ -99,8 +106,10 @@ const user = Avatar({
 
 ## Behavior
 
-- When src is missing or errors, the widget automatically shows initials from name.
+- Content is picked once, in order: src, then icon, then initials from name, then a generic person icon. A failing src does not swap the image for initials by itself.
 - onPress makes the whole avatar interactive, which is useful for opening profiles.
+- online draws a dot in the bottom-right corner. It sits inside the edge and is sized from the avatar, so a circular avatar clips it no more than a square one.
+- Every own prop applies again through update() or updateContent(), so an avatar bound to a state key changes without rebuilding the element.
 
 ## Related widgets
 

package/docs/widget/Badge.md

@@ -47,6 +47,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Button.md

@@ -54,6 +54,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Card.md

@@ -45,6 +45,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Carousel.md

@@ -54,6 +54,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Chart.md

@@ -60,6 +60,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Checkbox.md

@@ -41,6 +41,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Chip.md

@@ -47,6 +47,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/CircularBar.md

@@ -72,6 +72,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/CircularChart.md

@@ -67,6 +67,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/CodeViewer.md

@@ -47,6 +47,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Column.md

@@ -44,6 +44,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Container.md

@@ -51,6 +51,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/DataTable.md

@@ -55,6 +55,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Divider.md

@@ -37,6 +37,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/DraggBox.md

@@ -46,6 +46,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
@@ -122,8 +123,8 @@ const task = DraggBox({
 
 ## Continue reading
 
-- **Previous:** [Video](Video.md)
+- **Previous:** [Maps](Maps.md)
 - **Next:** [DroppBox](DroppBox.md)
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 7 · Media and drag & drop** (3 of 4).
+You are reading **Chapter 7 · Media and drag & drop** (4 of 5).

package/docs/widget/Dropdown.md

@@ -53,6 +53,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
@@ -112,6 +113,7 @@ const country = Dropdown({
 
 - Pass objects with value/label when the value sent to onChange must differ from the text shown, such as an id versus a name.
 - Set clearable: true to give users an explicit way back to no selection.
+- Bind a useState value to `value` to move the selection from code, such as auto-picking a default after a lookup; pass `''` to clear it back to the placeholder.
 
 ## Accessibility
 
@@ -121,6 +123,7 @@ const country = Dropdown({
 
 - The option menu is portaled to document.body by default and repositions on scroll/resize; set portal: false to keep it inline.
 - The returned element exposes value, open(), close() and update(), and removes its listeners on unmount.
+- A value applied from outside — a bound state change or `dropdown.value = x` — re-fires onChange when it differs from the current selection, and is ignored when it is the same, so a state → value → onChange → state loop settles after one pass.
 
 ## Related widgets
 

package/docs/widget/DroppBox.md

@@ -61,6 +61,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
@@ -149,4 +150,4 @@ const zone = DroppBox({
 - **Next:** [Scaffold](Scaffold.md) — Chapter 8 · App navigation
 - **Index:** [Widget index](README.md) · [Start here](START_HERE.md)
 
-You are reading **Chapter 7 · Media and drag & drop** (4 of 4).
+You are reading **Chapter 7 · Media and drag & drop** (5 of 5).

package/docs/widget/FloatingActionButton.md

@@ -45,6 +45,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/GridView.md

@@ -54,6 +54,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Icon.md

@@ -39,6 +39,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/Image.md

@@ -1,6 +1,6 @@
 # Image
 
-Renders an image element from a URL or path. Supports fixed sizing, object-fit modes, and a circular crop for avatars.
+Renders an image element from a URL or path. Supports fixed sizing, object-fit modes, a circular crop for avatars, and saving on click.
 
 ## When to use it
 
@@ -29,6 +29,8 @@ const photo = Image({
 | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
 | `fit` | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | How the image fits its box (CSS `object-fit`). |
 | `circular` | `boolean` | Clips the image into a circle. |
+| `downloadable` | `boolean` | Makes a click on the image save it. |
+| `downloadFileName` | `string` | File name suggested when saving; defaults to the name in the URL. |
 | `onLoad` | `(widget: Widget) => void` | Fired when the media finishes loading. |
 | `onError` | `(widget: Widget) => void` | Fired when the media fails to load. |
 | `onPress` | `(widget: Widget) => void` | Callback fired when the widget is pressed. Alias: `onClick`. |
@@ -45,6 +47,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
@@ -82,12 +85,14 @@ const cover = Image({
 import { Image } from "flet-box";
 
 const teamPhoto = Image({
-  src: "/team/anna.jpg",
+  src: "/team/anna.jpg?v=3",
   alt: "Anna at the keynote",
   width: 96,
   height: 96,
   fit: "cover",
   circular: true,
+  downloadable: true,
+  downloadFileName: "anna-keynote.jpg",
   onLoad: () => console.log("loaded"),
   onError: () => console.error("failed"),
   onPress: () => console.log("open profile"),
@@ -98,6 +103,7 @@ const teamPhoto = Image({
 
 - Set both width and height with fit: "cover" to avoid stretched or squashed art.
 - Use circular: true instead of a full borderRadius when you want a perfect avatar crop.
+- downloadable only saves the file when the image is same-origin or CORS-served; anything else opens in a new tab instead of replacing your app.
 
 ## Accessibility
 
@@ -106,7 +112,9 @@ const teamPhoto = Image({
 ## Behavior
 
 - onLoad fires once the image decodes; onError fires when the src fails to load.
-- onPress is attached to the wrapper, so the image behaves like a tappable tile.
+- onPress is attached to the image itself, so the image behaves like a tappable tile.
+- With downloadable: true a click saves the image under downloadFileName, or under the file name in the URL when that prop is absent.
+- Both download props stay live: update() can turn the offer on or off and rename it, and a downloadable bound to a useState key follows the store.
 
 ## Related widgets
 

package/docs/widget/Input.md

@@ -65,6 +65,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/InstallButton.md

@@ -43,6 +43,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/ListTile.md

@@ -54,6 +54,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |

package/docs/widget/ListView.md

@@ -53,6 +53,7 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `padding` | `Padding` | Space inside the widget, between its content and its border. |
 | `margin` | `Margin` | Space outside the widget, between it and its neighbors. |
 | `bgColor` | `Color` | Background color. Alias: `backgroundColor`. |
+| `backgroundColor` | `Color` | Background color. Alias of `bgColor`. |
 | `color` | `Color` | Foreground color, usually the text or icon color. |
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |