@tn3w/openage 1.0.4 → 1.0.6

package/README.md

@@ -16,11 +16,11 @@ button binding.
 
 ## At a Glance
 
-| Browser-side            | Server-backed              | UI                         |
-| ----------------------- | -------------------------- | -------------------------- |
-| On-device face analysis | Optional WASM verification | Embedded widget + popup    |
-| No raw camera upload    | Signed sessions and tokens | Normal, compact, invisible |
-| Serverless soft gates   | Hosted or custom backend   | Auto, light, dark          |
+| Browser-side            | Server-backed              | UI                               |
+| ----------------------- | -------------------------- | -------------------------------- |
+| On-device face analysis | Optional WASM verification | Widget popup, inline embed, bind |
+| No raw camera upload    | Signed sessions and tokens | Normal, compact, invisible       |
+| Serverless soft gates   | Hosted or custom backend   | Auto, light, dark                |
 
 ## Install
 
@@ -54,12 +54,27 @@ import OpenAge from '@tn3w/openage';
 
 OpenAge.render('#gate', {
     mode: 'serverless',
+    layout: 'inline',
     minAge: 18,
     callback: (token) => console.log(token),
     errorCallback: (error) => console.error(error),
 });
 ```
 
+### Inline Embed
+
+```js
+OpenAge.render('#gate', {
+    mode: 'serverless',
+    layout: 'inline',
+    minAge: 18,
+});
+```
+
+`layout: 'inline'` removes the checkbox shell and renders the verification
+panel directly in the container. The first verification step starts
+immediately after loading.
+
 ### Bound Flow
 
 ```js
@@ -95,11 +110,16 @@ OpenAge.execute(widgetId);
 await OpenAge.challenge(params);
 ```
 
+Runtime errors keep the popup open long enough to explain what happened.
+If no camera is available, OpenAge tells the user to plug one in and closes
+the popup automatically after 5 seconds.
+
 ## Main Params
 
 | Param     | Values                            |
 | --------- | --------------------------------- |
 | `mode`    | `serverless`, `sitekey`, `custom` |
+| `layout`  | `widget`, `inline`                |
 | `theme`   | `light`, `dark`, `auto`           |
 | `size`    | `normal`, `compact`, `invisible`  |
 | `minAge`  | number, default `18`              |
@@ -118,7 +138,7 @@ python server.py
 ```
 
 The repository also includes `demo/`, a minimal GitHub Pages build that loads
-the jsDelivr bundle for `@tn3w/openage` in embedded `serverless` mode.
+the jsDelivr bundle for `@tn3w/openage` in inline embedded `serverless` mode.
 
 ## Development
 

package/dist/openage.esm.js

@@ -541,6 +541,20 @@ const STYLES = `
   flex-direction: column;
 }
 
+.oa-inline-shell {
+  background: var(--oa-bg);
+  border: 1px solid var(--oa-border);
+  border-radius: var(--oa-radius);
+  box-shadow: 0 20px 60px rgba(0,0,0,0.18),
+    0 0 0 1px rgba(0,0,0,0.06);
+  width: min(100%, 360px);
+  max-width: 100%;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  margin: 0 auto;
+}
+
 .oa-modal-overlay {
   position: fixed;
   inset: 0;
@@ -893,6 +907,52 @@ const STYLES = `
 .oa-result-fail { color: var(--oa-danger); }
 .oa-result-retry { color: var(--oa-warn); }
 
+.oa-error-step {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.7rem;
+  padding: 2rem 1.2rem;
+  background: var(--oa-surface);
+  border: 1px solid var(--oa-border);
+  border-radius: var(--oa-radius);
+  margin: 10px;
+  animation: oa-fade-in 0.4s ease;
+  text-align: center;
+}
+
+.oa-error-step-icon {
+  width: 3rem;
+  height: 3rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 999px;
+  background: rgba(239, 68, 68, 0.12);
+  color: var(--oa-danger);
+  font-size: 1.7rem;
+  line-height: 1;
+}
+
+.oa-error-step-title {
+  font-size: 1rem;
+  font-weight: 700;
+  color: var(--oa-text);
+}
+
+.oa-error-step-message {
+  font-size: 0.84rem;
+  line-height: 1.5;
+  color: var(--oa-text-muted);
+  max-width: 260px;
+}
+
+.oa-error-step-countdown {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--oa-danger);
+}
+
 .oa-hidden { display: none !important; }
 
 /* ── Animations ──────────────────────────────── */
