@dile/scanner 0.0.8 → 0.1.0

package/README.md

@@ -22,9 +22,9 @@ Read the docs and find demos on the [dile-components site](https://dile-componen
 
 ## ML detector files
 
-The ML detector is optional and off by default. Without `ml-detector` your users download nothing of it. With `ml-detector` the component uses scanic's neural detector, and the browser downloads its files (3.5 MB, about 2.2 MB with gzip) the first time a photo is processed.
+The ML detector is optional and off by default. Without `ml-detector` your users download nothing of it. With `ml-detector` the component uses scanic's neural detector, and the browser downloads its files (3.5 MB, about 2.2 MB with gzip) in the background the first time the scanner is opened.
 
-By default the files come from jsDelivr. The package installs the matching `scanic-ml` version (3.5 MB in `node_modules`, only disk space in your project), so you can serve your own copy with the included Vite plugin:
+By default the files come from jsDelivr. The package installs the matching `scanic-ml` version (3.5 MB in `node_modules`, only disk space in your project), so you can serve your own copy with the included Vite plugin. It serves them in a folder with the `scanic-ml` version (`/dile-scanner-ml/0.2.0/`) and exports that URL in a virtual module:
 
 ```javascript
 // vite.config.js
@@ -33,10 +33,36 @@ import { scannerMlAssets } from '@dile/scanner/vite-plugin.js';
 export default { plugins: [scannerMlAssets()] };
 ```
 
-```html
-<dile-scanner ml-detector ml-assets-url="/dile-scanner-ml/"></dile-scanner>
+```javascript
+import { mlAssetsUrl } from 'virtual:dile-scanner-ml';
+
+scanner.mlDetector = true;
+scanner.mlAssetsUrl = mlAssetsUrl;
 ```
 
+## Using it in a PWA
+
+The ML files can be cached by the service worker so they are downloaded only once, the first time the scanner is opened. Don't precache them (they would be downloaded when installing the app); add a runtime caching rule instead. With vite-plugin-pwa:
+
+```javascript
+VitePWA({
+  workbox: {
+    globIgnores: ['**/dile-scanner-ml/**'],
+    runtimeCaching: [{
+      urlPattern: ({ url }) => url.pathname.includes('/dile-scanner-ml/'),
+      handler: 'CacheFirst',
+      options: {
+        cacheName: 'dile-scanner-ml',
+        cacheableResponse: { statuses: [200] },
+        expiration: { maxEntries: 3 },
+      },
+    }],
+  },
+})
+```
+
+The versioned folder makes sure an update never mixes cached files of different versions. See the [docs](https://dile-components.com/components/dile-scanner/#pwa) for the details.
+
 ## Maintenance note
 
 `scanic` is pinned to an exact version because `src/corner-editor-styles.js` copies the styles of its corner editor (scanic injects them into `document.head`, which does not reach the shadow root). When updating scanic, review that copy against `node_modules/scanic/dist/scanic.js` (search `.scanic-corner-editor`) and update `scanic-ml` (also pinned) to the version that scanic expects (see the jsDelivr URL in `node_modules/scanic/dist/scanic-mlDetector.js`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dile/scanner",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "description": "Web Component to scan documents in the browser: edge detection, perspective correction and multipage PDF or JPEG output, powered by scanic and jsPDF",
   "keywords": [
     "scanner",
@@ -36,5 +36,5 @@
     "scanic": "1.7.1",
     "scanic-ml": "0.2.0"
   },
-  "gitHead": "978a1d5b553cf39a5614223130f3446ec0bb89f2"
+  "gitHead": "e48f49078bcae4a1c3f879c0c0d03e5445d1a535"
 }

package/src/DileScanner.js

@@ -2,6 +2,8 @@ import { LitElement, html, css, nothing } from "lit";
 import "@dile/ui/components/modal/modal.js";
 import "@dile/ui/components/button/button.js";
 import "@dile/ui/components/spinner/spinner.js";
+import "@dile/ui/components/progress-bar/progress-bar.js";
+import "@dile/iconlib/dile-iconlib.js";
 import "@dile/iconlib/lucide-icons/camera.js";
 import "@dile/iconlib/lucide-icons/image.js";
 import "@dile/iconlib/lucide-icons/check.js";
@@ -50,8 +52,10 @@ const SIZE_FALLBACKS = [
 // (output="images"). With "multipage" the user can add several pages, reorder
 // them, rotate them, adjust them again and remove them. With "ml-detector"
 // the edges are detected with scanic's neural detector (about 2.2 MB
-// downloaded with gzip the first time) instead of the classical one; off by
-// default.
+// downloaded with gzip the first time the scanner opens) instead of the
+// classical one; off by default. A photo waits for that download at most
+// "ml-max-wait" ms, and "ml-fast-connection-only" skips it on slow
+// connections.
 //
 // It does not upload anything: when the user saves, it dispatches
 // "dile-document-scanned" with the files and closes. Closing it without saving
@@ -77,6 +81,14 @@ export class DileScanner extends LitElement {
         --dile-modal-border-radius: var(--dile-scanner-modal-border-radius, 15px);
         --dile-modal-content-background-color: var(--dile-background-color, #fff);
         --dile-modal-content-text-color: var(--dile-on-background-color, #303030);
+        /* Grays mixed from the theme background and text colors, so the
+           scanner works with light and dark themes without hardcoded grays. */
+        --_fg: var(--dile-on-background-color, #303030);
+        --_bg: var(--dile-background-color, #fff);
+        --_surface: color-mix(in srgb, var(--_fg) 6%, var(--_bg));
+        --_surface-strong: color-mix(in srgb, var(--_fg) 12%, var(--_bg));
+        --_border: color-mix(in srgb, var(--_fg) 15%, var(--_bg));
+        --_muted: color-mix(in srgb, var(--_fg) 68%, var(--_bg));
       }
       @media (max-width: 600px) {
         :host {
@@ -127,14 +139,39 @@ export class DileScanner extends LitElement {
       }
       @media (max-width: 600px) {
         .footer {
-          justify-content: space-between;
+          display: grid;
+          grid-auto-columns: 1fr;
+          grid-auto-flow: column;
           --dile-button-padding-x: 0.6rem;
           --dile-button-font-size: 0.9rem;
         }
+        .footer dile-button {
+          display: grid;
+        }
       }
+      /* Secondary buttons set their own text color: inheriting
+         --dile-on-primary-color can leave text without contrast on their
+         background. By default they use the theme background and text colors,
+         so they also work with dark themes. Hover keeps the same
+         colors so a theme hover color does not ruin the contrast either. */
       .secondary {
-        --dile-button-background-color: var(--dile-scanner-secondary-button-color, #888);
-        --dile-button-border-color: var(--dile-scanner-secondary-button-color, #888);
+        --dile-button-background-color: var(--dile-scanner-secondary-button-color, var(--_surface-strong));
+        --dile-button-border-color: var(--dile-scanner-secondary-button-color, var(--_surface-strong));
+        --dile-button-text-color: var(--dile-scanner-secondary-button-text-color, var(--_fg));
+        --dile-button-hover-background-color: var(--dile-scanner-secondary-button-color, var(--_surface-strong));
+        --dile-button-hover-border-color: var(--dile-scanner-secondary-button-color, var(--_surface-strong));
+        --dile-button-hover-text-color: var(--dile-scanner-secondary-button-text-color, var(--_fg));
+      }
+      /* Outlined buttons to add pages, lighter than the main action. */
+      .outline {
+        --dile-button-background-color: transparent;
+        --dile-button-hover-background-color: transparent;
+        --dile-button-border-color: var(--dile-scanner-outline-button-color, var(--_fg));
+        --dile-button-hover-border-color: var(--dile-scanner-outline-button-color, var(--_fg));
+        --dile-button-text-color: var(--dile-scanner-outline-button-color, var(--_fg));
+        --dile-button-hover-text-color: var(--dile-scanner-outline-button-color, var(--_fg));
+        --dile-button-border-width: 1px;
+        --dile-button-font-weight: normal;
       }
       .file-input {
         display: none;
@@ -152,53 +189,137 @@ export class DileScanner extends LitElement {
           height: calc(100dvh - 18rem);
         }
       }
+      .subtitle {
+        margin-top: -0.75rem;
+        font-size: 0.9rem;
+        color: var(--dile-scanner-muted-text-color, var(--_muted));
+      }
+      /* Pages in a horizontal scroll area with snap: on a phone each card
+         takes most of the width and the next one peeks out; on wider screens
+         several cards fit side by side. */
       .pages {
-        display: grid;
-        grid-template-columns: repeat(auto-fill, minmax(170px, 1fr));
+        display: flex;
         gap: 0.75rem;
+        overflow-x: auto;
+        scroll-snap-type: x mandatory;
+        padding: 0.25rem 0.25rem 0.75rem;
+        margin: 0 -0.25rem;
+        scrollbar-width: thin;
       }
       .page {
+        flex: 0 0 var(--dile-scanner-page-width, min(78%, 250px));
+        scroll-snap-align: center;
         display: flex;
         flex-direction: column;
-        gap: 0.25rem;
+        gap: 0.5rem;
         padding: 0.5rem;
-        border-radius: 0.5rem;
-        background-color: var(--dile-very-light-color, #f4f4f4);
+        border-radius: 0.75rem;
+        background-color: var(--dile-scanner-page-background-color, var(--_bg));
+        border: 1px solid var(--dile-scanner-page-border-color, var(--_border));
+        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+      }
+      .page-header .page-number {
+        color: var(--_fg);
       }
       .page img {
         width: 100%;
-        height: 170px;
+        height: 200px;
         object-fit: contain;
-        background-color: #fff;
-        border-radius: 0.25rem;
+        padding: 0.5rem;
+        background-color: var(--dile-scanner-page-image-background-color, var(--_surface-strong));
+        border-radius: 0.5rem;
+      }
+      .single .pages {
+        justify-content: center;
       }
       .single .page {
-        max-width: 420px;
-        margin: 0 auto;
-        width: 100%;
+        flex-basis: min(100%, 420px);
       }
       .single .page img {
         height: min(55dvh, 520px);
       }
+      .page-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 0.25rem;
+        padding: 0.25rem;
+        border-radius: 0.5rem;
+        background-color: var(--dile-scanner-page-header-background-color, var(--_surface));
+        --dile-button-border-radius: 0.4rem;
+        --dile-button-border-width: 0;
+        --dile-button-padding-y: 0.3rem;
+        --dile-button-padding-x: 0.3rem;
+        --dile-button-background-color: var(--dile-scanner-move-button-color, #5f6368);
+        --dile-button-hover-background-color: var(--dile-scanner-move-button-color, #5f6368);
+        --dile-button-text-color: #fff;
+        --dile-button-hover-text-color: #fff;
+        --dile-button-disabled-background-color: transparent;
+        --dile-button-disabled-text-color: var(--_border);
+      }
       .page-number {
-        font-size: 0.85rem;
+        flex: 1;
+        font-size: 0.9rem;
         text-align: center;
       }
       .page-actions {
-        display: flex;
-        justify-content: center;
-        flex-wrap: wrap;
+        display: grid;
+        grid-auto-columns: 1fr;
+        grid-auto-flow: column;
         gap: 0.25rem;
-        --dile-button-padding-y: 0.3rem;
-        --dile-button-padding-x: 0.4rem;
       }
-      .page-actions .remove {
-        --dile-button-background-color: var(--dile-alert-error-color, #c00);
-        --dile-button-border-color: var(--dile-alert-error-color, #c00);
+      .page-action {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: 0.2rem;
+        padding: 0.35rem 0.2rem;
+        border: none;
+        border-radius: 0.4rem;
+        background: none;
+        font: inherit;
+        font-size: 0.7rem;
+        text-transform: uppercase;
+        letter-spacing: 0.02em;
+        cursor: pointer;
+        color: var(--dile-scanner-page-action-color, var(--_fg));
+        --dile-icon-color: currentColor;
+        --dile-icon-size: 22px;
+      }
+      .page-action:hover {
+        background-color: var(--dile-scanner-page-header-background-color, var(--_surface));
+      }
+      .page-action:focus-visible {
+        outline: 2px solid var(--dile-button-ring-color, #12c9e9);
+      }
+      .page-action.remove {
+        color: var(--dile-scanner-remove-button-color, var(--dile-alert-error-color, #c00));
+        font-weight: bold;
       }
       .size {
+        display: flex;
+        flex-direction: column;
+        gap: 0.4rem;
         font-size: 0.85rem;
-        color: var(--dile-secondary-dark-color, #888);
+        --dile-progress-background: var(--dile-scanner-size-track-color, var(--_surface-strong));
+        --dile-progress-bar-background: var(--dile-scanner-size-bar-color, var(--dile-scanner-accent-color, var(--_fg)));
+        --dile-progress-bar-min-height: 6px;
+        --dile-progress-bar-percentage-font-size: 0;
+        --dile-progres-bar-percentage-padding-top: 0;
+        --dile-progres-bar-percentage-padding-right: 0;
+        --dile-progres-bar-percentage-padding-bottom: 0;
+        --dile-progres-bar-percentage-padding-left: 0;
+      }
+      .size.full {
+        --dile-progress-bar-background: var(--dile-alert-error-color, #c00);
+      }
+      .size-row {
+        display: flex;
+        justify-content: space-between;
+        gap: 0.5rem;
+      }
+      .size-value {
+        color: var(--dile-scanner-muted-text-color, var(--_muted));
       }
       .busy {
         display: flex;
@@ -230,7 +351,7 @@ export class DileScanner extends LitElement {
        * Detects the edges with scanic's neural detector (more robust on hard
        * photos), falling back to the classical one when it finds nothing.
        * Downloads about 2.2 MB with gzip (3.5 MB uncompressed) the first
-       * time it is used.
+       * time the scanner is opened.
        */
       mlDetector: { type: Boolean, attribute: "ml-detector" },
       /**
@@ -238,6 +359,19 @@ export class DileScanner extends LitElement {
        * ONNX runtime). Empty: they are downloaded from jsDelivr.
        */
       mlAssetsUrl: { type: String, attribute: "ml-assets-url" },
+      /**
+       * Maximum time in milliseconds a photo waits for the ML detector while
+       * it downloads (0 means no limit). When it is not ready, the classical
+       * detector is used for that photo and the download goes on in the
+       * background.
+       */
+      mlMaxWait: { type: Number, attribute: "ml-max-wait" },
+      /**
+       * Does not download the ML detector when the browser reports a slow
+       * connection (2G, 3G or data saver), unless it is already in the cache
+       * (Cache Storage). The classical detector is used instead.
+       */
+      mlFastConnectionOnly: { type: Boolean, attribute: "ml-fast-connection-only" },
       _step: { type: String, state: true },
       _pages: { type: Array, state: true },
       _busy: { type: Boolean, state: true },
@@ -257,6 +391,8 @@ export class DileScanner extends LitElement {
     this.labels = {};
     this.mlDetector = false;
     this.mlAssetsUrl = "";
+    this.mlMaxWait = 5000;
+    this.mlFastConnectionOnly = false;
     this._step = "capture";
     this._pages = [];
     this._busy = false;
@@ -266,6 +402,7 @@ export class DileScanner extends LitElement {
     this._adjusting = null;
     this._editor = null;
     this._saved = false;
+    this._scrollToPage = null;
     // Changes on every reset: an async task started before closing or
     // reopening the scanner checks it to discard its result.
     this._session = 0;
@@ -276,6 +413,15 @@ export class DileScanner extends LitElement {
     return { ...DEFAULT_LABELS, ...this.labels };
   }
 
+  get _engineOptions() {
+    return {
+      ml: this.mlDetector,
+      mlAssetsUrl: this.mlAssetsUrl,
+      mlMaxWait: this.mlMaxWait,
+      mlFastConnectionOnly: this.mlFastConnectionOnly,
+    };
+  }
+
   get _modal() {
     return this.shadowRoot.getElementById("modal");
   }
@@ -284,7 +430,7 @@ export class DileScanner extends LitElement {
   open() {
     this._reset();
     this._saved = false;
-    preloadEngine();
+    preloadEngine(this._engineOptions);
     this._modal.open();
   }
 
@@ -293,6 +439,18 @@ export class DileScanner extends LitElement {
     this._modal.close();
   }
 
+  updated() {
+    // Brings a new or moved page into view in the horizontal page list. It
+    // waits while the step is hidden (busy), because a hidden element can't
+    // be scrolled.
+    if (this._scrollToPage === null || this._busy || this._step !== "pages") {
+      return;
+    }
+    const page = this.shadowRoot.querySelector(`.page[data-index="${this._scrollToPage}"]`);
+    this._scrollToPage = null;
+    page?.scrollIntoView({ block: "nearest", inline: "center", behavior: "smooth" });
+  }
+
   disconnectedCallback() {
     super.disconnectedCallback();
     this._reset();
@@ -304,6 +462,12 @@ export class DileScanner extends LitElement {
       <dile-modal id="modal" blocking @dile-modal-closed=${this._onModalClosed}>
         <div class="scanner">
           <h2>${labels.title}</h2>
+          ${this._step === "pages" && this.multipage && !this._busy
+            ? html`<p class="subtitle">
+                ${this._pages.length}
+                ${this._pages.length === 1 ? labels.pageScanned : labels.pagesScanned}
+              </p>`
+            : nothing}
           ${this._busy
             ? html`<div class="busy">
                 <dile-spinner active></dile-spinner>
@@ -362,10 +526,11 @@ export class DileScanner extends LitElement {
     `;
   }
 
-  _captureButtons(photoLabel, imageLabel, disabled = false) {
+  _captureButtons(photoLabel, imageLabel, disabled = false, className = "") {
     return html`
       ${this._isTouchDevice
         ? html`<dile-button
+            class=${className}
             icon="lucide.camera"
             ?disabled=${disabled}
             @click=${this._takePhoto}
@@ -373,6 +538,7 @@ export class DileScanner extends LitElement {
           >`
         : nothing}
       <dile-button
+        class=${className}
         icon="lucide.image"
         ?disabled=${disabled}
         @click=${this._chooseImage}
@@ -411,87 +577,100 @@ export class DileScanner extends LitElement {
 
   _pagesTemplate(labels) {
     const limitReached = this._limitReached;
+    const count = this._pages.length;
     return html`
       <div class="${this.multipage ? "" : "single"}">
         <div class="pages">
           ${this._pages.map((page, index) => this._pageTemplate(page, index, labels))}
         </div>
       </div>
-      ${this.maxBytes
-        ? html`<p class="size">
-            ${this._formatSize(this._pagesSize)} ${labels.sizeOf}
-            ${this._formatSize(this.maxBytes)}
-          </p>`
-        : nothing}
+      ${this.maxBytes ? this._sizeTemplate(labels, limitReached) : nothing}
       ${this.multipage && limitReached
         ? html`<p class="message">${labels.sizeLimitReached}</p>`
         : nothing}
       <div class="actions">
         ${this.multipage
-          ? this._captureButtons(labels.addPhoto, labels.addImage, limitReached)
-          : this._captureButtons(labels.retakePhoto, labels.replaceImage)}
+          ? this._captureButtons(labels.addPhoto, labels.addImage, limitReached, "outline")
+          : this._captureButtons(labels.retakePhoto, labels.replaceImage, false, "outline")}
       </div>
       <div class="footer">
         <dile-button class="secondary" icon="lucide.x" @click=${this.close}
           >${labels.cancel}</dile-button
         >
         <dile-button icon="lucide.check" @click=${this._save}
-          >${labels.confirm}</dile-button
+          >${labels.confirm}${this.multipage ? ` (${count})` : ""}</dile-button
         >
       </div>
     `;
   }
 
+  _sizeTemplate(labels, limitReached) {
+    const percent = Math.min(100, Math.round((this._pagesSize / this.maxBytes) * 100));
+    return html`
+      <div class="size ${limitReached ? "full" : ""}">
+        <div class="size-row">
+          <span>${labels.documentSize}</span>
+          <span class="size-value"
+            >${this._formatSize(this._pagesSize)} ${labels.sizeOf}
+            ${this._formatSize(this.maxBytes)}</span
+          >
+        </div>
+        <dile-progress-bar value=${percent} aria-hidden="true"></dile-progress-bar>
+      </div>
+    `;
+  }
+
   _pageTemplate(page, index, labels) {
-    const isFirst = index === 0;
-    const isLast = index === this._pages.length - 1;
-    const showOrder = this.multipage && this._pages.length > 1;
+    const count = this._pages.length;
+    const showOrder = this.multipage && count > 1;
     return html`
-      <div class="page">
-        <img src=${page.url} alt="${labels.page} ${index + 1}" />
+      <div class="page" data-index=${index}>
         ${this.multipage
-          ? html`<div class="page-number">${labels.page} ${index + 1}</div>`
+          ? html`<div class="page-header">
+              ${showOrder
+                ? html`<dile-button
+                    icon="lucide.chevron-left"
+                    label=${labels.moveBefore}
+                    title=${labels.moveBefore}
+                    ?disabled=${index === 0}
+                    @click=${() => this._movePage(index, -1)}
+                  ></dile-button>`
+                : nothing}
+              <span class="page-number"
+                >${labels.page} ${index + 1} ${labels.pageOf} ${count}</span
+              >
+              ${showOrder
+                ? html`<dile-button
+                    icon="lucide.chevron-right"
+                    label=${labels.moveAfter}
+                    title=${labels.moveAfter}
+                    ?disabled=${index === count - 1}
+                    @click=${() => this._movePage(index, 1)}
+                  ></dile-button>`
+                : nothing}
+            </div>`
           : nothing}
+        <img src=${page.url} alt="${labels.page} ${index + 1}" />
         <div class="page-actions">
-          ${showOrder
-            ? html`<dile-button
-                icon="lucide.chevron-left"
-                label=${labels.moveBefore}
-                ?disabled=${isFirst}
-                @click=${() => this._movePage(index, -1)}
-              ></dile-button>`
-            : nothing}
-          <dile-button
-            icon="lucide.rotate-cw"
-            label=${labels.rotate}
-            @click=${() => this._rotatePage(index)}
-          ></dile-button>
-          <dile-button
-            icon="lucide.crop"
-            label=${labels.adjust}
-            @click=${() => this._adjustPage(index)}
-          ></dile-button>
+          ${this._pageAction("lucide.rotate-cw", labels.rotate, () => this._rotatePage(index))}
+          ${this._pageAction("lucide.crop", labels.adjust, () => this._adjustPage(index))}
           ${this.multipage
-            ? html`<dile-button
-                class="remove"
-                icon="lucide.trash-2"
-                label=${labels.remove}
-                @click=${() => this._removePage(index)}
-              ></dile-button>`
-            : nothing}
-          ${showOrder
-            ? html`<dile-button
-                icon="lucide.chevron-right"
-                label=${labels.moveAfter}
-                ?disabled=${isLast}
-                @click=${() => this._movePage(index, 1)}
-              ></dile-button>`
+            ? this._pageAction("lucide.trash-2", labels.remove, () => this._removePage(index), "remove")
             : nothing}
         </div>
       </div>
     `;
   }
 
+  _pageAction(icon, label, onClick, className = "") {
+    return html`
+      <button type="button" class="page-action ${className}" data-icon=${icon} @click=${onClick}>
+        <dile-iconlib icon=${icon} aria-hidden="true"></dile-iconlib>
+        <span>${label}</span>
+      </button>
+    `;
+  }
+
   // ---- Capture ----
 
   _takePhoto() {
@@ -544,10 +723,7 @@ export class DileScanner extends LitElement {
     }
     try {
       const [corners, sourceBlob] = await Promise.all([
-        detectCorners(canvas, {
-          ml: this.mlDetector,
-          mlAssetsUrl: this.mlAssetsUrl,
-        }).catch(() => null),
+        detectCorners(canvas, this._engineOptions).catch(() => null),
         canvasToBlob(canvas, "image/jpeg", SOURCE_QUALITY),
       ]);
       if (session !== this._session) {
@@ -667,6 +843,7 @@ export class DileScanner extends LitElement {
     const pages = [...this._pages];
     if (index === null || index === undefined) {
       pages.push(page);
+      this._scrollToPage = pages.length - 1;
     } else {
       URL.revokeObjectURL(pages[index].url);
       pages[index] = page;
@@ -729,6 +906,7 @@ export class DileScanner extends LitElement {
     const pages = [...this._pages];
     [pages[index], pages[target]] = [pages[target], pages[index]];
     this._pages = pages;
+    this._scrollToPage = target;
   }
 
   _removePage(index) {

package/src/default-labels.js

@@ -19,11 +19,15 @@ export const DEFAULT_LABELS = {
   cancel: "Cancel",
   confirm: "Save document",
   page: "Page",
+  pageOf: "of",
+  pageScanned: "page scanned",
+  pagesScanned: "pages scanned",
+  documentSize: "Document size",
   rotate: "Rotate",
-  adjust: "Adjust edges",
+  adjust: "Crop",
   moveBefore: "Move before",
   moveAfter: "Move after",
-  remove: "Remove page",
+  remove: "Delete",
   processing: "Processing…",
   readError:
     "The image could not be read. Try with another image (JPG, PNG or WebP).",

package/src/scanner-engine.js

@@ -12,12 +12,121 @@ function loadScanic() {
   return scanicModule;
 }
 
+// Base URL of the "scanic-ml" files when no mlAssetsUrl is given. scanic uses
+// the same one internally; it is repeated here to look for the files in the
+// cache (see isMlCached). scanner-ml.spec.js checks that its version matches
+// the installed "scanic-ml".
+export const CDN_ML_ASSETS_URL = "https://cdn.jsdelivr.net/npm/scanic-ml@0.2.0/dist/";
+
+// The two big files of the ML detector (the .mjs loader is tiny).
+const ML_CACHE_CHECK_FILES = ["doccornernet_lean.ort", "ort-wasm-simd-threaded.wasm"];
+
+// Connections where downloading about 2.2 MB takes too long (see
+// isSlowConnection).
+const SLOW_CONNECTION_TYPES = ["slow-2g", "2g", "3g"];
+
+// scanic aborts the download of the model after 30 s by default. The download
+// goes on in the background even when a photo stops waiting for it (see
+// mlMaxWait), so it gets a much longer limit: on a slow connection it would
+// never finish (nor reach the cache) with 30 s, and with no limit at all a
+// stalled connection would keep it pending until the page is reloaded.
+const ML_MODEL_FETCH_TIMEOUT_MS = 5 * 60 * 1000;
+
+// Loading of the ML detector: { key, promise }. The promise resolves to true
+// when it is ready and to false when it fails or is skipped (slow connection),
+// and never rejects. It is forgotten when it does not end ready, so the next
+// open() or photo decides again (e.g. the network is back or got faster).
+let mlLoad = null;
+
 // Starts downloading scanic in the background (e.g. when the scanner opens),
-// so it is ready by the time the first photo arrives.
-export function preloadEngine() {
+// so it is ready by the time the first photo arrives. With "ml" it also
+// prepares the neural detector (see loadMl), so the first photo does not wait
+// for about 2.2 MB. Calling it on every open() downloads nothing again.
+export function preloadEngine({ ml = false, mlAssetsUrl = "", mlFastConnectionOnly = false } = {}) {
   loadScanic().catch(() => {
     // Ignored here: the error shows up again when the engine is really used.
   });
+  if (ml) {
+    loadMl({ mlAssetsUrl, mlFastConnectionOnly });
+  }
+}
+
+// Downloads the ML detector files and creates its session. scanic keeps the
+// session cached by URL, so detectCorners() reuses it. With
+// "mlFastConnectionOnly" nothing is downloaded on a slow connection, unless the
+// files are already in the cache.
+function loadMl({ mlAssetsUrl, mlFastConnectionOnly }) {
+  const key = mlAssetsUrl;
+  if (mlLoad?.key === key) {
+    return mlLoad.promise;
+  }
+  const current = {
+    key,
+    promise: (async () => {
+      if (mlFastConnectionOnly && isSlowConnection() && !(await isMlCached(mlAssetsUrl))) {
+        return false;
+      }
+      const { Scanner } = await loadScanic();
+      await new Scanner({ detector: "ml", ml: mlOptions(mlAssetsUrl) }).initialize();
+      return true;
+    })().catch(() => false),
+  };
+  mlLoad = current;
+  current.promise.then((ready) => {
+    if (!ready && mlLoad === current) {
+      mlLoad = null;
+    }
+  });
+  return current.promise;
+}
+
+// True when the browser says the connection is slow or the user asked to save
+// data. Only Chromium browsers have navigator.connection: elsewhere (Safari,
+// Firefox) the connection is unknown and this returns false.
+export function isSlowConnection() {
+  const connection = globalThis.navigator?.connection;
+  if (!connection) {
+    return false;
+  }
+  return connection.saveData === true || SLOW_CONNECTION_TYPES.includes(connection.effectiveType);
+}
+
+// True when the ML files are in the Cache Storage (e.g. cached by the service
+// worker of a PWA). The HTTP cache of the browser can't be checked.
+export async function isMlCached(mlAssetsUrl = "") {
+  if (!globalThis.caches) {
+    return false;
+  }
+  try {
+    const base = new URL(mlAssetsUrl || CDN_ML_ASSETS_URL, document.baseURI);
+    const folder = base.href.endsWith("/") ? base.href : `${base.href}/`;
+    const matches = await Promise.all(
+      ML_CACHE_CHECK_FILES.map((file) => caches.match(new URL(file, folder).href)),
+    );
+    return matches.every(Boolean);
+  } catch {
+    return false;
+  }
+}
+
+function mlOptions(mlAssetsUrl) {
+  return {
+    ...(mlAssetsUrl ? { assetBaseUrl: mlAssetsUrl } : {}),
+    modelFetchTimeoutMs: ML_MODEL_FETCH_TIMEOUT_MS,
+  };
+}
+
+// Resolves to the value of the promise, or to false after "ms" milliseconds
+// (0 means no limit). The promise itself goes on.
+function withTimeout(promise, ms) {
+  if (!ms || ms <= 0) {
+    return promise;
+  }
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
 // Returns the corners of the document or null when none is found.
@@ -28,19 +137,27 @@ export function preloadEngine() {
 // not as a retry, because on hard photos the classical detector does not
 // always fail: it can return a wrong shape (e.g. a line of text) as if it
 // were the document. The neural detector downloads about 2.2 MB with gzip
-// (3.5 MB uncompressed: model + ONNX runtime) the first time, from jsDelivr
-// unless mlAssetsUrl points to a self-hosted copy of the "scanic-ml" package
-// files. When it finds nothing or fails (e.g. no network), the classical
-// detector is used.
-export async function detectCorners(canvas, { ml = false, mlAssetsUrl = "" } = {}) {
+// (3.5 MB uncompressed: model + ONNX runtime) the first time (when the
+// scanner opens, see preloadEngine), from jsDelivr unless mlAssetsUrl points
+// to a self-hosted copy of the "scanic-ml" package files.
+//
+// The photo waits for the ML detector at most "mlMaxWait" milliseconds (0
+// means no limit). When it is not ready by then, it was skipped (see
+// mlFastConnectionOnly), it finds nothing or fails (e.g. no network), the
+// classical detector is used. The download goes on in the background, so a
+// later photo or the next open() can use it.
+export async function detectCorners(
+  canvas,
+  { ml = false, mlAssetsUrl = "", mlMaxWait = 0, mlFastConnectionOnly = false } = {},
+) {
   const { Scanner } = await loadScanic();
   scanner ??= new Scanner();
-  if (ml) {
+  if (ml && (await withTimeout(loadMl({ mlAssetsUrl, mlFastConnectionOnly }), mlMaxWait))) {
     try {
       const mlResult = await scanner.scan(canvas, {
         mode: "detect",
         detector: "ml",
-        ml: mlAssetsUrl ? { assetBaseUrl: mlAssetsUrl } : {},
+        ml: mlOptions(mlAssetsUrl),
       });
       if (mlResult.success) {
         return mlResult.corners;

package/test/scanner-test-helpers.js

@@ -135,7 +135,10 @@ export async function openScanner(attrs) {
 export const query = (el, selector) => el.shadowRoot.querySelector(selector);
 export const queryAll = (el, selector) => [...el.shadowRoot.querySelectorAll(selector)];
 export const button = (el, icon) => query(el, `.step:not([hidden]) dile-button[icon="lucide.${icon}"]`);
-export const pageButtons = (el, icon) => queryAll(el, `.page dile-button[icon="lucide.${icon}"]`);
+// Buttons of the page cards: the move arrows (dile-button in the header) and
+// the actions (native buttons with data-icon).
+export const pageButtons = (el, icon) =>
+  queryAll(el, `.page dile-button[icon="lucide.${icon}"], .page button[data-icon="lucide.${icon}"]`);
 export const pages = (el) => queryAll(el, '.page');
 export const errorMessage = (el) => query(el, '.message.error')?.textContent.trim();
 

package/vite-plugin.js

@@ -6,11 +6,19 @@
 //   import { scannerMlAssets } from '@dile/scanner/vite-plugin.js';
 //   export default { plugins: [scannerMlAssets()] };
 //
-//   <dile-scanner ml-detector ml-assets-url="/dile-scanner-ml/"></dile-scanner>
+//   // app code
+//   import { mlAssetsUrl } from 'virtual:dile-scanner-ml';
+//   scanner.mlAssetsUrl = mlAssetsUrl; // "/dile-scanner-ml/0.2.0/"
 //
 // The files are served by the dev server and copied to the build with their
 // original names (scanic expects them together in one folder). They are only
 // downloaded by the browser when the ML detector is actually used.
+//
+// The default folder includes the scanic-ml version, so updating
+// @dile/scanner changes the URL of the files. That way a cache (HTTP or a PWA
+// service worker) never mixes the model of one version with the runtime of
+// another. The "virtual:dile-scanner-ml" module exports the current URL, so
+// the app does not have to write the version by hand.
 import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { dirname, extname, join } from "node:path";
@@ -21,24 +29,54 @@ export const ML_ASSET_FILES = [
   "ort-wasm-simd-threaded.wasm",
 ];
 
+export const ML_VIRTUAL_MODULE = "virtual:dile-scanner-ml";
+const RESOLVED_VIRTUAL_MODULE = `\0${ML_VIRTUAL_MODULE}`;
+
 const CONTENT_TYPES = {
   ".ort": "application/octet-stream",
   ".mjs": "text/javascript",
   ".wasm": "application/wasm",
 };
 
+function mlPackageJson() {
+  const require = createRequire(import.meta.url);
+  return require.resolve("scanic-ml/package.json");
+}
+
 // Folder of the "scanic-ml" files, resolved from this package so it is the
 // version pinned by @dile/scanner.
 export function mlAssetsDir() {
-  const require = createRequire(import.meta.url);
-  return join(dirname(require.resolve("scanic-ml/package.json")), "dist");
+  return join(dirname(mlPackageJson()), "dist");
 }
 
-export function scannerMlAssets({ path = "dile-scanner-ml" } = {}) {
+// Version of the "scanic-ml" files (e.g. "0.2.0").
+export function mlAssetsVersion() {
+  return JSON.parse(readFileSync(mlPackageJson(), "utf8")).version;
+}
+
+export function scannerMlAssets({
+  path = `dile-scanner-ml/${mlAssetsVersion()}`,
+} = {}) {
   const folder = path.replace(/^\/+|\/+$/g, "");
   const assetsDir = mlAssetsDir();
+  let base = "/";
   return {
     name: "dile-scanner-ml-assets",
+    configResolved(config) {
+      base = config.base.endsWith("/") ? config.base : `${config.base}/`;
+    },
+    resolveId(id) {
+      return id === ML_VIRTUAL_MODULE ? RESOLVED_VIRTUAL_MODULE : null;
+    },
+    load(id) {
+      if (id !== RESOLVED_VIRTUAL_MODULE) {
+        return null;
+      }
+      return [
+        `export const mlAssetsUrl = ${JSON.stringify(`${base}${folder}/`)};`,
+        `export const mlAssetsVersion = ${JSON.stringify(mlAssetsVersion())};`,
+      ].join("\n");
+    },
     configureServer(server) {
       server.middlewares.use((req, res, next) => {
         const prefix = `${server.config.base}${folder}/`;