k-qr-scanner 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/CHANGELOG.md +22 -1
  2. package/README.md +38 -10
  3. package/dist/chunks/chunk-PUUIGXID.js +149 -0
  4. package/dist/chunks/engine-EJ4OC3LZ.js +1 -0
  5. package/dist/cli.js +22 -9
  6. package/dist/element.d.ts +11 -1
  7. package/dist/emv.d.ts +89 -0
  8. package/dist/engine.d.ts +5 -0
  9. package/dist/index.cjs +24 -10
  10. package/dist/index.d.ts +2 -0
  11. package/dist/index.js +1 -2
  12. package/dist/kqrcode.engine.js +1 -1
  13. package/dist/kqrcode.global.js +24 -10
  14. package/dist/kqrcode.jsqr.js +0 -1
  15. package/dist/react-native.d.ts +4 -0
  16. package/dist/react.cjs +1 -2
  17. package/dist/react.d.ts +2 -0
  18. package/dist/react.js +1 -2
  19. package/dist/rn/index.js +5 -6
  20. package/dist/rn/runtime.js +1 -1
  21. package/dist/scan-qr.d.ts +2 -0
  22. package/dist/sr.cjs +0 -1
  23. package/dist/sr.js +1 -2
  24. package/dist/svelte.cjs +1 -2
  25. package/dist/svelte.d.ts +2 -0
  26. package/dist/svelte.js +1 -2
  27. package/dist/vue.cjs +1 -2
  28. package/dist/vue.d.ts +2 -0
  29. package/dist/vue.js +1 -2
  30. package/llms.txt +15 -8
  31. package/package.json +2 -3
  32. package/dist/chunks/chunk-E66QYIQI.js +0 -135
  33. package/dist/chunks/chunk-E66QYIQI.js.map +0 -6
  34. package/dist/chunks/chunk-HCGRA6GM.js +0 -2
  35. package/dist/chunks/chunk-HCGRA6GM.js.map +0 -6
  36. package/dist/chunks/decoder-jsqr-54X2IQSI.js +0 -2
  37. package/dist/chunks/decoder-jsqr-54X2IQSI.js.map +0 -6
  38. package/dist/chunks/engine-QWSAAVKN.js +0 -2
  39. package/dist/chunks/engine-QWSAAVKN.js.map +0 -6
  40. package/dist/chunks/worker-source.generated-24WX42PC.js +0 -2
  41. package/dist/chunks/worker-source.generated-24WX42PC.js.map +0 -6
  42. package/dist/cli.d.ts +0 -17
  43. package/dist/decoder-jsqr.d.ts +0 -3
  44. package/dist/decoder-zxing.d.ts +0 -3
  45. package/dist/engine-host.d.ts +0 -48
  46. package/dist/engine.cjs +0 -1
  47. package/dist/index.cjs.map +0 -6
  48. package/dist/index.js.map +0 -6
  49. package/dist/jsqr.cjs +0 -2
  50. package/dist/jsqr.cjs.map +0 -6
  51. package/dist/kqrcode.global.js.map +0 -6
  52. package/dist/kqrcode.jsqr.js.map +0 -6
  53. package/dist/react.cjs.map +0 -6
  54. package/dist/react.js.map +0 -6
  55. package/dist/rn/index.js.map +0 -6
  56. package/dist/rn-bridge.d.ts +0 -103
  57. package/dist/rn-runtime.generated.d.ts +0 -2
  58. package/dist/sr-model.generated.d.ts +0 -4
  59. package/dist/sr.cjs.map +0 -6
  60. package/dist/sr.js.map +0 -6
  61. package/dist/svelte.cjs.map +0 -6
  62. package/dist/svelte.js.map +0 -6
  63. package/dist/vue.cjs.map +0 -6
  64. package/dist/vue.js.map +0 -6
  65. package/dist/worker-source.generated.d.ts +0 -2
  66. package/dist/worker.d.ts +0 -1
  67. package/docs/API.md +0 -292
  68. package/docs/BENCHMARK.md +0 -101
  69. package/docs/CUSTOMIZE.md +0 -150
  70. package/docs/FRAMEWORKS.md +0 -241
  71. package/docs/REACT_NATIVE.md +0 -181
  72. package/docs/TESTING.md +0 -90
