User:Jono Bean/common.js: Difference between revisions

From DQWiki
Jump to navigationJump to search
mNo edit summary
mNo edit summary
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
# DQ Media Wiki Lorekeeper Widget
/* Lorekeeper Widget Loader - v1.2.6 (MediaWiki ES5 loader) */
 
This note documents how the DQ Media Wiki widget is loaded from MediaWiki, what the current `common.js` script does, how the iframe talks to NPC Forge, and what changed in the recent hardening work.
 
## Where the MediaWiki code lives
 
For Jono Bean, the active widget loader is currently in:
 
- `https://dq-nz.org/dqwiki/index.php/User:Jono_Bean/common.js`
 
This means the widget is user-scoped rather than site-wide. Only that logged-in user sees it unless the same code is copied into a site script such as `MediaWiki:Common.js` or a gadget.
 
## Current MediaWiki loader shape
 
The wiki-side script:
 
1. Reads the logged-in MediaWiki username with `mw.config.get('wgUserName')`
2. Detects whether the parent wiki viewport is mobile
3. Builds an iframe URL pointing at:
  - `https://npc-forge--npc-forge-qh4gc.asia-southeast1.hosted.app/widget`
4. Passes either:
  - `user=<wiki username>`
  - or `guest=Traveler`
5. Passes `isMobile=true` when the wiki viewport is narrow
6. Creates a fixed-position iframe container in the bottom-right corner
7. Listens for `postMessage` events from the NPC Forge widget and resizes the iframe when the widget opens, closes, or changes layout
 
## Recommended MediaWiki `common.js`
 
This is the current recommended loader script for the DQ Media Wiki user script:
 
