flet-box 1.1.0 → 1.1.2

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/colors.js

@@ -173,9 +173,6 @@ export const panel = (title, subtitle = "", { minW = 62 } = {}) => {
 export const banner = (title, subtitle = "", opts = {}) =>
   panel(title, subtitle, opts);
 
-export const badge = (icon, text, color = "brightCyan") =>
-  `  ${c(color, icon + " " + text)}`;
-
 // Status dot (green by default, red/amber for failures/warnings)
 export const dot = (color = "#34d399") => hex("●", color);
 
@@ -207,9 +204,4 @@ export const setupCtrlC = () => {
     console.log(`\n\n${rainbow("👋 Bye!")}\n`);
     process.exit(0);
   });
-};
-
-// Show help message for Ctrl+C
-export const showExitHint = () => {
-  console.log(`${c("gray", "Press Ctrl+C to exit")}`);
 };

package/bin/utils/helpers.js

@@ -73,8 +73,3 @@ export const execCmd = (cmd) => {
     return false;
   }
 };
-
-// Fixed: Now returns actual package path
-export const getPackagePath = () => {
-  return path.join(process.cwd(), "node_modules", "flet-box");
-};

package/bin/utils/images/jpeg.js

@@ -338,7 +338,7 @@ export const decodeJpeg = (buf) => {
 const decodeScan = (scan, ctx) => {
   const { buf, components, width, height, maxH, maxV, block, scratch } = ctx;
   const { restartInterval, tables: { quant, dc, ac } } = scan;
-  const specs = readScanHeader(scan.payload, components.length);
+  const specs = readScanHeader(scan.payload);
   if (specs.length !== components.length && specs.length !== 1) {
     throw new Error(`JPEG scan covers ${specs.length} of ${components.length} components, which is neither interleaved nor single-component`);
   }
@@ -558,11 +558,10 @@ const readDht = (payload, dc, ac) => {
  * scan.
  *
  * @param {Buffer} payload
- * @param {number} componentCount
  * @returns {{ id: number, tables: number }[]} Component specifiers, in scan order.
  * @throws {UnsupportedImage} For a progressive or refined scan.
  */
-const readScanHeader = (payload, componentCount) => {
+const readScanHeader = (payload) => {
   const count = payload[0];
   if (payload.length < 4 + count * 2) throw new Error("JPEG scan header is truncated");
   const specs = [];

package/bin/utils/templates.js

@@ -709,54 +709,6 @@ echo "Press Ctrl+C to stop"
 python3 -m http.server $PORT --bind $BIND
 `;
 
-export const createBundleSh = (target = "www") => `#!/bin/bash
-# createBundle.sh — Bundle UNIFICADO a \${TARGET}/ (un solo app.js + PWA)
-# Uso: bash createBundle.sh [target]
-set -euo pipefail
-cd "\$(dirname "\$0")"
-TARGET="\${1:-${target}}"
-
-if ! npx --no-install esbuild --version >/dev/null 2>&1; then
-    echo "📦 Instalando esbuild (devDependency)…"
-    npm install --save-dev esbuild >/dev/null
-fi
-
-rm -rf "\$TARGET"
-mkdir -p "\$TARGET/src" "\$TARGET/assets"
-
-# Root static files (PWA + preview)
-for f in index.html manifest.json run.sh service-worker.js; do
-    [ -f "\$f" ] && cp "\$f" "\$TARGET/"
-done
-[ -f "\$TARGET/run.sh" ] && chmod +x "\$TARGET/run.sh"
-
-# Assets: iconos PWA + fuentes de iconos
-if [ -d "src/assets" ]; then
-    cp -R src/assets/. "\$TARGET/src/assets/"
-    cp -R src/assets/. "\$TARGET/assets/"
-fi
-
-# CSS global (lo carga index.html)
-if [ -f "src/styles/global.css" ]; then
-    mkdir -p "\$TARGET/src/styles"
-    cp src/styles/global.css "\$TARGET/src/styles/"
-fi
-
-# BUNDLE UNIFICADO: flet-box + widgets en UN solo app.js
-echo "📦 Bundling (esbuild + tree-shaking)…"
-npx esbuild src/app.js \\
-    --bundle --outfile="\$TARGET/src/app.js" --format=esm --minify \\
-    --tree-shaking=true --target=es2020 --define:FLETBOX_DEV=false \\
-    --external:*.css --external:*.woff2 --resolve-extensions=.js,.json
-
-# App source code (required by the "View code" button)
-for d in modules screens database components; do
-    [ -d "src/\$d" ] && cp -R "src/\$d" "\$TARGET/src/"
-done
-
-echo "✅ Bundle listo: \$TARGET/   Prueba: cd \$TARGET && bash run.sh"
-`;
-
 export const serviceWorkerJs = () => `// service-worker.js - PWA offline support
 const CACHE_NAME = 'fletbox-v2';
 // Deployment prefix: a worker's own URL always sits at the app root, so this
@@ -879,6 +831,28 @@ self.addEventListener('fetch', event => {
 });
 `;
 
+// Not TypeScript: an editor reads this file and runs its bundled JS language
+// service over `flet-box`'s own .d.ts, so a prop autocompletes and a prop that
+// does not exist is a squiggle. `bundler` is the resolution an unbundled-ESM
+// app needs, and TypeScript 7 removed `node10` outright — an older editor that
+// still only knows `node` ignores the whole jsconfig, which is no worse than
+// not having one. Nothing here is compiled or installed.
+export const jsconfig = () => `{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowJs": true,
+    "checkJs": true,
+    "strict": false,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.js"],
+  "exclude": ["node_modules", "www", "dist"]
+}`;
+
 export const packageJson = (name) => `{
   "name": ${JSON.stringify(name)},
   "version": "1.0.0",
@@ -1322,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}
@@ -1663,6 +1644,15 @@ npm install
 npm run dev
 \`\`\`
 
+## Autocomplete without TypeScript
+
+\`jsconfig.json\` points the editor's own JavaScript language service at
+\`flet-box\`'s bundled \`.d.ts\` — nothing to install, nothing to compile. Every
+widget, prop, colour token and helper autocompletes in VS Code (or any editor
+that reads jsconfig), and a prop that does not exist is underlined as an error
+instead of failing silently at runtime. \`src/\` is the only folder checked;
+\`npm run check\` remains the gate that runs in CI.
+
 ## Working with an AI assistant
 
 This project ships an in-project agent contract, so an AI editing the app uses the
@@ -1796,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
@@ -1888,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
@@ -2066,7 +2060,7 @@ import { AppBar, Icon, Tooltip, colors, openDrawer, toggleTheme, getTheme } from
 // It reads the theme instead of subscribing to it: setTheme() re-renders the app,
 // so a component that subscribed would add a listener on every render and never
 // remove it.
-export const AppBarComponent = ({ title, isMobile = false, showBack = false, onBack }) => {
+export const AppBarComponent = ({ title, isMobile = false, showBack = false, onBack = () => {} }) => {
     const isDark = getTheme() === 'dark';
 
     return AppBar({
@@ -2244,7 +2238,7 @@ runApp(App, 'root');
 `;
 
 export const basicAppJs = () => `// app.js - Basic template (AppBar + Drawer)
-import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+import { runApp, Scaffold, colors, useState, atLeast, onBreakpointChange } from 'flet-box';
 // Registers this app's design tokens. Without it every screen paints
 // with the framework's own palette, and the file that looks like the design
 // system is decoration.
@@ -2264,13 +2258,14 @@ const routes = {
 };
 
 // The drawer is only reachable through the AppBar's menu button, so the shell has
-// to know whether it is on a phone. Key-based state keeps the width across
-// re-renders; the resize listener is registered once, at module scope.
-const [viewportWidth, setViewportWidth] = useState('viewportWidth', dimensions.getWidth());
-dimensions.addListener(({ width }) => setViewportWidth(width));
+// to know whether it is on a phone. Key-based state keeps the answer across
+// re-renders; the subscription is registered once, at module scope, and only
+// fires when the viewport crosses a breakpoint, not on every pixel of a resize.
+const [isWide, setIsWide] = useState('isWide', atLeast('md'));
+onBreakpointChange(() => setIsWide(atLeast('md')));
 
 const MyApp = () => {
-    const isMobile = viewportWidth.valueOf() < 768;
+    const isMobile = !isWide.valueOf();
     return Scaffold({
         routes,
         appBar: AppBarComponent({ title: 'FletBox', isMobile }),
@@ -2284,7 +2279,7 @@ runApp(MyApp, 'root');
 
 export const fullAppJs =
   () => `// app.js - Full template (AppBar + Drawer + BottomNav)
-import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+import { runApp, Scaffold, colors, useState, atLeast, onBreakpointChange } from 'flet-box';
 // Registers this app's design tokens. Without it every screen paints
 // with the framework's own palette, and the file that looks like the design
 // system is decoration.
@@ -2304,15 +2299,15 @@ const routes = {
     '/about': AboutScreen
 };
 
-// State is key-based, so the viewport width survives re-renders. One resize
+// State is key-based, so the layout answer survives re-renders. One breakpoint
 // subscription feeds it from module scope: registering it inside the component
-// would add a listener on every render.
-const [viewportWidth, setViewportWidth] = useState('viewportWidth', dimensions.getWidth());
-dimensions.addListener(({ width }) => setViewportWidth(width));
+// would add a listener on every render, and it only fires when a step is crossed.
+const [isWide, setIsWide] = useState('isWide', atLeast('md'));
+onBreakpointChange(() => setIsWide(atLeast('md')));
 
 const MyApp = () => {
     // Structural read of the key, so crossing the breakpoint re-renders the shell.
-    const isMobile = viewportWidth.valueOf() < 768;
+    const isMobile = !isWide.valueOf();
     return Scaffold({
         routes,
         appBar: AppBarComponent({ title: 'FletBox', isMobile }),
@@ -2357,7 +2352,7 @@ runApp(MyApp, 'root');
 
 export const adaptiveAppJs =
   () => `// app.js - Adaptive template (mobile + desktop)
-import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+import { runApp, Scaffold, colors, useState, atLeast, onBreakpointChange } from 'flet-box';
 // Registers this app's design tokens. Without it every screen paints
 // with the framework's own palette, and the file that looks like the design
 // system is decoration.
@@ -2380,11 +2375,11 @@ const routes = {
     '/profile': ProfileScreen
 };
 
-// State is key-based, so the viewport width survives re-renders. The resize
+// State is key-based, so the layout answer survives re-renders. The breakpoint
 // subscription is registered once at module scope; doing it inside the component
 // would add another listener on every render.
-const [viewportWidth, setViewportWidth] = useState('viewportWidth', dimensions.getWidth());
-dimensions.addListener(({ width }) => setViewportWidth(width));
+const [isWide, setIsWide] = useState('isWide', atLeast('md'));
+onBreakpointChange(() => setIsWide(atLeast('md')));
 
 // One menu, three surfaces: the drawer and the bottom bar on a phone, the
 // sidebar on a desktop. The labels stay short because the bottom bar has to fit
@@ -2397,9 +2392,9 @@ const menu = [
 ];
 
 const MyApp = () => {
-    // Structural read of the keyed viewport state, so crossing the breakpoint
+    // Structural read of the keyed layout state, so crossing the breakpoint
     // re-renders the shell (drawer + bottom bar <-> sidebar).
-    const isMobile = viewportWidth.valueOf() < 768;
+    const isMobile = !isWide.valueOf();
     return Scaffold({
         routes,
         appBar: AppBarComponent({ title: 'FletBox', isMobile }),
@@ -2547,9 +2542,13 @@ export const agentsMd = (appName, template, version) =>
     'Real `Scaffold` props: `appBar body bottomBar fab drawer leftNavBar',
     'leftNavBarWidth rightNavBar rightNavBarWidth routes basePath backgroundColor',
     'closeDrawerOnNavigate`. (`--props Scaffold` is authoritative.)',
-    'For a responsive app, branch in JS on the keyed viewport state — `useState`',
-    'seeded from `dimensions.getWidth()` plus one `dimensions.addListener()` at',
-    'module scope — not on CSS alone. See `src/app.js` in this project.',
+    'For a responsive app, branch in JS on the breakpoint table, not on CSS alone:',
+    '`useState` seeded from `atLeast("md")` plus one `onBreakpointChange()` at',
+    'module scope — it fires when the viewport crosses a step, not on every pixel',
+    'of a resize. `md` is 768, the same line `AdaptiveScaffold` crosses, so a',
+    'screen and its shell cannot disagree. A number that really wants to be',
+    'different at 400px and 1400px comes from `pick({ xs: 16, md: 24 })`.',
+    'See `src/app.js` in this project.',
     '',
     'Custom widgets follow the same shape every framework widget uses',
     '(`QRCode.js` is the reference):',
@@ -2566,8 +2565,25 @@ export const agentsMd = (appName, template, version) =>
     '  idempotent `onUnmount` disposer. Never monkey-patch `_cleanup`.',
     '- State is key-based: `useState("key", 0)` plus subscribers. There is no',
     '  component re-render tree to reason about.',
-    '- Reuse the framework utilities (`colors`, `margin`, `padding`, `gradient',
-    '  shadow`, `rgba`, `stackPosition`) instead of hand-writing CSS.',
+    '- The package exports 123 helpers next to the widgets and they are the short',
+    '  form of the code you would otherwise write: `mapList` (an array, a number or',
+    "  an object), `createList`, `range`, `repeat`, `sort`, `unique`, `chunk`,",
+    '  `shadow`, `gradient`, `rgba`, `transform`, `transition`, `filter` (a CSS',
+    '  filter, not a list filter), `color(hex).darken(12).hex()`, `random.*`,',
+    '  `shortId`, `uuid`, `formatDate`, `formatTimeAmPm`, `relativeTime`, `timeAgo`,',
+    '  `addDays`, `subtractDays`, `dateDiff`, `dayOfWeek`, `isWeekend`, `today`,',
+    '  `seconds`, `days`, `parseDate`, `timer`, `every`, `everySecond`, `waitUntil`,',
+    '  `split`, `join`, `trim`, `startsWith`, `endsWith`, `includes`,',
+    '  `delay`, `withMinDelay`,',
+    '  `retry`, `memo`, `dict`, `print`, `ref`, `atLeast`, `pick`,',
+    '  `onBreakpointChange`, `loadFont`, `clipboard`. Hand-write the long version',
+    '  only when it is genuinely shorter or clearer. `npm run check -- --list`',
+    '  prints the set for the version actually installed.',
+    '  The trap: a routed prop already IS the short form. `padding: 16` reaches the',
+    '  rem contract; `padding(16)` returns a pixel string. Use the helpers for a',
+    '  CSS value a prop cannot express, never instead of a number.',
+    '  Second trap: `months(1)` is 30 days and `years(1)` is 365, and `addDays`',
+    '  counts calendar days while `addHours` counts real elapsed ones.',
     '',
     'One rendering engine exists: `src/widget-factory/`. Never add a second one, and',
     'never style by reaching around the factory. **If you believe the engine is',
@@ -2625,7 +2641,7 @@ export const agentsMd = (appName, template, version) =>
     '         40  ·  the smallest tap target, a roomy control',
     '         48  ·  hero spacing',
     '         64 / 96  ·  a full-bleed section, a landing hero',
-    'radius     4 / 8 / 12 / 16 / 999 (pill)',
+    'radius     4 / 8 / 12 / 16 / 20 / 24 / 999 (pill)',
     'type      12 caption · 14 body-small · 16 body · 18 subtitle · 24 title',
     '          32 headline · 40 / 48 display (a hero, a big number)',
     'weight    400 body · 500 label · 600 title · 700 headline',

package/docs/README.md

@@ -17,6 +17,7 @@ This documentation is one continuous book. Start at **Chapter 0** and follow the
 | 10 | [Tools & Utilities](tools/README.md) | The helper functions that ship with the framework | Intermediate |
 | 11 | [The CLI](cli/README.md) | Create, run, and build projects with `flet-box` | Intermediate |
 | 12 | [Clean UI](guides/clean-ui.md) | The four skills every app ships with, the design system they hold, and the gate that enforces it | Intermediate |
+| 13 | [Accessibility](guides/accessibility.md) | The focus ring, the keyboard pass over every press, the roles the widgets declare, and the overlays that hold the keyboard | Intermediate |
 | A | [Appendices](guides/minification-and-protection.md) | Minification, mobile, compatibility, embedding, online updates (OTA) | Advanced |
 
 > **Levels.** *Beginner:* start here and read in order. *Intermediate:* continue in order — you are comfortable with widgets. *Advanced:* for when you ship, skip on a first read.
@@ -54,6 +55,7 @@ Front cover (this page)
 → Utilities guide · guides/utilities.md
 → The CLI · cli/README.md
 → Clean UI · guides/clean-ui.md
+→ Accessibility · guides/accessibility.md
 → Appendices (minification → mobile → compatibility → embedding → online updates)
 → The end of the book
 ```
@@ -69,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
@@ -275,6 +291,7 @@ A typical generated project looks like this:
 ```text
 my-app/
 ├── index.html
+├── jsconfig.json
 ├── package.json
 ├── capacitor.config.json
 ├── manifest.json
@@ -301,7 +318,23 @@ my-app/
 
 The exact folders depend on the selected template.
 
-## A complete beginner workflow
+### Autocomplete without TypeScript
+
+`jsconfig.json` is not a build step: it tells the editor's own JavaScript
+language service to read `flet-box`'s bundled `src/index.d.ts`. With `checkJs`
+on, VS Code, Cursor and any editor that understands `jsconfig.json` autocomplete
+every widget, prop, colour token and helper — and underline a prop that does not
+exist, which is the same error `npm run check` reports from the command line.
+
+Nothing is installed and nothing is compiled. The framework keeps the promise
+honest with `scripts/check-app-types.mjs`, which creates all five templates and
+requires zero diagnostics over their `src/` — a starter that produces red
+squiggles fails `npm test`.
+
+```bash
+npm run check   # the gate: real API, real props, real imports
+```
+
 
 ```bash
 # 1. Create the project
@@ -619,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/README.md

@@ -11,8 +11,11 @@ This directory is the **conceptual index** of FletBox: how to build apps, set up
 - **[FletBox utilities](utilities.md)** — Chapter 10 · layout/theme/format helpers and validator tools.
 - **[The CLI](../cli/README.md)** — Chapter 11 · create, run, and build projects with `flet-box`.
 - **[Clean UI](clean-ui.md)** — Chapter 12 · the four skills `flet-box create`
-  installs, the token scale, the 25 rules, and the `flet-box check-ui` gate that
-  enforces them.
+  installs, the token scale, the numbered rules (00–24 enforced, 25–37 the
+  visual atlas), and the `flet-box check-ui` gate that enforces them.
+- **[Accessibility](accessibility.md)** — Chapter 13 · the focus ring, the
+  keyboard pass over every press, the roles and states the widgets declare, and
+  the overlays that hold the keyboard.
 - **[Widget structure](widget-structure.md)** — the canonical, modular shape every widget follows (and how new ones are added).
 
 ## Appendices (Advanced — for shipping)