@@ -1019,6 +1079,17 @@ function challengeTemplate() {
   `;
 }
 
+function errorStepTemplate(message) {
+    return `
+    <div class="oa-error-step">
+      <div class="oa-error-step-icon">✕</div>
+      <div class="oa-error-step-title">Verification stopped</div>
+      <div class="oa-error-step-message">${message}</div>
+      <div class="oa-error-step-countdown"></div>
+    </div>
+  `;
+}
+
 function resultTemplate(outcome, message) {
     const icons = {
         fail: '✕',
@@ -1040,7 +1111,7 @@ function resultTemplate(outcome, message) {
 
 const VERSION = '1.0.0';
 
-const MEDIAPIPE_CDN = 'https://cdn.jsdelivr.net/npm/' + '@mediapipe/tasks-vision@0.10.17';
+const MEDIAPIPE_CDN = 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.17';
 
 const MEDIAPIPE_WASM = `${MEDIAPIPE_CDN}/wasm`;
 
@@ -1051,13 +1122,13 @@ const MEDIAPIPE_MODEL =
     'face_landmarker/face_landmarker/float16/1/' +
     'face_landmarker.task';
 
-const FACEAPI_CDN =
-    'https://cdn.jsdelivr.net/npm/' + 'face-api.js@0.22.2/dist/face-api.min.js';
+const FACEAPI_CDN = 'https://cdn.jsdelivr.net/npm/face-api.js@0.22.2/dist/face-api.min.js';
 
 const FACEAPI_MODEL_CDN =
-    'https://cdn.jsdelivr.net/gh/' + 'justadudewhohacks/face-api.js@master/weights';
+    'https://cdn.jsdelivr.net/gh/justadudewhohacks/face-api.js@master/weights';
 
 const MAX_RETRIES = 3;
+const ERROR_STEP_SECONDS = 5;
 const BURST_FRAMES = 5;
 const BURST_INTERVAL_MS = 200;
 const POSITION_CHECK_MS = 100;
@@ -1088,6 +1159,7 @@ class Widget {
         this.popup = null;
         this.shadow = null;
         this.elements = {};
+        this.popupElements = null;
         this.onChallenge = null;
         this.onStartClick = null;
         this.popupFrame = 0;
@@ -1100,6 +1172,7 @@ class Widget {
         const host = document.createElement('div');
         host.id = this.id;
         this.shadow = host.attachShadow({ mode: 'open' });
+        this.host = host;
 
         const style = document.createElement('style');
         style.textContent = STYLES;
@@ -1112,7 +1185,12 @@ class Widget {
         if (this.params.size === 'invisible') {
             host.style.display = 'none';
             this.container.appendChild(host);
-            this.host = host;
+            return;
+        }
+
+        if (this.isInlineLayout()) {
+            this.renderInlineShell();
+            this.container.appendChild(host);
             return;
         }
 
@@ -1148,7 +1226,32 @@ class Widget {
         this.elements.errorSlot = this.shadow.querySelector('.oa-error-slot');
 
         this.container.appendChild(host);
-        this.host = host;
+    }
+
+    isInlineLayout() {
+        return this.params.layout === 'inline';
+    }
+
+    renderInlineShell() {
+        const inlineShell = document.createElement('div');
+        inlineShell.className = 'oa-inline-shell';
+        inlineShell.innerHTML = this.buildPopupContent({ closeable: false });
+        this.shadow.appendChild(inlineShell);
+
+        this.popup = {
+            host: this.host,
+            root: inlineShell,
+            inline: true,
+        };
+
+        this.bindPopupEvents(inlineShell);
+    }
+
+    resetInlineShell() {
+        if (!this.popup?.root) return;
+
+        this.popup.root.innerHTML = this.buildPopupContent({ closeable: false });
+        this.bindPopupEvents(this.popup.root);
     }
 
     startChallenge() {
@@ -1181,6 +1284,14 @@ class Widget {
     }
 
     openPopup() {
+        if (this.isInlineLayout()) {
+            if (!this.popup) {
+                this.renderInlineShell();
+            }
+
+            return this.getVideo();
+        }
+
         if (this.popup) return this.getVideo();
 
         const anchor = this.getPopupAnchor();
@@ -1358,7 +1469,7 @@ class Widget {
         this.popup.root.style.pointerEvents = 'auto';
     }
 
-    buildPopupContent() {
+    buildPopupContent({ closeable = true } = {}) {
         return `
       <div class="oa-header">
         <div class="oa-title">
@@ -1369,10 +1480,14 @@ class Widget {
           </a>
           <span class="oa-badge">on-device</span>
         </div>
-        <button class="oa-close-btn"
-          aria-label="Close">
-          ${CLOSE_SVG}
-        </button>
+                ${
+                    closeable
+                        ? `<button class="oa-close-btn"
+                    aria-label="Close">
+                    ${CLOSE_SVG}
+                </button>`
+                        : ''
+                }
       </div>
       <div class="oa-body">
         ${heroTemplate('Initializing…')}
@@ -1385,7 +1500,7 @@ class Widget {
     `;
     }
 
-    bindPopupEvents(root, shadow) {
+    bindPopupEvents(root) {
         const closeBtn = root.querySelector('.oa-close-btn');
         if (closeBtn) {
             closeBtn.addEventListener('click', () => {
@@ -1503,6 +1618,22 @@ class Widget {
     }
 
     showResult(outcome, message) {
+        if (this.isInlineLayout()) {
+            if (!this.popupElements?.body) return;
+
+            this.popupElements.body.innerHTML = resultTemplate(outcome, message);
+            this.hideActions();
+
+            if (outcome === 'pass') {
+                this.setState('verified');
+                return;
+            }
+
+            this.setState(outcome === 'fail' ? 'failed' : 'retry');
+            this.showActions('Try Again');
+            return;
+        }
+
         if (outcome === 'pass') {
             this.closePopup();
             this.setState('verified');
@@ -1538,8 +1669,21 @@ class Widget {
         }
     }
 
-    showError() {
-        this.setState('retry');
+    showError(message) {
+        if (!this.popupElements?.body) return;
+
+        this.popupElements.body.innerHTML = errorStepTemplate(message);
+        this.popupElements.errorCountdown = this.popupElements.body.querySelector(
+            '.oa-error-step-countdown'
+        );
+        this.hideActions();
+    }
+
+    setErrorCountdown(seconds) {
+        if (!this.popupElements?.errorCountdown) return;
+
+        const unit = seconds === 1 ? 'second' : 'seconds';
+        this.popupElements.errorCountdown.textContent = `Closing in ${seconds} ${unit}…`;
     }
 
     clearError() {
@@ -1550,6 +1694,22 @@ class Widget {
 
     closePopup() {
         if (!this.popup) return;
+
+        if (this.popup.inline) {
+            this.popup.cleanup?.();
+            if (this.popupFrame) {
+                cancelAnimationFrame(this.popupFrame);
+                this.popupFrame = 0;
+            }
+            this.resetInlineShell();
+
+            if (this.state === 'loading') {
+                this.setState('idle');
+            }
+
+            return;
+        }
+
         this.popup.cleanup?.();
         this.popup.themeCleanup?.();
         this.popup.host.remove();
@@ -2717,6 +2877,73 @@ function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
 
+function resolveChallengeErrorMessage(error) {
+    const name = typeof error?.name === 'string' ? error.name : '';
+    const message = typeof error?.message === 'string' ? error.message : String(error || '');
+    const normalized = `${name} ${message}`.toLowerCase();
+
+    if (
+        name === 'NotFoundError' ||
+        /request is not allowed by the user agent or the platform in the current context/.test(
+            normalized
+        ) ||
+        /requested device not found|device not found|no camera|could not start video source/.test(
+            normalized
+        )
+    ) {
+        return 'No camera available. Plug in a camera and try again.';
+    }
+
+    if (
+        name === 'NotAllowedError' ||
+        name === 'PermissionDeniedError' ||
+        /permission|camera access|access denied/.test(normalized)
+    ) {
+        return 'Camera access was blocked. Allow camera access and try again.';
+    }
+
+    if (/positioning timeout/.test(normalized)) {
+        return 'Face positioning timed out. Reopen the check and try again.';
+    }
+
+    return 'Verification failed. Please try again.';
+}
+
+function isInlineLayout(widget) {
+    return widget?.params?.layout === 'inline';
+}
+
+async function showErrorStep(widget, error) {
+    const message = resolveChallengeErrorMessage(error);
+
+    if (isInlineLayout(widget)) {
+        widget.showResult?.('retry', message);
+        return;
+    }
+
+    if (!widget.popup) {
+        widget.openPopup?.();
+    }
+
+    widget.showError?.(message);
+
+    for (let seconds = ERROR_STEP_SECONDS; seconds > 0; seconds--) {
+        if (!widget.popup) break;
+        widget.setErrorCountdown?.(seconds);
+        await sleep(1000);
+    }
+
+    widget.closePopup?.();
+    widget.setState?.('retry');
+}
+
+async function handleChallengeError(widget, emitter, error) {
+    console.log('Error during challenge:', error);
+    await showErrorStep(widget, error);
+    emitter.emit('error', error, widget.id);
+    widget.params.errorCallback?.(error);
+}
+
 async function runChallenge(widget, emitter) {
     const mode = widget.params.mode || 'serverless';
 
@@ -2746,10 +2973,14 @@ async function runServerless(widget, emitter) {
         await Promise.all([loadVision(), initAgeEstimator()]);
 
         modelBuffer = await loadModel();
-        widget.showReady();
 
-        await waitForStart(widget);
-        await startCameraFlow(widget, modelBuffer);
+        if (isInlineLayout(widget)) {
+            await startCameraFlow(widget, modelBuffer);
+        } else {
+            widget.showReady();
+            await waitForStart(widget);
+            await startCameraFlow(widget, modelBuffer);
+        }
 
         const transport = createTransport('serverless', params);
 
@@ -2797,10 +3028,7 @@ async function runServerless(widget, emitter) {
         emitResult(widget, emitter, result);
     } catch (error) {
         cleanupLocal();
-        console.log('Error during challenge:', error);
-        widget.showResult('fail', 'Verification failed');
-        emitter.emit('error', error, widget.id);
-        params.errorCallback?.(error);
+        await handleChallengeError(widget, emitter, error);
     }
 }
 
@@ -2841,10 +3069,16 @@ async function runServer(widget, emitter) {
             captureFrame: () => (captureFrame() ? 'true' : 'null'),
         });
 
-        widget.showReady();
-        await waitForStart(widget);
+        let video;
+
+        if (isInlineLayout(widget)) {
+            video = widget.showCamera();
+        } else {
+            widget.showReady();
+            await waitForStart(widget);
+            video = widget.showCamera();
+        }
 
-        const video = widget.showCamera();
         widget.setVideoStatus('Requesting camera…');
         await startCamera(video);
         exposeMirrorVideo(video);
@@ -2931,11 +3165,8 @@ async function runServer(widget, emitter) {
 
         cleanupVM(transport);
     } catch (error) {
-        console.log('Error during challenge:', error);
         cleanupVM();
-        widget.showResult('fail', 'Verification failed');
-        emitter.emit('error', error, widget.id);
-        params.errorCallback?.(error);
+        await handleChallengeError(widget, emitter, error);
     }
 }
 
@@ -3150,8 +3381,19 @@ class EventEmitter {
 const emitter = new EventEmitter();
 const widgets = new Map();
 
+function normalizeLayout(layout) {
+    if (layout === 'inline' || layout === 'embed' || layout === 'embedded') {
+        return 'inline';
+    }
+
+    return 'widget';
+}
+
 function normalizeParams(params) {
     const globalConfig = typeof window !== 'undefined' ? window.openage || {} : {};
+    const layout = normalizeLayout(
+        params.layout ?? params.display ?? globalConfig.layout ?? globalConfig.display
+    );
 
     return {
         mode: 'serverless',
@@ -3160,6 +3402,7 @@ function normalizeParams(params) {
         minAge: 18,
         ...globalConfig,
         ...params,
+        layout,
     };
 }
 
@@ -3168,6 +3411,10 @@ function startWidget(widget) {
         emitter.emit('opened', widget.id);
         runChallenge(widget, emitter);
     };
+
+    if (widget.params.layout === 'inline') {
+        widget.startChallenge();
+    }
 }
 
 function render(container, params = {}) {
@@ -3316,6 +3563,7 @@ function autoRender() {
             size: element.dataset.size,
             action: element.dataset.action,
             mode: element.dataset.mode,
+            layout: element.dataset.layout || element.dataset.display,
             server: element.dataset.server,
         };