```javascript
/* Lorekeeper Widget Loader - v1.2.0 (MediaWiki polished loader) */
(function () {
(function () {
     'use strict';
     'use strict';


     var CONFIG = {
     var CONFIG = {
         appOrigin: 'https://npc-forge--npc-forge-qh4gc.asia-southeast1.hosted.app',
         appOrigin: 'https://npc-forge-6mvsrbhsoq-as.a.run.app',
         widgetPath: '/widget',
         widgetPath: '/widget',
         containerId: 'lorekeeper-widget-container',
         containerId: 'lorekeeper-widget-container',
Line 42: Line 10:
         mobileBreakpoint: 768,
         mobileBreakpoint: 768,
         edgeGap: 16,
         edgeGap: 16,
         desktopCollapsed: { width: 300, height: 120 },
         desktopCollapsed: { width: 360, height: 150 },
         mobileCollapsed: { width: 80, height: 80 },
         mobileCollapsed: { width: 96, height: 96 },
         desktopMax: { width: 720, height: 720 },
        desktopOpen: { width: 1120, height: 760 },
         desktopMin: { width: 300, height: 120 },
        desktopHistoryOpen: { width: 1280, height: 760 },
         zIndex: 99999,
         desktopMax: { width: 1280, height: 820 },
        debug: false
         desktopMin: { width: 360, height: 150 },
         zIndex: 99999
     };
     };


Line 59: Line 28:
         lastMode: null
         lastMode: null
     };
     };
    function log() {
        if (!CONFIG.debug || !window.console) return;
        window.console.log.apply(window.console, ['[Lorekeeper Widget]'].concat([].slice.call(arguments)));
    }


     function isMobileViewport() {
     function isMobileViewport() {
Line 83: Line 47:


     function buildWidgetUrl() {
     function buildWidgetUrl() {
        var url = new URL(CONFIG.widgetPath, CONFIG.appOrigin);
         var username = getMediaWikiUsername();
         var username = getMediaWikiUsername();
        var params = [];


         if (username) {
         if (username) {
             url.searchParams.set('user', username);
             params.push('user=' + encodeURIComponent(username));
         } else {
         } else {
             url.searchParams.set('guest', 'Traveler');
             params.push('guest=Traveler');
         }
         }


         url.searchParams.set('isMobile', isMobileViewport() ? 'true' : 'false');
         params.push('isMobile=' + (isMobileViewport() ? 'true' : 'false'));
         url.searchParams.set('parentOrigin', window.location.origin);
         params.push('parentOrigin=' + encodeURIComponent(window.location.protocol + '//' + window.location.host));
         return url.toString();
        params.push('loaderVersion=' + encodeURIComponent('1.2.6'));
 
         return CONFIG.appOrigin + CONFIG.widgetPath + '?' + params.join('&');
     }
     }


Line 103: Line 69:
     function clampNumber(value, min, max) {
     function clampNumber(value, min, max) {
         return Math.max(min, Math.min(max, value));
         return Math.max(min, Math.min(max, value));
    }
    function isFiniteNumber(value) {
        return typeof value === 'number' && isFinite(value);
     }
     }


Line 110: Line 80:


             var parsed = parseFloat(value);
             var parsed = parseFloat(value);
             if (!Number.isFinite(parsed)) return null;
             if (!isFiniteNumber(parsed)) return null;
             value = parsed;
             value = parsed;
         }
         }


         if (typeof value !== 'number' || !Number.isFinite(value)) return null;
         if (!isFiniteNumber(value)) return null;


         if (isMobileViewport()) {
         if (isMobileViewport()) {
Line 130: Line 100:


     function setStyles(element, styles) {
     function setStyles(element, styles) {
         Object.keys(styles).forEach(function (key) {
         var key;
            element.style[key] = styles[key];
        for (key in styles) {
         });
            if (styles.hasOwnProperty(key)) {
                element.style[key] = styles[key];
            }
         }
     }
     }


Line 161: Line 134:
             maxWidth: '100vw',
             maxWidth: '100vw',
             maxHeight: '100vh',
             maxHeight: '100vh',
             transition: window.matchMedia('(prefers-reduced-motion: reduce)').matches
             transition: 'width 180ms ease, height 180ms ease'
                ? 'none'
                : 'width 180ms ease, height 180ms ease'
         });
         });


Line 178: Line 149:
         iframe.setAttribute('loading', 'lazy');
         iframe.setAttribute('loading', 'lazy');
         iframe.setAttribute('referrerpolicy', 'strict-origin-when-cross-origin');
         iframe.setAttribute('referrerpolicy', 'strict-origin-when-cross-origin');
        iframe.setAttribute('scrolling', 'no');
        iframe.setAttribute('allowtransparency', 'true');
         iframe.setAttribute('data-mode', currentMode());
         iframe.setAttribute('data-mode', currentMode());


Line 187: Line 160:
             padding: '0',
             padding: '0',
             margin: '0',
             margin: '0',
            overflow: 'hidden',
             background: 'transparent',
             background: 'transparent',
             colorScheme: 'normal',
             colorScheme: 'normal',
Line 219: Line 193:
         state.lastMode = currentMode();
         state.lastMode = currentMode();
         state.mounted = true;
         state.mounted = true;
        log('mounted', state.lastMode);
         return true;
         return true;
    }
    function looksLikeOpenSize(width, height) {
        if (isMobileViewport()) return width === '100vw' || height === '100vh';
        var parsedWidth = typeof width === 'number' ? width : parseFloat(width);
        var parsedHeight = typeof height === 'number' ? height : parseFloat(height);
        return isFiniteNumber(parsedWidth)
            && isFiniteNumber(parsedHeight)
            && (parsedWidth > CONFIG.desktopCollapsed.width || parsedHeight > CONFIG.desktopCollapsed.height);
    }
    function resolveRequestedSize(width, height) {
        if (isMobileViewport()) {
            return { width: width, height: height };
        }
        if (!looksLikeOpenSize(width, height)) {
            return { width: width, height: height };
        }
        var parsedWidth = typeof width === 'number' ? width : parseFloat(width);
        var wantsHistory = isFiniteNumber(parsedWidth) && parsedWidth >= 900;
        return wantsHistory ? CONFIG.desktopHistoryOpen : CONFIG.desktopOpen;
     }
     }


Line 227: Line 225:
         if (!container) return;
         if (!container) return;


         var nextWidth = normalizeSize(width, 'width');
        var requestedSize = resolveRequestedSize(width, height);
         var nextHeight = normalizeSize(height, 'height');
         var nextWidth = normalizeSize(requestedSize.width, 'width');
         var nextHeight = normalizeSize(requestedSize.height, 'height');


         if (nextWidth) container.style.width = nextWidth;
         if (nextWidth) container.style.width = nextWidth;
Line 260: Line 259:
             iframe.src = buildWidgetUrl();
             iframe.src = buildWidgetUrl();
             setCollapsedSize(container);
             setCollapsedSize(container);
            log('mode changed', nextMode);
             return;
             return;
         }
         }
Line 298: Line 296:


         window.__lorekeeperWidgetLoader = {
         window.__lorekeeperWidgetLoader = {
             version: '1.2.0',
             version: '1.2.6',
             refresh: refreshForViewport,
             refresh: refreshForViewport,
             destroy: destroy
             destroy: destroy
Line 305: Line 303:


     if (document.readyState === 'loading') {
     if (document.readyState === 'loading') {
         document.addEventListener('DOMContentLoaded', init, { once: true });
         document.addEventListener('DOMContentLoaded', init, false);
     } else {
     } else {
         init();
         init();
     }
     }
})();
})();
```
## What the app expects from MediaWiki
The widget route now expects these query params from the wiki loader:
- `user`
  - preferred when MediaWiki has a logged-in user
