DEV-1264: Barcode dev docs — add attachScanner() (web + native)

docs/.well-known/agent-skills/fliplet-js-api/SKILL.md

@@ -55,7 +55,7 @@ The Fliplet client-side JavaScript API: every Fliplet.X namespace (Storage, User
 - [Fliplet.App.Submissions](https://developers.fliplet.com/API/fliplet-app-submissions.md): Read App Store and Google Play submission metadata for the current Fliplet app — version, status, build numbers — via the fliplet-app-submissions package.
 - [Fliplet.Media.Audio.Player](https://developers.fliplet.com/API/fliplet-audio-player.md): Embed an audio player UI in a screen by tagging HTML elements with audio URLs; the framework auto-initializes players on screen load.
 - [Fliplet.Media.Audio](https://developers.fliplet.com/API/fliplet-audio.md): Play, pause, stop, and seek audio files on device or from a URL in Fliplet apps via the Audio namespace.
-- [Fliplet.Barcode](https://developers.fliplet.com/API/fliplet-barcode.md): Generate QR codes and 1D/2D barcodes on screen, and scan them from the device camera, via the fliplet-barcode package.
+- [Fliplet.Barcode](https://developers.fliplet.com/API/fliplet-barcode.md): Scan QR codes and 1D/2D barcodes from the camera on web and native (attachScanner / scan) and generate barcode images, via the fliplet-barcode package.
 - [Fliplet.Chat](https://developers.fliplet.com/API/fliplet-chat.md): Build one-to-one, group, and public-channel chat features. Fliplet.Chat owns the conversations and messages data sources internally — supply only the contacts list (who can chat with whom).
 - [Fliplet.Communicate](https://developers.fliplet.com/API/fliplet-communicate.md): Send email, SMS, push notifications, and share URLs from a Fliplet app using a single Communicate namespace.
 - [Fliplet.Content()](https://developers.fliplet.com/API/fliplet-content.md): Create, query, update, and delete shared content records (bookmarks, likes, saved searches) backed by a data source via Fliplet.Content.
@@ -103,6 +103,7 @@ The Fliplet client-side JavaScript API: every Fliplet.X namespace (Storage, User
 - [V3 app bootstrap constraints](https://developers.fliplet.com/API/v3/app-bootstrap.md): The four constraints every V3 boot HTML must satisfy. Covers Fliplet.require.lazy for dependencies, Fliplet.Media.getContents for source files, the Fliplet().then(...) init sequence, and the locked v…
 - [V3 App Settings Convention](https://developers.fliplet.com/API/v3/app-settings.md): V3 app settings convention for storing public and private configuration. Covers the underscore prefix convention for editor-private settings.
 - [V3 Authentication Patterns](https://developers.fliplet.com/API/v3/auth.md): V3 authentication patterns for email/password login, session management, logout, and protected routes. Use these patterns when building authentication flows in V3 apps.
+- [V3 barcodes](https://developers.fliplet.com/API/v3/barcode.md): Scan and generate QR codes and barcodes in V3 apps with Fliplet.Barcode — attachScanner() to scan (web + native) and encode() to render barcode images.
 - [V3 Alpine.js apps](https://developers.fliplet.com/API/v3/frameworks/alpine.md): Constraints for building V3 apps in Alpine.js. Alpine is attribute-driven HTML with no build step, so it maps cleanly to the V3 runtime. Covers x-init timing relative to Fliplet().then and platform-c…
 - [V3 framework guide — picking and setup](https://developers.fliplet.com/API/v3/frameworks/overview.md): Picking a frontend framework for a V3 app. Lists the runtime constraints every framework must cope with (no build step, no bundler, no transpile) and compares Vue, React, Alpine, and vanilla JS again…
 - [V3 React apps](https://developers.fliplet.com/API/v3/frameworks/react.md): Constraints for building V3 apps in React. Covers the JSX transpilation problem (the #1 cause of first-deploy failures) with three alternatives, React Router 6 createHashRouter wiring (no basename —…

docs/.well-known/agent-skills/index.json

@@ -130,7 +130,7 @@
       "tags": [
         "js-api"
       ],
-      "sha256": "c07cf31ad3a44743fc7a6e656685bd8dd20f07bc92fc7a76d6899a77d0092ea5"
+      "sha256": "7d2ee408458c7970f50f21310b0be09aba835bb86c8eeca41a6227bbc4c89530"
     },
     {
       "name": "fliplet-docs-index",

docs/.well-known/llms-full.txt

@@ -12596,19 +12596,58 @@ URL: https://developers.fliplet.com/API/fliplet-barcode.md
 
 # `Fliplet.Barcode`
 
-Scan QR codes and other 1D/2D barcodes from the device camera, and generate barcode images on screen, via the `fliplet-barcode` package. Barcode scanning is only supported in native apps.
+Scan QR codes and other 1D/2D barcodes from the device camera, and generate barcode images on screen, via the `fliplet-barcode` package.
+
+The package offers two ways to scan: `attachScanner()` embeds a scanner in a container in your own UI and works on web and native, while `scan()` opens a ready-made full-screen scanner on native. Use `show()` or `encode()` to generate barcode images. Building a scanning screen in a V3 app? See the [V3 barcode scanning guide](./v3/barcode.md).
 
 ## Install
 
 Add the `fliplet-barcode` dependency to your screen or app resources.
 
+## Fliplet.Barcode.attachScanner()
+
+(Returns a controller object)
+
+`attachScanner()` is a low-level scanner with **no built-in UI**: you provide a container element (placed and styled inside your own screen or modal) and `attachScanner()` drives the camera and decoder into it. It works the same on **web and native**.
+
+### Usage
+
+```js
+// 1. Put a container in your own UI: <div id="reader"></div>
+var scanner = Fliplet.Barcode.attachScanner(document.getElementById('reader'), {
+  onScan: function (result) {
+    // result.text   — the decoded value
+    // result.format — e.g. 'QR_CODE', 'CODE_128'
+    scanner.stop(); // one-shot: stop after the first scan (or keep scanning)
+  },
+  onError: function (error) {
+    // camera permission denied, no camera, or library failed to load
+  }
+});
+
+// when the user leaves the screen or closes your scanner UI:
+scanner.stop();
+```
+
+A typical "tap a button to scan" screen shows your own button, reveals the `#reader` container when tapped, calls `attachScanner()`, and displays `result.text` on screen from inside `onScan`.
+
+* **element** (HTMLElement | String) The container to render the camera into (an element or its `id`). You own its placement and styling — `attachScanner()` neither creates nor removes it.
+* **options** (Object)
+  * **onScan** (Function) Called on every successful decode with `{ text, format }`. Call `scanner.stop()` inside it for one-shot scanning.
+  * **onError** (Function) Called on a fatal start error (camera permission denied, no camera, or library load failure).
+  * **fps** (Number) Decode attempts per second. Default `10`.
+  * **qrbox** (Object | Function) Scan-box size (html5-qrcode `qrbox`). Defaults to a centred square at 70% of the smaller edge.
+* **Returns** a controller `{ stop() }`. `stop()` ends the camera, tears down the decoder (your element is left in the DOM), and returns a `Promise`.
+
+**Permissions**: on web the browser prompts for camera access when scanning starts and requires a secure context (HTTPS). On native the OS prompts on first use.
+
 ## Fliplet.Barcode.scan()
 
 (Returns `Promise`)
 
-Scan a QR code or barcode.
+Open a ready-made full-screen scanner and resolve with the result. This is a convenience shortcut for a quick, standalone scan where you do not need the scanner embedded in your own screen.
 
-**Note**: Barcode scanning is only supported in native apps.
+**Note**: `scan()` is only supported in native apps. For scanning that also works on the web, use [`attachScanner()`](#fliplet-barcode-attachscanner).
 
 ### Usage
 
@@ -27847,6 +27886,195 @@ var session = await Fliplet.User.getCachedSession();
 
 ---
 
+# V3 barcodes
+URL: https://developers.fliplet.com/API/v3/barcode.md
+
+# V3 barcodes
+
+The `fliplet-barcode` package does two things in a V3 app, both the same on **web and native**: it **scans** QR codes and barcodes with `Fliplet.Barcode.attachScanner()`, and it **generates** QR code and barcode images with `Fliplet.Barcode.encode()`.
+
+Scanning uses `attachScanner()` — a UI-less scanner you drive into a container element inside your own screen. It runs everywhere a V3 app runs (slug-hosted web, the Studio preview, and the native shell). You build the scanning UI yourself, the same way you build a login screen on top of `Fliplet.Session`; the API owns only the camera and the decoder.
+
+This guide covers the recommended embedded-scanner pattern, a full worked example, the controller and options, camera permissions, and generating barcode images.
+
+## Prerequisites
+
+Add the `fliplet-barcode` package to the screen, then load it before use:
+
+```js
+await Fliplet.require.lazy.chain('fliplet-barcode');
+```
+
+Once the package is loaded, `Fliplet.Barcode` exposes two methods, both of which work the same on **web and native**: `attachScanner()` (scan, documented below) and `encode()` (generate a QR code or barcode image, documented under [Generating barcodes](#generating-barcodes)).
+
+## The recommended pattern: attachScanner()
+
+`attachScanner()` has **no built-in UI**. You place and style a container element; `attachScanner()` runs the camera and decoder into it and calls you back on each successful decode. Because there is no platform-specific overlay, the same code works on web and native.
+
+```js
+// Your screen owns this element and its styling:
+// <div id="reader" style="width: 100%; max-width: 320px; aspect-ratio: 1;"></div>
+
+const scanner = Fliplet.Barcode.attachScanner(document.getElementById('reader'), {
+  onScan(result) {
+    // result.text   — the decoded value, e.g. "https://example.com" or "5012345678900"
+    // result.format — the symbology, e.g. "QR_CODE", "CODE_128", "EAN_13"
+    scanner.stop(); // one-shot: stop after the first hit (omit to keep scanning)
+    showResult(result.text);
+  },
+  onError(error) {
+    // Fatal start error: camera permission denied, no camera, or library load failure.
+    showMessage('Could not start the scanner. Check camera permissions and try again.');
+  }
+});
+
+// Stop the camera when the user leaves the screen or closes your scanner UI:
+scanner.stop();
+```
+
+### Worked example: tap a button to scan
+
+A typical scanning screen keeps the viewfinder hidden until the user asks for it, scans once, then shows the result. This is the whole flow in vanilla JS:
+
+```html
+<button id="scan-btn">Scan a barcode</button>
+<div id="reader" hidden style="width: 100%; max-width: 320px; aspect-ratio: 1; margin-top: 16px;"></div>
+<p id="result"></p>
+```
+
+```js
+await Fliplet.require.lazy.chain('fliplet-barcode');
+
+const btn = document.getElementById('scan-btn');
+const reader = document.getElementById('reader');
+const resultEl = document.getElementById('result');
+let scanner = null;
+
+btn.addEventListener('click', function () {
+  reader.hidden = false;
+  scanner = Fliplet.Barcode.attachScanner(reader, {
+    onScan(result) {
+      resultEl.textContent = `${result.format}: ${result.text}`;
+      scanner.stop();
+      reader.hidden = true;
+    },
+    onError() {
+      resultEl.textContent = 'Camera unavailable — check permissions.';
+      reader.hidden = true;
+    }
+  });
+});
+```
+
+### Vue component
+
+In a V3 Vue screen, start the scanner from a button handler and always stop it on unmount so the camera is released:
+
+```js
+// Scanner.vue (runtime template — V3 single-file components run without a build step)
+export default {
+  data() {
+    return { value: '', scanner: null };
+  },
+  methods: {
+    async start() {
+      await Fliplet.require.lazy.chain('fliplet-barcode');
+      this.scanner = Fliplet.Barcode.attachScanner(this.$refs.reader, {
+        onScan: (result) => {
+          this.value = result.text;
+          this.scanner.stop();
+        },
+        onError: () => { this.value = 'Camera unavailable.'; }
+      });
+    }
+  },
+  beforeUnmount() {
+    if (this.scanner) {
+      this.scanner.stop();
+    }
+  },
+  template: `
+    <div>
+      <button @click="start">Scan</button>
+      <div ref="reader" style="width: 100%; max-width: 320px; aspect-ratio: 1;"></div>
+      <p v-if="value">{{ value }}</p>
+    </div>
+  `
+};
+```
+
+## Controller and options
+
+`attachScanner(element, options)` returns a controller and accepts:
+
+* **element** (HTMLElement | String) — the container to render the camera into (an element or its `id`). You own its placement and styling; `attachScanner()` neither creates nor removes it.
+* **options.onScan** (Function) — called on every successful decode with `{ text, format }`. Call `controller.stop()` inside it for one-shot scanning.
+* **options.onError** (Function) — called on a fatal start error (permission denied, no camera, or library load failure). Per-frame decode misses are *not* errors and are ignored.
+* **options.fps** (Number) — decode attempts per second. Default `10`.
+* **options.qrbox** (Object | Function) — scan-box size. Defaults to a centered square at 70% of the smaller edge.
+
+The controller is `{ stop() }`. `stop()` ends the camera, tears down the decoder (your element stays in the DOM), and returns a `Promise`.
+
+## Camera permissions
+
+* **Web** — the browser prompts for camera access when scanning starts, and `getUserMedia` requires a secure context (HTTPS). In the Studio preview the app runs in an iframe that already delegates `camera`; a published slug is served over HTTPS.
+* **Native** — the OS prompts on first use.
+
+Handle a denied permission in `onError` — show the user how to re-enable the camera rather than leaving an empty viewfinder.
+
+## Generating barcodes
+
+To render a QR code or barcode image, use `Fliplet.Barcode.encode()`. It works on web and native, returns the image as a Base64 string, and defaults to a QR code unless you pass a different `format`. You place the returned image in your own UI — the same "you own the UI" model as `attachScanner()` — for example into an `<img>` `src`, or save it with `Fliplet.Media`.
+
+### Fliplet.Barcode.encode()
+
+Encode text into a QR code or barcode and resolve with the image as a Base64 string.
+
+```js
+await Fliplet.require.lazy.chain('fliplet-barcode');
+
+// QR code (default)
+Fliplet.Barcode.encode('https://example.com').then(function (data) {
+  document.getElementById('qr').src = data; // <img id="qr">
+});
+
+// Barcode with options
+Fliplet.Barcode.encode('5012345678900', { format: 'ean13' }).then(function (data) {
+  document.getElementById('code').src = data;
+});
+```
+
+* **text** (String) — the value to encode.
+* **options** (Object)
+  * **format** (String) — `qr` (**default**), or `barcode` (encodes as `code128`), or a specific symbology: `code39`, `code128`, `code128A`, `code128B`, `code128C`, `ean13`, `ean8`, `ean5`, `ean2`, `upc`, `upce`, `itf14`, `itf`, `msi`, `msi10`, `msi11`, `msi1010`, `msi1110`, `pharmacode`, `codabar`, `genericbarcode`.
+  * **color** (String) — foreground color, keyword (`green`) or hex (`#00ff00`). **Default** `#000000`.
+  * **background** (String) — background color, keyword or hex. **Default** `#ffffff`.
+  * **width** (Number) — **QR code only.** Width of the QR image. **Default** `600`. (Barcode width is driven by the text length and `lineWidth`.)
+  * **height** (Number) — height of the image. **Default** `600` for QR, `150` for barcode.
+  * **lineWidth** (Number) — **barcode only.** Width of a single bar; larger values produce a wider image. **Default** `2`.
+
+> **Tip:** QR codes are always 1:1, so they scale cleanly. Prefer a QR code unless a linear barcode is specifically required; for barcodes, tune `height` and `lineWidth` to the length of the encoded text. `encode()` returns the raw image and renders no UI of its own — display it however your screen needs.
+
+## Patterns — DO and DON'T
+
+**DO**
+
+- Build your own scanning UI (button, viewfinder container, result area) and drive `attachScanner()` into it.
+- Call `controller.stop()` after the first scan for one-shot flows, and on screen teardown/unmount to release the camera.
+- Handle `onError` with a user-facing message about camera permissions.
+- Give the container an explicit size — the camera fills it.
+
+**DON'T**
+
+- Don't leave the scanner running after navigation — a live camera drains battery and blocks other capture.
+- Don't add a separate "scanner" package or a custom camera/getUserMedia stack — `attachScanner()` is the supported cross-platform scanner.
+
+## Related
+
+- [V3 routing](./routing.md) — base-path and navigation patterns for the screen that hosts your scanner.
+
+---
+
 # V3 Alpine.js apps
 URL: https://developers.fliplet.com/API/v3/frameworks/alpine.md
 
@@ -40418,7 +40646,7 @@ Every Fliplet JS API available to V3 apps, grouped by capability category. Each
 
 ## Media
 
-- [`Fliplet.Barcode`](https://developers.fliplet.com/API/fliplet-barcode.html) — Generate QR codes and 1D/2D barcodes on screen, and scan them from the device camera, via the fliplet-barcode package.
+- [`Fliplet.Barcode`](https://developers.fliplet.com/API/v3/barcode.html) — Scan and generate QR codes and barcodes in V3 apps with Fliplet.Barcode — attachScanner() to scan (web + native) and show()/encode() to render barcode images.
 - [`Fliplet.Media`](https://developers.fliplet.com/API/fliplet-media.html) — Browse folders, upload and manage files, and download media to devices via the Fliplet Media namespace.
 - [`Fliplet.Media.Audio`](https://developers.fliplet.com/API/fliplet-audio.html) — Play, pause, stop, and seek audio files on device or from a URL in Fliplet apps via the Audio namespace.
 

docs/.well-known/llms-v3-libraries.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-06-10T17:50:12.068Z",
+  "generatedAt": "2026-06-17T10:20:55.308Z",
   "libraries": [
     {
       "package": "fliplet-analytics-spa",
@@ -61,9 +61,9 @@
     {
       "package": "fliplet-barcode",
       "namespace": "Fliplet.Barcode",
-      "title": "Fliplet.Barcode",
-      "description": "Generate QR codes and 1D/2D barcodes on screen, and scan them from the device camera, via the fliplet-barcode package.",
-      "docUrl": "https://developers.fliplet.com/API/fliplet-barcode.md",
+      "title": "V3 barcodes",
+      "description": "Scan and generate QR codes and barcodes in V3 apps with Fliplet.Barcode — attachScanner() to scan (web + native) and encode() to render barcode images.",
+      "docUrl": "https://developers.fliplet.com/API/v3/barcode.md",
       "preloaded": false,
       "capabilities": [
         "barcode",