initial files

.editorconfig

@@ -0,0 +1,15 @@
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = tab
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.md]
+indent_style = space
+indent_size = 4
+
+[*.yml]
+indent_style = space
+indent_size = 2

.github/workflows/build-testbed.yml

@@ -0,0 +1,49 @@
+# This is a basic workflow to help you get started with Actions
+
+name: Build-TestBed
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the "main" branch
+  push:
+    branches: [ "main" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v3
+
+      # Runs a set of commands using the runners shell
+      - name: install deps and build test bed
+        run: |
+          npm install
+          npm run build:gh-pages
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          # Upload built files
+          path: './.gh-build'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.gh-build/
+package-lock.json
+src/external
+test/src
+test/dist

.npmignore

@@ -0,0 +1,7 @@
+.npmignore
+.gitignore
+node_modules/
+.gh-build/
+src/external
+test/src
+test/dist

BUNDLERS.md

@@ -0,0 +1,86 @@
+# Deploying QR-Data-Sync WITH A Bundler
+
+This project has non-ESM dependencies, which unfortunately cannot be *bundled* in with your other app code. Modern bundlers unfortunately don't out-of-the-box support configurations that can handle such a situation.
+
+As such, this project provides plugins for webpack and vite, to take care of the various steps needed to get these non-ESM dependencies into an otherwise bundled web app built by those tools.
+
+## Bundler Plugins
+
+The plugins for vite and webpack are included in the `bundler-plugins/` directory. They should handle all necessary steps to load the dependencies.
+
+**Note:** You should not need to manually copy any files out of the `dist/bundlers/` directory, as the plugins access the `qr-data-sync` dependency (in `node_modules`) directly to pull the files needed. But for reference, the files these plugins access are:
+
+* `dist/bundlers/qrds.js`
+
+    ESM library module that's suitable for bundling and `import`ing into your web app.
+
+    **Note:** not `dist/auto/qrds.js`, which is only intended [for web application projects WITHOUT a bundler](NON-BUNDLERS.md)
+
+* `dist/bundlers/qrds-external-bundle.js`
+
+    Non-ESM (plain global .js) bundle of dependencies that must be loaded separately from (and prior to) your app's bundle. Includes the concatenated contents of these individual dependencies:
+
+    - `dist/auto/external/qrcode.js`
+
+### Vite Plugin
+
+If using Vite 5+, it's strongly suggested to import this library's vite-plugin to manage the loading of its non-ESM dependencies. Add something like the following to your `vite.config.js` file:
+
+```js
+import { defineConfig } from "vite";
+import QRDS from "qr-data-sync/bundlers/vite";
+
+export default defineConfig({
+    // ..
+
+    plugins: [ QRDS() ],
+
+    // ..
+});
+```
+
+This plugin works for both the `vite dev` (dev-server) mode and the `vite build` mode. In both cases, it copies the `dist/bundlers/qrds-external-bundle.js` file into the `public/` directory of your project root. It also injects a `<script src="qrds-external-bundle.js"></script>` tag into the markup of the `index.html` file that vite produces for your app.
+
+**Note:** At present, this plugin is not configurable in any way (i.e., calling `QRDS()` above with no arguments). If something about its behavior is not compatible with your vite project setup -- which can vary widely and be quite complex to predict or support by a basic plugin -- it's recommended you simply copy over the `qr-data-sync/bundler-plugins/vite.mjs` plugin and make necessary changes.
+
+### Webpack Plugin
+
+If using Webpack 5+, make sure you're already using the [HTML Webpack Plugin](https://github.com/jantimon/html-webpack-plugin/) to manage building your `index.html` (and/or other HTML pages).
+
+Then import this library's webpack-plugin to manage the loading of its non-ESM dependencies. Add something like the following to your `webpack.config.js`:
+
+```js
+// 'HtmlWebpackPlugin' is a required dependency of the
+// qr-data-sync webpack plugin
+import HtmlWebpackPlugin from "html-webpack-plugin";
+import QRDS from "qr-data-sync/bundlers/webpack";
+
+export default {
+    // ..
+
+    plugins: [
+        // required QRDS dependency
+        new HtmlWebpackPlugin({
+            // ..
+        }),
+
+        QRDS()
+    ],
+
+    // ..
+};
+```
+
+This plugin copies the `dist/bundlers/qrds-external-bundle.js` file into the build root (default `dist/`), along with the other bundled files. It also injects a `<script src="qrds-external-bundle.js"></script>` tag into the markup of the `index.html` file (and any other HTML files) that webpack produces for your app.
+
+**Note:** At present, this plugin is not configurable in any way (i.e., calling `QRDS()` above with no arguments). If something about its behavior is not compatible with your webpack project setup -- which can vary widely and be quite complex to predict or support by a basic plugin -- it's recommended you simply copy over the `qr-data-sync/bundler-plugins/webpack.mjs` plugin and make necessary changes.
+
+## Import/Usage
+
+To import and use **qr-data-sync** in a *bundled* browser app:
+
+```js
+import { todo } from "qr-data-sync";
+```
+
+When `import`ed like this, both vite and webpack should (via these plugins) properly find and bundle the `dist/bundlers/qrds.js` ESM library module with the rest of your app code, without any further steps necessary.

LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2024 Kyle Simpson <[email protected]>
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

NON-BUNDLERS.md

@@ -0,0 +1,48 @@
+# Deploying QR-Data-Sync WITHOUT A Bundler
+
+To use this library directly -- i.e., in a classic/vanilla web project without a modern bundler tool -- make a directory for it (e.g., `qr-data-sync/`) in your browser app's JS assets directory.
+
+Then copy over all `dist/auto/*` contents, as-is:
+
+* `dist/auto/qrds.js`
+
+    **Note:** not `dist/bundlers/qrds.js`, which is only intended [for web application projects WITH a bundler](BUNDLERS.md)
+
+* `dist/auto/external.js`
+
+    This is an *auto-loader* that dynamically loads the rest of the `external/*` dependencies via `<script>`-element injection into the DOM. `dist/auto/qrds.js` imports and activates this loader automatically.
+
+* `dist/auto/external/*` (preserve the whole `external/` sub-directory):
+    - `qrcode.js`
+    - `qr-scanner.min.js`
+    - `qr-scanner-worker.min.js`
+
+## Import/Usage
+
+To import and use **qr-data-sync** in a *non-bundled* browser app:
+
+```js
+import { todo } from "/path/to/js-assets/qr-data-sync/qrds.js";
+```
+
+The library's dependencies will be auto-loaded (via `external.js`).
+
+## Using Import Map
+
+If your **non-bundled** browser app has an [Import Map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap), you can improve the `import` by adding an entry for this library:
+
+```html
+<script type="importmap">
+{
+    "imports": {
+        "qr-data-sync": "/path/to/js-assets/qr-data-sync/qrds.js"
+    }
+}
+</script>
+```
+
+Then you'll be able to `import` the library in a more friendly/readable way:
+
+```js
+import { todo } from "qr-data-sync";
+```

README.md

@@ -0,0 +1,60 @@
+# QR Data Sync
+
+[![npm Module](https://badge.fury.io/mylofi/qr-data-sync.svg)](https://www.npmjs.org/package/qr-data-sync)
+[![License](https://img.shields.io/badge/license-MIT-a1356a)](LICENSE.txt)
+
+**QR Data Sync** is a browser library with utils for sharing/synchronizing data via "animated" QR codes.
+
+----
+
+[Demo/Tests](https://mylofi.github.io/qr-data-sync/)
+
+----
+
+## Deployment / Import
+
+The [**qr-data-sync** npm package](https://npmjs.com/package/webauthn-local-client) includes a `dist/` directory with all files you need to deploy **qr-data-sync** (and its dependencies) into your application/project.
+
+If you obtain this library via git instead of npm, you'll need to [build `dist/` manually](#re-building-dist) before deployment.
+
+* **USING A WEB BUNDLER?** (vite, webpack, etc) Use the `dist/bundlers/*` files and see [Bundler Deployment](BUNDLERS.md) for instructions.
+
+* Otherwise, use the `dist/auto/*` files and see [Non-Bundler Deployment](NON-BUNDLERS.md) for instructions.
+
+## Re-building `dist/*`
+
+If you need to rebuild the `dist/*` files for any reason, run:
+
+```cmd
+# only needed one time
+npm install
+
+npm run build:all
+```
+
+## Tests
+
+Since the library involves non-automatable behaviors (requiring user intervention on two devices at once), an automated unit-test suite is not included. Instead, a simple interactive browser test page is provided, to run on both devices.
+
+Visit [`https://mylofi.github.io/qr-data-sync/`](https://mylofi.github.io/qr-data-sync/) on each device, and follow instructions in-page from there to perform the interactive tests.
+
+**Note:** You will need two devices to test, and at least one needs a camera.
+
+### Run Locally
+
+To locally run the tests, start the simple static server (no server-side logic):
+
+```cmd
+# only needed one time
+npm install
+
+npm run test:start
+```
+
+Then visit `http://localhost:8080/` in a browser.
+
+## License
+
+[![License](https://img.shields.io/badge/license-MIT-a1356a)](LICENSE.txt)
+
+All code and documentation are (c) 2024 Kyle Simpson and released under the [MIT License](http://getify.mit-license.org/). A copy of the MIT License [is also included](LICENSE.txt).