- `guest`
  - fallback display/storage identity when no logged-in user exists
- `isMobile=true`
  - tells the iframe to start in mobile layout
- `parentOrigin`
  - used by the iframe so resize messages can target the wiki origin more safely
The widget app normalizes `user` and `guest` before using them for local guest storage and the header badge.
## Iframe message contract
The NPC Forge widget sends this message back to the parent page:
```json
{
  "type": "lorekeeper-resize",
  "width": 700,
  "height": 650
}
```
Or on mobile:
```json
{
  "type": "lorekeeper-resize",
  "width": "100vw",
  "height": "100vh"
}
```
The wiki loader should:
- check `event.origin`
- check `event.data.type === 'lorekeeper-resize'`
- apply the new width and height to the fixed widget container
## Recent widget fixes
The NPC Forge side was recently hardened in these areas:
1. Transparent embed shell
  - removed the large grey iframe background slab behind the Lorekeeper card
2. Safer widget identity handling
  - `user` and `guest` values are trimmed, normalized, and bounded before use
3. Better widget API routing
  - external hosts like the DQ Media Wiki now resolve the correct absolute API base more safely
  - local/private hosts no longer get mistaken for production external embeds
4. Safer widget messaging
  - `parentOrigin` is supported for stricter `postMessage` targeting
5. Cleaner widget error reporting
  - widget requests no longer retry the same endpoint and then misreport the failure as a fake fallback error
6. Polished MediaWiki loader paste script
  - v1.2.0 keeps all tweakable values in one `CONFIG` block
  - uses `URL` / `searchParams` instead of hand-built query strings
  - verifies both message origin and iframe message source before resizing
  - clamps desktop resize requests to the viewport so the widget cannot sprawl off-screen
  - debounces viewport resize handling and reloads the iframe only when crossing the mobile breakpoint
  - exposes `window.__lorekeeperWidgetLoader.refresh()` and `.destroy()` for live wiki debugging
## Capacity handling
Originally, the MediaWiki widget was competing against the global AI cap used by all app features. That meant a low setting like `2` active runs could make the wiki widget fail even when only a couple of unrelated AI jobs were running elsewhere.
The runtime controls now support a separate widget bucket:
- `maxActiveRuns`
  - global shared cap for normal app AI traffic
- `mediaWikiWidgetMaxActiveRuns`
  - dedicated cap for `sourceApp === "MediaWiki Widget"`