@@ -1,241 +0,0 @@
1
- # Frameworks
2
-
3
- The quickest start in any project is:
4
-
5
- ```bash
6
- npx k-qr-scanner init
7
- ```
8
-
9
- It detects the framework and writes a component like the ones below.
10
-
11
- The scanner is a standard custom element, `<kqr-scanner>`, so it works anywhere the DOM does. React, Vue and Svelte get small wrappers on top of it, and React Native gets its own component. Every entry point can be imported during server-side rendering: the element only activates in the browser.
12
-
13
- - [React](#react)
14
- - [Next.js](#nextjs)
15
- - [Vue](#vue)
16
- - [Nuxt](#nuxt)
17
- - [Svelte and SvelteKit](#svelte-and-sveltekit)
18
- - [Angular](#angular)
19
- - [React Native and Expo](#react-native-and-expo)
20
- - [Plain HTML](#plain-html)
21
- - [Content-Security-Policy](#content-security-policy)
22
-
23
- ## Names across frameworks
24
-
25
- Attributes become camelCase props in the wrappers:
26
-
27
- | `<kqr-scanner>` attribute | React / Vue / Svelte | default |
28
- | :--- | :--- | :--- |
29
- | `theme` | `theme` | `wechat` |
30
- | `locale` | `locale` | browser language |
31
- | `heading` | `heading` | – |
32
- | `facing` | `facing` | `environment` |
33
- | `continuous` | `continuous` | off: stop after the first code |
34
- | `inline` | `inline` | off: full screen |
35
- | `success`, `torch` | `success`, `torch` | `dot`, `auto` |
36
- | `zoom-control` | `zoomControl` | `none` |
37
- | `max-zoom` | `maxZoom` | `8` |
38
- | `super-resolution` | `superResolution` | `js` |
39
- | `formats` | `formats` (an array) | all |
40
- | `no-auto-zoom`, `no-gallery`, `no-torch`, `no-beep`, `no-vibrate`, `no-close` | `noAutoZoom`, `noGallery`, `noTorch`, `noBeep`, `noVibrate`, `noClose` | off |
41
- | property `accept` | `accept` | – |
42
- | property `labels` | `labels` | – |
43
-
44
- | element event | React / Svelte | Vue |
45
- | :--- | :--- | :--- |
46
- | `scan` | `onScan(result)` | `@scan` |
47
- | `reject` | `onReject(result, message?)` | `@reject` |
48
- | `error` | `onError(error)` | `@error` |
49
- | `close` | `onClose()` | `@close` |
50
- | `ready` | `onReady()` | `@ready` |
51
-
52
- Svelte has no `noClose`; use the `<kqr-scanner>` tag with `no-close` instead. Every option is described in [API.md](API.md).
53
-
54
- ## React
55
-
56
- ```tsx
57
- import { useState } from 'react';
58
- import { QRScanner } from 'k-qr-scanner/react';
59
-
60
- export function PayButton() {
61
- const [open, setOpen] = useState(false);
62
- return (
63
- <>
64
- <button onClick={() => setOpen(true)}>Scan to pay</button>
65
- {open && (
66
- <QRScanner
67
- locale="lo"
68
- style={{ '--kqr-accent': '#e60012' }}
69
- onScan={(r) => { setOpen(false); pay(r.text); }}
70
- onClose={() => setOpen(false)}
71
- onError={(e) => console.warn(e.code)}
72
- >
73
- <button slot="actions-left" onClick={showMyCode}>My QR code</button>
74
- </QRScanner>
75
- )}
76
- </>
77
- );
78
- }
79
- ```
80
-
81
- Mount the component to open the scanner and unmount it to close. Children with `slot="…"` go into the scanner UI ([slots](CUSTOMIZE.md#slots)). Callbacks always see your latest props, so they can use the current state.
82
-
83
- ## Next.js
84
-
85
- The React wrapper ships with `'use client'`, so you can use it straight from a server component file. To download the engine only on the page that scans, load it lazily:
86
-
87
- ```tsx
88
- // app/scan/page.tsx
89
- import dynamic from 'next/dynamic';
90
-
91
- const QRScanner = dynamic(() => import('k-qr-scanner/react').then((m) => m.QRScanner), { ssr: false });
92
-
93
- export default function Page() {
94
- return <QRScanner locale="lo" onScan={(r) => console.log(r.text)} />;
95
- }
96
- ```
97
-
98
- ## Vue
99
-
100
- ```vue
101
- <script setup lang="ts">
102
- import { ref } from 'vue';
103
- import { QRScanner } from 'k-qr-scanner/vue';
104
- import type { ScanResult } from 'k-qr-scanner';
105
-
106
- const open = ref(false);
107
- function onScan(r: ScanResult) {
108
- open.value = false;
109
- pay(r.text);
110
- }
111
- </script>
112
-
113
- <template>
114
- <button @click="open = true">Scan</button>
115
- <QRScanner v-if="open" theme="alipay" locale="zh" @scan="onScan" @close="open = false">
116
- <nav slot="footer"><b>扫码</b><span>识物</span><span>AR</span></nav>
117
- </QRScanner>
118
- </template>
119
- ```
120
-
121
- If you use the raw `<kqr-scanner>` tag in Vue templates instead of the wrapper, tell Vue it is a custom element:
122
-
123
- ```ts
124
- // vite.config.ts
125
- vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === 'kqr-scanner' } } });
126
- ```
127
-
128
- ## Nuxt
129
-
130
- Render the scanner on the client only, with `<ClientOnly>` or a `*.client.vue` component:
131
-
132
- ```vue
133
- <!-- pages/scan.vue -->
134
- <script setup lang="ts">
135
- import { QRScanner } from 'k-qr-scanner/vue';
136
- </script>
137
-
138
- <template>
139
- <ClientOnly>
140
- <QRScanner locale="lo" @scan="(r) => navigateTo(`/pay?qr=${encodeURIComponent(r.text)}`)" />
141
- </ClientOnly>
142
- </template>
143
- ```
144
-
145
- ## Svelte and SvelteKit
146
-
147
- The Svelte entry is an action. Actions only run in the browser, so it is safe in SvelteKit without `browser` checks.
148
-
149
- ```svelte
150
- <script lang="ts">
151
- import { qrScanner } from 'k-qr-scanner/svelte';
152
- let open = $state(false);
153
- </script>
154
-
155
- <button onclick={() => (open = true)}>Scan</button>
156
-
157
- {#if open}
158
- <div use:qrScanner={{ locale: 'lo', onScan: (r) => { open = false; pay(r.text); }, onClose: () => (open = false) }}>
159
- <button data-slot="actions-left">My QR code</button>
160
- </div>
161
- {/if}
162
- ```
163
-
164
- Svelte 5 only allows `slot="…"` inside custom elements, so children of the action use `data-slot="…"`. You can also use the element directly, where `slot` works and events are `on…` attributes:
165
-
166
- ```svelte
167
- <script>
168
- import 'k-qr-scanner';
169
- </script>
170
-
171
- <kqr-scanner theme="alipay" locale="lo" onscan={(e) => pay(e.detail.text)}>
172
- <button slot="actions-left">My QR code</button>
173
- </kqr-scanner>
174
- ```
175
-
176
- ## Angular
177
-
178
- Import the package once to register the element, and allow custom elements in the component:
179
-
180
- ```ts
181
- import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
182
- import 'k-qr-scanner';
183
- import type { ScanResult } from 'k-qr-scanner';
184
-
185
- @Component({
186
- selector: 'app-scan',
187
- standalone: true,
188
- schemas: [CUSTOM_ELEMENTS_SCHEMA],
189
- template: `
190
- <button (click)="open = true">Scan</button>
191
- @if (open) {
192
- <kqr-scanner locale="lo" (scan)="onScan($any($event).detail)" (close)="open = false"></kqr-scanner>
193
- }
194
- `,
195
- })
196
- export class ScanComponent {
197
- open = false;
198
- onScan(r: ScanResult) {
199
- this.open = false;
200
- console.log(r.text);
201
- }
202
- }
203
- ```
204
-
205
- The import is safe with Angular SSR; the element only activates in the browser. To set `accept` or `labels`, get the element with a template reference and `ViewChild`, then assign the property.
206
-
207
- ## React Native and Expo
208
-
209
- ```tsx
210
- import { QRScanner } from 'k-qr-scanner/react-native';
211
-
212
- <QRScanner style={{ flex: 1 }} locale="lo" onScan={(r) => pay(r.text)} onClose={() => setOpen(false)} />
213
- ```
214
-
215
- It needs `react-native-webview` and the camera permissions; `npx k-qr-scanner init` sets up both. Everything else is in [REACT_NATIVE.md](REACT_NATIVE.md).
216
-
217
- ## Plain HTML
218
-
219
- ```html
220
- <script src="https://cdn.jsdelivr.net/npm/k-qr-scanner/dist/kqrcode.global.js"></script>
221
-
222
- <button id="scan">Scan</button>
223
- <script>
224
- document.getElementById('scan').onclick = async () => {
225
- const { text } = await KQRCode.scanQR({ locale: 'lo' });
226
- alert(text);
227
- };
228
- </script>
229
- ```
230
-
231
- The script build (17 kB gzip) defines the global `KQRCode` and registers `<kqr-scanner>`. It loads the engine from `kqrcode.engine.js` in the same directory when the scanner first opens. Pin a version in production, e.g. `k-qr-scanner@0.2.0`, or self-host `kqrcode.global.js`, `kqrcode.engine.js` and `kqrcode.jsqr.js` together.
232
-
233
- ## Content-Security-Policy
234
-
235
- The engine runs WebAssembly in a worker created from a `blob:` URL, so a CSP needs:
236
-
237
- ```
238
- worker-src blob:; script-src 'self' 'wasm-unsafe-eval'
239
- ```
240
-
241
- With `superResolution: 'webgpu'`, also allow the ONNX Runtime CDN in `script-src` and `connect-src`, or self-host it and set `onnx-runtime-url`. If workers or WebAssembly are blocked, the scanner falls back to jsQR on the main thread: it still works, but slower, without super-resolution, and for regular QR codes only. `npx k-qr-scanner doctor` finds a CSP in your HTML and checks it.
@@ -1,181 +0,0 @@
1
- # React Native
2
-
3
- `k-qr-scanner/react-native` brings the same scanner to iOS and Android apps, Expo included: the themes, auto-zoom, Micro QR and rMQR, the `accept` callback and album import.
4
-
5
- - [Setup](#setup)
6
- - [Usage](#usage)
7
- - [Props](#props)
8
- - [Ref methods](#ref-methods)
9
- - [What the component handles for you](#what-the-component-handles-for-you)
10
- - [Platform notes](#platform-notes)
11
- - [Troubleshooting](#troubleshooting)
12
-
13
- ## How it works
14
-
15
- React Native has no DOM and no camera API in JavaScript, and Hermes cannot run WebAssembly. So the component renders a [`react-native-webview`](https://github.com/react-native-webview/react-native-webview) and runs the regular web scanner inside it. Events and the `accept` callback cross between the WebView and your app automatically.
16
-
17
- The engine is bundled with the component, about 0.8 MB (0.5 MB gzip). The scanner works offline, and there are no assets to configure.
18
-
19
- ## Setup
20
-
21
- ```bash
22
- npx k-qr-scanner init
23
- ```
24
-
25
- In a React Native or Expo project, this one command:
26
-
27
- 1. installs `k-qr-scanner` and `react-native-webview` (on Expo through `npx expo install`, so the WebView matches your SDK);
28
- 2. adds the camera permissions (see below);
29
- 3. writes a starter component, `components/QrScanner`.
30
-
31
- Then:
32
-
33
- - **bare React Native**: run `cd ios && pod install` and rebuild the app;
34
- - **Expo Go**: nothing to do, it already includes the WebView and the camera permission;
35
- - **Expo development or EAS builds**: the next `npx expo prebuild` or EAS build applies the permissions.
36
-
37
- ### Camera permissions
38
-
39
- | project | what `init` adds |
40
- | :--- | :--- |
41
- | Expo | `"plugins": ["k-qr-scanner"]` in `app.json`. The plugin writes both entries during prebuild. |
42
- | bare iOS | `NSCameraUsageDescription` in `ios/<App>/Info.plist` |
43
- | bare Android | `<uses-permission android:name="android.permission.CAMERA" />` in `android/app/src/main/AndroidManifest.xml` |
44
-
45
- > [!IMPORTANT]
46
- > Without `NSCameraUsageDescription`, iOS ends the app the moment the camera opens.
47
-
48
- To set your own iOS permission text with Expo:
49
-
50
- ```json
51
- { "expo": { "plugins": [["k-qr-scanner", { "cameraPermission": "Scan QR codes to pay" }]] } }
52
- ```
53
-
54
- You don't need to write any permission code. On Android the component asks for the camera before it opens the scanner; on iOS the system asks once when the camera starts.
55
-
56
- `npx k-qr-scanner doctor` checks that the WebView is installed and that both permissions are in place.
57
-
58
- ### Setting up by hand
59
-
60
- ```bash
61
- npm install k-qr-scanner react-native-webview
62
- cd ios && pod install
63
- ```
64
-
65
- Then add the two permission entries from the table above.
66
-
67
- ## Usage
68
-
69
- ```tsx
70
- import { useRef, useState } from 'react';
71
- import { Button, Modal } from 'react-native';
72
- import { QRScanner, type QRScannerHandle } from 'k-qr-scanner/react-native';
73
-
74
- export function PayScreen() {
75
- const [open, setOpen] = useState(false);
76
- const scanner = useRef<QRScannerHandle>(null);
77
-
78
- return (
79
- <>
80
- <Button title="Scan to pay" onPress={() => setOpen(true)} />
81
- <Modal visible={open} animationType="slide" presentationStyle="fullScreen" onRequestClose={() => setOpen(false)}>
82
- <QRScanner
83
- ref={scanner}
84
- style={{ flex: 1 }}
85
- theme="wechat"
86
- locale="lo"
87
- heading="ສະແກນເພື່ອຈ່າຍ"
88
- cssVars={{ '--kqr-accent': '#e60012' }}
89
- accept={async (r) => r.text.startsWith('000201') || 'ນີ້ບໍ່ແມ່ນ QR ຈ່າຍເງິນ'}
90
- onScan={(r) => { setOpen(false); pay(r.text); }}
91
- onClose={() => setOpen(false)}
92
- onError={(e) => console.warn(e.code)}
93
- slots={{ 'actions-left': '<button data-kqr-id="my-code">My QR code</button>' }}
94
- onSlotPress={(slot, id) => { if (id === 'my-code') showMyCode(); }}
95
- />
96
- </Modal>
97
- </>
98
- );
99
- }
100
- ```
101
-
102
- Mount the component to open the scanner and unmount it to close.
103
-
104
- ## Props
105
-
106
- These work exactly as on the web (see [API.md](API.md#scanqr)): `theme`, `locale`, `heading`, `labels`, `facing`, `continuous`, `success`, `torch`, `zoomControl`, `maxZoom`, `superResolution`, `formats`, `accept`, `noAutoZoom`, `noGallery`, `noTorch`, `noBeep`, `noVibrate` and `noClose`.
107
-
108
- Callbacks:
109
-
110
- | prop | called with | when |
111
- | :--- | :--- | :--- |
112
- | `onScan` | `ScanResult` | a code was read and accepted; `result.bytes` is a `Uint8Array` |
113
- | `onReject` | `ScanResult`, `message?` | `accept` turned a code down |
114
- | `onError` | `ScanError` | the camera could not start, e.g. `permission-denied` |
115
- | `onClose` | – | the user pressed ✕ |
116
- | `onReady` | – | the camera is running |
117
- | `onSlotPress` | `slot`, `id?` | something inside `slots` was tapped; `id` is the `data-kqr-id` of the tapped element |
118
-
119
- Only for React Native:
120
-
121
- | prop | type | description |
122
- | :--- | :--- | :--- |
123
- | `keepCamera` | `boolean` | keep the camera on after a result; call `resume()` to scan again |
124
- | `cssVars` | `Record<string, string>` | [CSS variables](CUSTOMIZE.md#css-variables) for the scanner UI |
125
- | `slots` | `Record<string, string>` | extra UI as **HTML strings** by [slot name](CUSTOMIZE.md#slots); React Native views can't be placed inside a WebView |
126
- | `scriptUrl` | `string` | load the scanner from a URL instead of the bundled copy |
127
- | `style` | `StyleProp<ViewStyle>` | style of the scanner view; default `{ flex: 1, backgroundColor: '#000' }` |
128
- | `webViewProps` | `WebViewProps` | extra props for `react-native-webview` |
129
-
130
- Changing a callback is free. Changing any other prop reloads the scanner and restarts the camera, so keep them stable while the scanner is open.
131
-
132
- ## Ref methods
133
-
134
- | method | description |
135
- | :--- | :--- |
136
- | `resume()` | scan again after a result; reopens the camera if it was stopped |
137
- | `start()` / `stop()` | open or release the camera |
138
- | `close()` | stop the camera and fire `onClose` |
139
- | `toggleTorch(on?)` | switch the flashlight |
140
- | `pickImage()` | open the photo picker |
141
-
142
- ## What the component handles for you
143
-
144
- The defaults are tuned for scanning, so most apps never need `webViewProps`:
145
-
146
- - **Permissions.** On Android it requests the camera permission before showing the scanner. On iOS it skips the second, web-level prompt, so the user is asked only once.
147
- - **Camera quality.** The stream starts at 1080p and goes up to 4K where the phone has no hardware zoom. Continuous autofocus, tap to focus, and hardware zoom and flashlight wherever the WebView offers them.
148
- - **Background.** While the app is in the background, the camera is released, so the camera indicator turns off and other apps can use the camera. It reopens when the app returns, unless a result is showing; then `resume()` reopens it.
149
- - **Recovery.** If the system kills the WebView process to free memory, the scanner reloads instead of leaving a black screen.
150
- - **A native feel.** Full screen, laid out around the notch, with no scrolling, bouncing, zoom gestures, link previews or text selection.
151
- - **Debugging.** In development builds, inspect the scanner page with Safari (iOS) or `chrome://inspect` (Android).
152
-
153
- ## Loading the scanner from a URL
154
-
155
- ```tsx
156
- <QRScanner scriptUrl="https://cdn.jsdelivr.net/npm/k-qr-scanner@0.2.0/dist/kqrcode.global.js" />
157
- ```
158
-
159
- This loads that version instead of the bundled one, which is useful to try a fix without an app update. `kqrcode.engine.js` must be in the same directory (it is on jsDelivr and unpkg), the phone needs network access, and the bundled copy stays in your app either way. Always pin a version.
160
-
161
- ## Platform notes
162
-
163
- | platform | notes |
164
- | :--- | :--- |
165
- | iOS 14.5+ | WKWebView has no camera zoom API, so zoom is digital, on a 4K stream as in Safari |
166
- | Android 7+ | needs an up-to-date Android System WebView; hardware zoom and the flashlight work where the device offers them |
167
- | Expo Go | works as is |
168
-
169
- - The scanner page has the address `https://kqrcode.local/`. A secure (`https`) address is what allows the camera; nothing is ever loaded from it.
170
- - `superResolution="webgpu"` downloads ONNX Runtime Web from a CDN. The default, `'js'`, works offline.
171
- - With iOS Lockdown Mode, WebAssembly is turned off. The scanner then falls back to jsQR, which reads regular QR codes only.
172
-
173
- ## Troubleshooting
174
-
175
- | problem | fix |
176
- | :--- | :--- |
177
- | the iOS app closes when the scanner opens | `NSCameraUsageDescription` is missing: run `npx k-qr-scanner init --no-install`, or add `"plugins": ["k-qr-scanner"]` on Expo, then rebuild |
178
- | `onError` with `permission-denied` | the user said no. On Android the system won't ask again after a second "no", so link to the app settings with `Linking.openSettings()` |
179
- | "Unable to resolve module react-native-webview" | install it (`npx expo install react-native-webview` on Expo), then rebuild or restart Metro |
180
- | a black screen and nothing happens | check `onError`, and look at the page in Safari or `chrome://inspect` in a development build |
181
- | Expo: the permission doesn't apply | the plugin runs during prebuild, so run `npx expo prebuild` or a new EAS build after adding it |
package/docs/TESTING.md DELETED
@@ -1,90 +0,0 @@
1
- # Testing
2
-
3
- k-qr-scanner is tested in four layers. CI runs the first on every push and pull request; run the others before a release.
4
-
5
- | layer | what it proves | runs |
6
- | :--- | :--- | :--- |
7
- | [1. Unit tests](#1-unit-tests) | the engine, auto-zoom, the CLI, SSR and the React Native bridge work | in CI, ~30 s |
8
- | [2. Browser end-to-end](#2-browser-end-to-end) | the real UI scans from a camera in Chrome | locally |
9
- | [3. Framework apps](#3-framework-apps) | production builds of real apps scan end to end | before a release |
10
- | [4. Cross-browser and devices](#4-cross-browser-and-devices) | Firefox, WebKit and real phones | before a release |
11
-
12
- ## 1. Unit tests
13
-
14
- ```bash
15
- npm ci
16
- npm run build # some tests use the built package
17
- npm test
18
- ```
19
-
20
- The 70 tests cover:
21
-
22
- - **decoding**: rotation, blur, perspective, far and inverted codes, the native-resolution region path, and Micro QR and rMQR;
23
- - **`formats` and module-size estimates** for every QR-family symbol;
24
- - **auto-zoom** decisions;
25
- - **super-resolution**: the JS kernel and the ONNX model, compared with reference output from OpenCV;
26
- - **SSR**: importing and rendering the React and Vue wrappers on the server;
27
- - **React Native**: the page builder and its escaping, the message bridge, `accept` round trips, the Android permission order, background handling, recovery after a WebView crash, and the Expo config plugin;
28
- - **the CLI**: framework detection, generated components, React Native permission edits (once only, and nothing with `--dry-run`), and `doctor`.
29
-
30
- ## 2. Browser end-to-end
31
-
32
- ```bash
33
- npx tsx scripts/e2e.mts # headless QRScanner reads a far code from the fake camera
34
- npx tsx scripts/e2e.mts --ios # the same with Safari's limits: no zoom API, no OffscreenCanvas, no BarcodeDetector
35
- npx tsx scripts/e2e.mts --micro # a Micro QR code instead of a regular one
36
- npx tsx scripts/e2e.mts --el # the <kqr-scanner> element
37
- npx tsx scripts/e2e.mts --scanqr # scanQR() resolves and removes itself
38
- npx tsx scripts/e2e.mts --global # the <script> build (KQRCode global, engine loaded next to it)
39
- npx tsx scripts/e2e.mts --csp # a strict CSP that blocks workers: the jsQR fallback
40
- npx tsx scripts/e2e.mts --accept # accept turns the first code down with a message, then accepts it
41
- npx tsx scripts/e2e.mts --rn # the React Native page at https://kqrcode.local with a stand-in bridge
42
- ```
43
-
44
- Flags can be combined. Chrome gets a fake camera that plays a QR code video. The React Native run checks the full message flow (`ready` → `accept` → `reject` → `accept` → `scan`), that the page is a secure context, and that the camera is released in the background and reopened afterwards.
45
-
46
- Chrome is used from its installed channel; set `CHROME_PATH` to use another binary.
47
-
48
- ## 3. Framework apps
49
-
50
- Five small apps install the packed tarball, build for production and are then scanned in Chrome with a fake camera: React with Vite, Next.js, Nuxt, SvelteKit and Angular.
51
-
52
- ```bash
53
- npm pack --pack-destination ../kqr-apps
54
- node scripts/make-apps.mjs ../kqr-apps
55
- # in each app: npm install && npm run build
56
- npx tsx scripts/themes.mts # creates the fake-camera videos
57
- npx tsx scripts/apps-e2e.mts ../kqr-apps
58
- ```
59
-
60
- Each app must render its server HTML (for the SSR frameworks), scan the code, show the slotted content and log no console errors.
61
-
62
- ## 4. Cross-browser and devices
63
-
64
- ```bash
65
- node node_modules/playwright-core/cli.js install firefox webkit
66
- npx tsx scripts/xbrowser.mts # or: npx tsx scripts/xbrowser.mts firefox
67
- ```
68
-
69
- The camera is simulated with `canvas.captureStream()` showing moving, rotating codes. For each browser the script measures the first and warm scan times, then checks photo decoding, `scanQR`, a 20-second continuous run (frame rate, wrong reads, memory) and 20 start/stop cycles, which must leave **no workers and no camera tracks** behind. Playwright's WebKit for Windows has no camera API, so on Windows only photo decoding and the "unsupported" screen are checked there.
70
-
71
- Emulation can't cover camera hardware, so check real devices before a release:
72
-
73
- | device | check |
74
- | :--- | :--- |
75
- | iPhone, Safari | opens; digital zoom reads a far code; flashlight (where available); album; rotating the phone |
76
- | Android, Chrome | hardware auto-zoom on a far code; flashlight; tap to focus |
77
- | Android, Samsung Internet | the same |
78
- | desktop Chrome, Firefox and Safari with a webcam | opens; reads a code shown on a phone |
79
- | React Native app on iOS and Android | the permission prompt; scanning; background and return; album |
80
-
81
- Serve `demo/index.html` over HTTPS (for example `npx serve` behind a tunnel) and report results as issues, with the device, OS and browser version.
82
-
83
- ## Benchmarks
84
-
85
- ```bash
86
- npm run bench # accuracy and CPU latency → bench/results.md, then updates the README table
87
- npx tsx bench/browser.mts # super-resolution speed in Chrome (JS, WebAssembly, WebGPU)
88
- ```
89
-
90
- The WeChat column needs Python with `opencv-contrib-python-headless<5` and the original model files (see `scripts/convert-sr.py`). Point `KQR_PY` at that Python; without it, the column is skipped. The method is described in [BENCHMARK.md](BENCHMARK.md).