Default widget capacity now falls back to:
- `MEDIAWIKI_WIDGET_MAX_ACTIVE_RUNS=12`
If widget traffic hits its own limit, the user will now get a widget-specific capacity message instead of competing directly with all other AI routes.
## Where the source lives in NPC Forge
Relevant app files:
- [widget/page.tsx](/C:/Antigravity/npc-forge-app/src/app/widget/page.tsx)
- [lorekeeper-widget.tsx](/C:/Antigravity/npc-forge-app/src/components/lorekeeper-widget.tsx)
- [lore-page-client.tsx](/C:/Antigravity/npc-forge-app/src/components/lore-page-client.tsx)
- [lore-widget.ts](/C:/Antigravity/npc-forge-app/src/lib/lore-widget.ts)
- [ai-runtime-controls.service.ts](/C:/Antigravity/npc-forge-app/src/services/ai-runtime-controls.service.ts)
- [askLore route.ts](/C:/Antigravity/npc-forge-app/src/app/api/askLore/route.ts)
## Troubleshooting checklist
If the widget breaks on the wiki:
1. Check `User:Jono_Bean/common.js`
  - confirm the iframe URL is correct
  - confirm `parentOrigin` is being passed
2. Check browser console on the wiki page
  - look for blocked iframe or CSP errors
  - look for failed message-origin checks
3. Check widget network calls
  - `/api/askLore`
  - `/api/lore/stream`
4. If errors mention capacity
  - inspect active `system_runs`
  - inspect `system_ai_leases`
  - compare global `maxActiveRuns` vs `mediaWikiWidgetMaxActiveRuns`
5. If the widget background looks wrong
  - verify widget route transparency fixes are present
  - verify the iframe container itself does not set a non-transparent background
## Readiness smoke
Run the combined Discord/widget readiness gate before marking the widget code ready for testing:
```text
npm run discord-widget:readiness -- -- --write docs/discord-widget-readiness-YYYY-MM-DD.md --live
```
This checks the `/widget` route contract, `parentOrigin`/`lorekeeper-resize` messaging, the Discord Cloud Tasks route contract, current env/runbook docs, typecheck, and a live hosted `/widget` HTML response. The stricter Discord endpoint check is separate and can be run after deployment with `--live-discord`.
## Suggested next admin improvement
Add an admin panel that shows both:
- global active AI runs
- MediaWiki widget active AI runs
That would make it much easier to see whether the widget is saturated, whether a run is stale, and whether the global cap or widget cap is the real bottleneck.

Latest revision as of 06:00, 26 May 2026

/* Lorekeeper Widget Loader - v1.2.6 (MediaWiki ES5 loader) */
(function () {
    'use strict';

    var CONFIG = {
        appOrigin: 'https://npc-forge-6mvsrbhsoq-as.a.run.app',
        widgetPath: '/widget',
        containerId: 'lorekeeper-widget-container',
        iframeId: 'lorekeeper-widget-frame',
        mobileBreakpoint: 768,
        edgeGap: 16,
        desktopCollapsed: { width: 360, height: 150 },
        mobileCollapsed: { width: 96, height: 96 },
        desktopOpen: { width: 1120, height: 760 },
        desktopHistoryOpen: { width: 1280, height: 760 },
        desktopMax: { width: 1280, height: 820 },
        desktopMin: { width: 360, height: 150 },
        zIndex: 99999
    };

    if (window.__lorekeeperWidgetLoader && window.__lorekeeperWidgetLoader.version) {
        return;
    }

    var state = {
        mounted: false,
        resizeTimer: 0,
        lastMode: null
    };

    function isMobileViewport() {
        return window.innerWidth < CONFIG.mobileBreakpoint;
    }

    function currentMode() {
        return isMobileViewport() ? 'mobile' : 'desktop';
    }

    function getMediaWikiUsername() {
        try {
            if (!window.mw || !window.mw.config) return '';
            return String(window.mw.config.get('wgUserName') || '').trim();
        } catch (err) {
            return '';
        }
    }

    function buildWidgetUrl() {
        var username = getMediaWikiUsername();
        var params = [];

        if (username) {
            params.push('user=' + encodeURIComponent(username));
        } else {
            params.push('guest=Traveler');
        }

        params.push('isMobile=' + (isMobileViewport() ? 'true' : 'false'));
        params.push('parentOrigin=' + encodeURIComponent(window.location.protocol + '//' + window.location.host));
        params.push('loaderVersion=' + encodeURIComponent('1.2.6'));

        return CONFIG.appOrigin + CONFIG.widgetPath + '?' + params.join('&');
    }

    function px(value) {
        return Math.round(value) + 'px';
    }

    function clampNumber(value, min, max) {
        return Math.max(min, Math.min(max, value));
    }

    function isFiniteNumber(value) {
        return typeof value === 'number' && isFinite(value);
    }

    function normalizeSize(value, axis) {
        if (typeof value === 'string') {
            if (value === '100vw' || value === '100vh') return value;

            var parsed = parseFloat(value);
            if (!isFiniteNumber(parsed)) return null;
            value = parsed;
        }

        if (!isFiniteNumber(value)) return null;

        if (isMobileViewport()) {
            return axis === 'width' ? '100vw' : '100vh';
        }

        var viewportLimit = axis === 'width'
            ? window.innerWidth - (CONFIG.edgeGap * 2)
            : window.innerHeight - (CONFIG.edgeGap * 2);
        var min = CONFIG.desktopMin[axis];
        var max = Math.min(CONFIG.desktopMax[axis], viewportLimit);

        return px(clampNumber(value, min, Math.max(min, max)));
    }

    function setStyles(element, styles) {
        var key;
        for (key in styles) {
            if (styles.hasOwnProperty(key)) {
                element.style[key] = styles[key];
            }
        }
    }

    function setCollapsedSize(container) {
        var size = isMobileViewport() ? CONFIG.mobileCollapsed : CONFIG.desktopCollapsed;
        setStyles(container, {
            width: px(size.width),
            height: px(size.height)
        });
    }

    function createContainer() {
        var container = document.createElement('div');
        container.id = CONFIG.containerId;
        container.setAttribute('data-lorekeeper-widget', 'true');

        setStyles(container, {
            position: 'fixed',
            right: isMobileViewport() ? '0' : px(CONFIG.edgeGap),
            bottom: isMobileViewport() ? '0' : px(CONFIG.edgeGap),
            zIndex: String(CONFIG.zIndex),
            pointerEvents: 'none',
            overflow: 'hidden',
            background: 'transparent',
            border: '0',
            padding: '0',
            margin: '0',
            maxWidth: '100vw',
            maxHeight: '100vh',
            transition: 'width 180ms ease, height 180ms ease'
        });

        setCollapsedSize(container);
        return container;
    }

    function createIframe() {
        var iframe = document.createElement('iframe');
        iframe.id = CONFIG.iframeId;
        iframe.title = 'NPC Forge Lorekeeper';
        iframe.src = buildWidgetUrl();
        iframe.setAttribute('allow', 'clipboard-write');
        iframe.setAttribute('loading', 'lazy');
        iframe.setAttribute('referrerpolicy', 'strict-origin-when-cross-origin');
        iframe.setAttribute('scrolling', 'no');
        iframe.setAttribute('allowtransparency', 'true');
        iframe.setAttribute('data-mode', currentMode());

        setStyles(iframe, {
            display: 'block',
            width: '100%',
            height: '100%',
            border: '0',
            padding: '0',
            margin: '0',
            overflow: 'hidden',
            background: 'transparent',
            colorScheme: 'normal',
            pointerEvents: 'auto'
        });

        return iframe;
    }

    function ensureMounted() {
        if (!document.body) return false;

        var container = document.getElementById(CONFIG.containerId);
        var iframe = document.getElementById(CONFIG.iframeId);

        if (!container) {
            container = createContainer();
        }

        if (!iframe) {
            iframe = createIframe();
        }

        if (iframe.parentNode !== container) {
            container.appendChild(iframe);
        }

        if (container.parentNode !== document.body) {
            document.body.appendChild(container);
        }

        state.lastMode = currentMode();
        state.mounted = true;
        return true;
    }

    function looksLikeOpenSize(width, height) {
        if (isMobileViewport()) return width === '100vw' || height === '100vh';

        var parsedWidth = typeof width === 'number' ? width : parseFloat(width);
        var parsedHeight = typeof height === 'number' ? height : parseFloat(height);

        return isFiniteNumber(parsedWidth)
            && isFiniteNumber(parsedHeight)
            && (parsedWidth > CONFIG.desktopCollapsed.width || parsedHeight > CONFIG.desktopCollapsed.height);
    }

    function resolveRequestedSize(width, height) {
        if (isMobileViewport()) {
            return { width: width, height: height };
        }

        if (!looksLikeOpenSize(width, height)) {
            return { width: width, height: height };
        }

        var parsedWidth = typeof width === 'number' ? width : parseFloat(width);
        var wantsHistory = isFiniteNumber(parsedWidth) && parsedWidth >= 900;
        return wantsHistory ? CONFIG.desktopHistoryOpen : CONFIG.desktopOpen;
    }

    function applyResize(width, height) {
        var container = document.getElementById(CONFIG.containerId);
        if (!container) return;

        var requestedSize = resolveRequestedSize(width, height);
        var nextWidth = normalizeSize(requestedSize.width, 'width');
        var nextHeight = normalizeSize(requestedSize.height, 'height');

        if (nextWidth) container.style.width = nextWidth;
        if (nextHeight) container.style.height = nextHeight;

        container.style.right = isMobileViewport() ? '0' : px(CONFIG.edgeGap);
        container.style.bottom = isMobileViewport() ? '0' : px(CONFIG.edgeGap);
    }

    function handleMessage(event) {
        var iframe = document.getElementById(CONFIG.iframeId);
        if (event.origin !== CONFIG.appOrigin) return;
        if (iframe && event.source !== iframe.contentWindow) return;
        if (!event.data || event.data.type !== 'lorekeeper-resize') return;

        applyResize(event.data.width, event.data.height);
    }

    function refreshForViewport() {
        var container = document.getElementById(CONFIG.containerId);
        var iframe = document.getElementById(CONFIG.iframeId);
        if (!container || !iframe) return;

        var nextMode = currentMode();
        container.style.right = nextMode === 'mobile' ? '0' : px(CONFIG.edgeGap);
        container.style.bottom = nextMode === 'mobile' ? '0' : px(CONFIG.edgeGap);

        if (nextMode !== state.lastMode) {
            state.lastMode = nextMode;
            iframe.setAttribute('data-mode', nextMode);
            iframe.src = buildWidgetUrl();
            setCollapsedSize(container);
            return;
        }

        if (container.style.width === '100vw' || container.style.height === '100vh') {
            applyResize(container.style.width, container.style.height);
        }
    }

    function handleWindowResize() {
        window.clearTimeout(state.resizeTimer);
        state.resizeTimer = window.setTimeout(refreshForViewport, 120);
    }

    function destroy() {
        window.clearTimeout(state.resizeTimer);
        window.removeEventListener('message', handleMessage, false);
        window.removeEventListener('resize', handleWindowResize, false);

        var container = document.getElementById(CONFIG.containerId);
        if (container && container.parentNode) {
            container.parentNode.removeChild(container);
        }

        state.mounted = false;
        window.__lorekeeperWidgetLoader = null;
    }

    function init() {
        if (!ensureMounted()) {
            window.setTimeout(init, 50);
            return;
        }

        window.addEventListener('message', handleMessage, false);
        window.addEventListener('resize', handleWindowResize, false);

        window.__lorekeeperWidgetLoader = {
            version: '1.2.6',
            refresh: refreshForViewport,
            destroy: destroy
        };
    }

    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', init, false);
    } else {
        init();
    }
})();