@readium/navigator-html-injectables 2.4.3 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/navigator-html-injectables",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "type": "module",
   "description": "An embeddable solution for connecting frames of HTML publications with a Readium Navigator",
   "author": "readium",
@@ -54,6 +54,7 @@
     "rimraf": "^6.1.2",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
+    "user-agent-data-types": "^0.4.2",
     "vite": "^7.3.1"
   }
 }

package/src/comms/keys.ts

@@ -20,8 +20,8 @@ export type CommsEventKey =
     "media_play" |
     "media_pause" |
     "content_protection" |
-    "keyboard_peripherals";
-;
+    "keyboard_peripherals" |
+    "decoration_activated";
 
 export type CommsCommandKey =
     "_ping" |
@@ -39,6 +39,7 @@ export type CommsCommandKey =
     // "exact_progress" |
     "first_visible_locator" |
     "decorate" |
+    "decoration_activatable" |
     "protect" |
     "unprotect" |
     "unfocus" |

package/src/helpers/color.ts

@@ -202,4 +202,67 @@ export const isLightColor = (color: string, blendedWith: string | null = null):
 
 export const getContrastingTextColor = (color: string, blendedWith: string | null = null): "black" | "white" => {
   return isDarkColor(color, blendedWith) ? "white" : "black";
+};
+
+const rgbaToCss = (rgba: { r: number; g: number; b: number; a?: number }): string => {
+  const a = rgba.a !== undefined ? rgba.a : 1;
+  return `rgba(${Math.round(rgba.r)}, ${Math.round(rgba.g)}, ${Math.round(rgba.b)}, ${a})`;
+};
+
+const lightenColor = (rgba: { r: number; g: number; b: number; a?: number }, factor: number): { r: number; g: number; b: number; a: number } => {
+  return {
+    r: Math.min(255, rgba.r + (255 - rgba.r) * factor),
+    g: Math.min(255, rgba.g + (255 - rgba.g) * factor),
+    b: Math.min(255, rgba.b + (255 - rgba.b) * factor),
+    a: rgba.a ?? 1
+  };
+};
+
+const darkenColor = (rgba: { r: number; g: number; b: number; a?: number }, factor: number): { r: number; g: number; b: number; a: number } => {
+  return {
+    r: Math.max(0, rgba.r * (1 - factor)),
+    g: Math.max(0, rgba.g * (1 - factor)),
+    b: Math.max(0, rgba.b * (1 - factor)),
+    a: rgba.a ?? 1
+  };
+};
+
+export const adjustColorForContrast = (
+  baseColor: string,
+  backgroundColor: string | null = null,
+  targetContrast: number = 3
+): string => {
+  const baseRgba = colorToRgba(baseColor);
+  const bgRgba = backgroundColor ? colorToRgba(backgroundColor) : { r: 255, g: 255, b: 255, a: 1 };
+  
+  let currentContrast = checkContrast(baseRgba, bgRgba);
+  
+  // If already meets target, return as-is
+  if (currentContrast >= targetContrast) {
+    return baseColor;
+  }
+  
+  const bgLuminance = getLuminance(bgRgba);
+  const isBgDark = bgLuminance < 0.5;
+  
+  let adjustedRgba = { ...baseRgba, a: baseRgba.a ?? 1 };
+  const maxIterations = 20;
+  const step = 0.1;
+  
+  for (let i = 0; i < maxIterations; i++) {
+    if (isBgDark) {
+      // Dark background: lighten the base color
+      adjustedRgba = lightenColor(adjustedRgba, step);
+    } else {
+      // Light background: darken the base color
+      adjustedRgba = darkenColor(adjustedRgba, step);
+    }
+    
+    currentContrast = checkContrast(adjustedRgba, bgRgba);
+    if (currentContrast >= targetContrast) {
+      break;
+    }
+  }
+  
+  return rgbaToCss(adjustedRgba);
 };

package/src/helpers/css.ts

@@ -1,5 +1,34 @@
 import { ReadiumWindow } from "./dom.ts";
 
+const COSMETIC_PROPERTIES = new Set([
+    "backgroundColor", "textColor",
+    "linkColor", "visitedColor",
+    "primaryColor", "secondaryColor",
+    "selectionBackgroundColor", "selectionTextColor",
+    "blendFilter", "darkenFilter", "invertFilter", "invertGaiji",
+]);
+
+const CSS_PROP_RE = /--(?:USER|RS)__([\w-]+)/g;
+
+/**
+ * Returns true if the style attribute change between oldValue and newValue
+ * includes at least one ReadiumCSS property that affects document layout/geometry.
+ * Pure appearance changes (colors, filters) return false.
+ */
+export function styleChangeAffectsLayout(oldValue: string | null, newValue: string | null): boolean {
+    const old_ = oldValue ?? "";
+    const new_ = newValue ?? "";
+    const seen = new Set<string>();
+
+    for (const match of old_.matchAll(CSS_PROP_RE)) seen.add(match[1]);
+    for (const match of new_.matchAll(CSS_PROP_RE)) seen.add(match[1]);
+
+    for (const suffix of seen) {
+        if (!COSMETIC_PROPERTIES.has(suffix)) return true;
+    }
+    return false;
+}
+
 export function getProperties(wnd: ReadiumWindow) {
     const cssProperties: { [key: string]: string } = {};
 

package/src/helpers/document.ts

@@ -13,6 +13,126 @@ export function isVerticalLR(wnd: ReadiumWindow): boolean {
     return writingMode === 'vertical-lr';
 }
 
+export function isVerticalWriting(wnd: ReadiumWindow): boolean {
+    const writingMode = wnd.getComputedStyle(wnd.document.documentElement).writingMode
+        || wnd.getComputedStyle(wnd.document.body).writingMode;
+    return writingMode === 'vertical-rl' || writingMode === 'vertical-lr';
+}
+
+/**
+ * Axis-normalizing context for decoration layout.
+ *
+ * Translates CSS physical properties into logical inline/block terms so that
+ * callers can position elements identically regardless of writing mode:
+ *
+ *   horizontal writing  →  inline = horizontal, block = vertical
+ *   vertical writing    →  inline = vertical,   block = horizontal
+ */
+export interface WritingContext {
+    isVertical: boolean;
+    isVertLR: boolean;
+    /** Viewport size along the inline axis (innerWidth / innerHeight). */
+    viewportInlineSize: number;
+    /** Viewport size along the block axis (innerHeight / innerWidth). */
+    viewportBlockSize: number;
+    /**
+     * Size of a single page along the inline axis.
+     * Horizontal: viewportWidth / columnCount.
+     * Vertical: viewportHeight (no columns).
+     */
+    pageInlineSize: number;
+    /**
+     * Physical x offset to add to a client-space x coordinate to get document space.
+     * Horizontal: scrollLeft (non-negative).
+     * Vertical-rl: scrollWidth − viewportWidth + scrollLeft (scrollLeft is negative,
+     *   so this normalises it to the viewport's left edge in document coordinates).
+     * Vertical-lr: scrollLeft (non-negative, same as horizontal).
+     */
+    xDocOffset: number;
+    /** Physical y offset to add to a client-space y coordinate to get document space (scrollTop). */
+    yDocOffset: number;
+    /** Scroll offset along the inline axis, derived from xDocOffset / yDocOffset. */
+    inlineScrollOffset: number;
+    /** Scroll offset along the block axis, derived from xDocOffset / yDocOffset. */
+    blockScrollOffset: number;
+
+    /** Logical inline start of a rect (left / top). */
+    inlineStart(r: DOMRect | { top: number; left: number }): number;
+    /** Logical block start of a rect (top / left). */
+    blockStart(r: DOMRect | { top: number; left: number }): number;
+    /** Logical inline size of a rect (width / height). */
+    inlineSize(r: DOMRect | { width: number; height: number }): number;
+    /** Logical block size of a rect (height / width). */
+    blockSize(r: DOMRect | { width: number; height: number }): number;
+
+    /**
+     * Set absolute position on an element using logical coordinates.
+     * `iz` is the inverse zoom factor (1 in non-Blink, 1/zoom in Blink).
+     */
+    applyPosition(el: HTMLElement, inlineStart: number, blockStart: number, inlineSize: number, blockSize: number, iz: number): void;
+
+    /** Convert logical coordinates back to a physical DOMRect. */
+    toRect(inlineStart: number, blockStart: number, inlineSize: number, blockSize: number): DOMRect;
+}
+
+export function makeWritingContext(wnd: ReadiumWindow): WritingContext {
+    const isVert = isVerticalWriting(wnd);
+    const isVLR  = isVert && isVerticalLR(wnd);
+    const vw     = wnd.innerWidth;
+    const vh     = wnd.innerHeight;
+    const se     = wnd.document.scrollingElement!;
+    const xOff   = se.scrollLeft;   // negative for vertical-rl, non-negative otherwise
+    const yOff   = se.scrollTop;
+    const cols   = parseInt(wnd.getComputedStyle(wnd.document.documentElement).getPropertyValue("column-count"));
+
+    // In vertical-rl, scrollLeft starts at 0 (document start = right side) and goes
+    // negative as the reader scrolls left. The viewport's left edge in document space
+    // is therefore (scrollWidth − viewportWidth + scrollLeft). For vertical-lr and
+    // horizontal modes, scrollLeft is non-negative and is the offset directly.
+    const xDocOffset = (isVert && !isVLR)
+        ? se.scrollWidth - vw + xOff
+        : xOff;
+    const yDocOffset = yOff;
+
+    return {
+        isVertical:          isVert,
+        isVertLR:            isVLR,
+        viewportInlineSize:  isVert ? vh : vw,
+        viewportBlockSize:   isVert ? vw : vh,
+        pageInlineSize:      isVert ? vh : vw / (cols || 1),
+        xDocOffset,
+        yDocOffset,
+        inlineScrollOffset:  isVert ? yDocOffset : xDocOffset,
+        blockScrollOffset:   isVert ? xDocOffset : yDocOffset,
+
+        inlineStart: (r) => isVert ? r.top  : r.left,
+        blockStart:  (r) => isVert ? r.left : r.top,
+        inlineSize:  (r) => isVert ? r.height : r.width,
+        blockSize:   (r) => isVert ? r.width  : r.height,
+
+        applyPosition(el, inlineStart, blockStart, inlineSize, blockSize, iz) {
+            el.style.position = "absolute";
+            if (isVert) {
+                el.style.top    = `${inlineStart * iz}px`;
+                el.style.left   = `${blockStart  * iz}px`;
+                el.style.height = `${inlineSize  * iz}px`;
+                el.style.width  = `${blockSize   * iz}px`;
+            } else {
+                el.style.left   = `${inlineStart * iz}px`;
+                el.style.top    = `${blockStart  * iz}px`;
+                el.style.width  = `${inlineSize  * iz}px`;
+                el.style.height = `${blockSize   * iz}px`;
+            }
+        },
+
+        toRect(inlineStart, blockStart, inlineSize, blockSize) {
+            return isVert
+                ? new DOMRect(blockStart, inlineStart, blockSize, inlineSize)
+                : new DOMRect(inlineStart, blockStart, inlineSize, blockSize);
+        },
+    };
+}
+
 export function getColumnCountPerScreen(wnd: ReadiumWindow): number {
     return parseInt(
         wnd.getComputedStyle(

package/src/helpers/rect.ts

@@ -12,7 +12,8 @@ export interface Rect {
 
 export function getClientRectsNoOverlap(
     range: Range,
-    doNotMergeHorizontallyAlignedRects: boolean
+    doNotMergeHorizontallyAlignedRects: boolean,
+    doNotMergeVerticallyAlignedRects: boolean = false
 ) {
     let clientRects = range.getClientRects();
 
@@ -36,7 +37,8 @@ export function getClientRectsNoOverlap(
     const mergedRects = mergeTouchingRects(
         originalRects,
         tolerance,
-        doNotMergeHorizontallyAlignedRects
+        doNotMergeHorizontallyAlignedRects,
+        doNotMergeVerticallyAlignedRects
     );
     const noContainedRects = removeContainedRects(mergedRects, tolerance);
     const newRects = replaceOverlapingRects(noContainedRects);
@@ -61,7 +63,8 @@ export function getClientRectsNoOverlap(
 function mergeTouchingRects(
     rects: Rect[],
     tolerance: number,
-    doNotMergeHorizontallyAlignedRects: boolean
+    doNotMergeHorizontallyAlignedRects: boolean,
+    doNotMergeVerticallyAlignedRects: boolean = false
 ): Rect[] {
     for (let i = 0; i < rects.length; i++) {
         for (let j = i + 1; j < rects.length; j++) {
@@ -78,8 +81,9 @@ function mergeTouchingRects(
                 almostEqual(rect1.left, rect2.left, tolerance) &&
                 almostEqual(rect1.right, rect2.right, tolerance);
             const horizontalAllowed = !doNotMergeHorizontallyAlignedRects;
+            const verticalAllowed = !doNotMergeVerticallyAlignedRects;
             const aligned =
-                (rectsLineUpHorizontally && horizontalAllowed) ||
+                (rectsLineUpHorizontally && horizontalAllowed && verticalAllowed) ||
                 (rectsLineUpVertically && !rectsLineUpHorizontally);
             const canMerge = aligned && rectsTouchOrOverlap(rect1, rect2, tolerance);
             if (canMerge) {
@@ -94,7 +98,8 @@ function mergeTouchingRects(
                 return mergeTouchingRects(
                     newRects,
                     tolerance,
-                    doNotMergeHorizontallyAlignedRects
+                    doNotMergeHorizontallyAlignedRects,
+                    doNotMergeVerticallyAlignedRects
                 );
             }
         }

package/src/helpers/sML.ts

@@ -0,0 +1,143 @@
+/*!
+ *                                                                                                                         (℠)
+ *  # sML.js | I'm a Simple and Middling Library.
+ *
+ *  * Copyright (c) Satoru MATSUSHIMA - https://github.com/satorumurmur/sML
+ *  * Licensed under the MIT license. - http://www.opensource.org/licenses/mit-license.php
+ *
+ * Portions of this code come from the sML library
+ * Current version: 1.0.36
+ */
+/// <reference types="user-agent-data-types" />
+
+declare interface OSFlags {
+    iOS: number[];
+    macOS: number[];
+    iPadOS: number[];
+    WindowsPhone: number[];
+    ChromeOS: number[];
+    Windows: number[];
+    Android: number[];
+    Linux: number[];
+    Firefox: boolean;
+}
+
+declare interface UAFlags {
+    Gecko: number[];
+    Firefox: number[];
+    Waterfox: number[];
+    Opera: number[];
+    Silk: number[];
+    Blink: number[];
+    EdgeHTML: number[];
+    Chrome: number[];
+    Chromium: number[];
+    Phoebe: number[];
+    UCBrowser: number[];
+    Vivaldi: number[];
+    Safari: number[];
+    Edge: number[];
+    WebKit: number[];
+    Trident: number[];
+    InternetExplorer: number[];
+    Flash: number[];
+    Facebook: number[];
+    LINE: number[];
+}
+
+declare type iOSRequest = "mobile" | "desktop" | undefined;
+
+// Fallback when global 'navigator' is not available, such as in SSR environments.
+const userAgent = () => typeof navigator === "undefined" ? "" : (navigator.userAgent || "");
+const userAgentData = () => typeof navigator === "undefined" ? undefined : (navigator.userAgentData || undefined);
+
+class sMLFactory {
+    OS: OSFlags;
+    UA: UAFlags;
+    Env!: string[];
+
+    constructor() {
+        const NUAD = userAgentData(), NUA = userAgent();
+
+        const _sV = (V?: string | number) => (typeof V === "string" || typeof V === "number") && V ? String(V).replace(/_/g, ".").split(".").map(I => parseInt(I) || 0) : [];
+        const _dV = (Pre="") => {
+            if(!Pre) return [];
+            const RE = new RegExp("^.*" + Pre + "[ :\\/]?(\\d+([\\._]\\d+)*).*$");
+            if(!RE.test(NUA)) return [];
+            return _sV(NUA.replace(RE, "$1"));
+        };
+
+        this.OS = ((OS: OSFlags) => {
+            if(                /(macOS|Mac OS X)/.test(NUA)) {
+                    if(/\(iP(hone|od touch);/.test(NUA)) OS.iOS = _dV("CPU (?:iPhone )?OS ");
+                    if(             /\(iPad;/.test(NUA)) OS.iOS = OS.iPadOS = _dV("CPU (?:iPhone )?OS ");
+                else if( /(macOS|Mac OS X) \d/.test(NUA)) document.ontouchend !== undefined ? OS.iOS = OS.iPadOS = _dV() : OS.macOS = _dV("(?:macOS|Mac OS X) ");
+            } else if(      /Windows( NT)? \d/.test(NUA)) OS.Windows = (V => V[0] !== 6 || !V[1] ? V : V[1] === 1 ? [7] : V[1] === 2 ? [8] : [8, 1])(_dV("Windows(?: NT)?"));
+            else if(            /Android \d/.test(NUA)) OS.Android = _dV("Android");
+            else if(                  /CrOS/.test(NUA)) OS.ChromeOS = _dV();
+            else if(                  /X11;/.test(NUA)) OS.Linux = _dV();
+            return OS;
+        })({} as OSFlags); if(NUAD) NUAD.getHighEntropyValues(["architecture", "model", "platform", "platformVersion", "uaFullVersion"]).then((HEUAD: any) => (OS => { const Pf = HEUAD.platform, PfV = HEUAD.platformVersion; if(!Pf || !PfV) return;
+                if(         /^i(OS|P(hone|od touch))$/.test(Pf)) OS.iOS = _sV(PfV);
+            else if(                      /^iPad(OS)?$/.test(Pf)) OS.iOS = OS.iPadOS = _sV(PfV);
+            else if(/^(macOS|(Mac )?OS X|Mac(Intel)?)$/.test(Pf)) document.ontouchend !== undefined ? OS.iOS = OS.iPadOS = _sV() : OS.macOS = _sV(PfV);
+            else if(           /^(Microsoft )?Windows$/.test(Pf)) OS.Windows = _sV(PfV);
+            else if(              /^(Google )?Android$/.test(Pf)) OS.Android = _sV(PfV);
+            else if(     /^((Google )?Chrome OS|CrOS)$/.test(Pf)) OS.ChromeOS = _sV(PfV);
+            else if(             /^(Linux|Ubuntu|X11)$/.test(Pf)) OS.Linux = _sV(PfV);
+            else return; /**/ Object.keys(this.OS).forEach(Key => delete (this.OS as any)[Key]), Object.assign(this.OS, OS);
+        })({} as OSFlags));
+
+        this.UA = ((UA: UAFlags) => { let _OK = false;
+            if(NUAD && Array.isArray(NUAD.brands)) { const BnV = NUAD.brands.reduce((BnV: Record<string, number[]>, _: NavigatorUABrandVersion) => { BnV[_.brand] = [(_.version as any) * 1]; return BnV; }, {});
+                    if(BnV["Google Chrome"])  _OK = true, UA.Blink = UA.Chromium = BnV["Chromium"] || [], UA.Chrome = BnV["Google Chrome"];
+                else if(BnV["Microsoft Edge"]) _OK = true, UA.Blink = UA.Chromium = BnV["Chromium"] || [], UA.Edge = BnV["Microsoft Edge"];
+                else if(BnV["Opera"])          _OK = true, UA.Blink = UA.Chromium = BnV["Chromium"] || [], UA.Opera = BnV["Opera"];
+            } if(!_OK) {
+                if(              / Gecko\/\d/.test(NUA)) { UA.Gecko = _dV("rv");
+                        if(  / Waterfox\/\d/.test(NUA))   UA.Waterfox = _dV("Waterfox");
+                    else if(   / Firefox\/\d/.test(NUA))   UA.Firefox = _dV("Firefox");
+                } else if(        / Edge\/\d/.test(NUA)) { UA.EdgeHTML = _dV("Edge");
+                                                        UA.Edge = UA.EdgeHTML;
+                } else if(/ Chrom(ium|e)\/\d/.test(NUA)) { UA.Blink = UA.Chromium = (V => V[0] ? V : _dV("Chrome"))(_dV("Chromium"));
+                        if(     / EdgA?\/\d/.test(NUA))   UA.Edge = (V => V[0] ? V : _dV("Edg"))(_dV("EdgA"));
+                    else if(       / OPR\/\d/.test(NUA))   UA.Opera = _dV("OPR");
+                    else if(   / Vivaldi\/\d/.test(NUA))   UA.Vivaldi = _dV("Vivaldi");
+                    else if(      / Silk\/\d/.test(NUA))   UA.Silk = _dV("Silk");
+                    else if( / UCBrowser\/\d/.test(NUA))   UA.UCBrowser = _dV("UCBrowser");
+                    else if(    / Phoebe\/\d/.test(NUA))   UA.Phoebe = _dV("Phoebe");
+                    else                                   UA.Chrome = (V => V[0] ? V : UA.Chromium)(_dV("Chrome"));
+                } else if( / AppleWebKit\/\d/.test(NUA)) { UA.WebKit = _dV("AppleWebKit");
+                        if(      / CriOS \d/.test(NUA))   UA.Chrome = _dV("CriOS");
+                    else if(      / FxiOS \d/.test(NUA))   UA.Firefox = _dV("FxiOS");
+                    else if(    / EdgiOS\/\d/.test(NUA))   UA.Edge = _dV("EdgiOS");
+                    else if(   / Version\/\d/.test(NUA))   UA.Safari = _dV("Version");
+                } else if(     / Trident\/\d/.test(NUA)) { UA.Trident = _dV("Trident");
+                                                        UA.InternetExplorer = (V => V[0] ? V : _dV("MSIE"))(_dV("rv"));
+                }
+            } /*+*/ if( /[\[; ]FB(AN|_IAB)\//.test(NUA))   UA.Facebook = _dV("FBAV");
+            /*+*/ if(           / Line\/\d/.test(NUA))   UA.LINE = _dV("Line");
+            return UA;
+        })({} as UAFlags);
+
+        (this.Env as any) = { get: () => [this.OS, this.UA].reduce((Env: string[], OS_UA) => { for(const Par in OS_UA) if((OS_UA as any)[Par]) Env.push(Par); return Env; }, []) };
+    }
+}
+
+class sMLFactoryWithRequest extends sMLFactory {
+    get iOSRequest(): iOSRequest {
+        const NUAD = userAgentData(), NUA = userAgent();
+
+        if (this.OS.iOS && !this.OS.iPadOS) {
+            return "mobile";
+        } else if (this.OS.iPadOS) {
+            return (/\(iPad;/.test(NUA) || (NUAD && /^iPad(OS)?$/.test(NUAD.platform))) ? "mobile" : "desktop"
+        }
+
+        return undefined;
+    }
+}
+
+const sML = new sMLFactory();
+const sMLWithRequest = new sMLFactoryWithRequest();
+export { sML, sMLWithRequest };

package/src/helpers/sanitize.ts

@@ -0,0 +1,77 @@
+/**
+ * Elements a decoration template is allowed to contain.
+ * Allowlisting instead of denylisting: anything not listed here is stripped,
+ * including elements that do not yet exist in the HTML spec.
+ */
+const ALLOWED_ELEMENTS = [
+    // Structure / presentation
+    "div", "span", "p", "br", "hr",
+    "b", "i", "em", "strong", "s", "u", "mark", "small", "sub", "sup",
+    "abbr", "cite", "code", "data", "dfn", "kbd", "q", "samp", "time", "var",
+    "blockquote", "pre",
+    // SVG — useful for icon-style decorations (e.g. sidemarks)
+    "svg", "g", "path", "circle", "ellipse", "rect", "line",
+    "polygon", "polyline", "text", "tspan", "defs", "use",
+];
+
+/** Attributes that introduce executable code on any element. */
+const DANGEROUS_ATTR = /^on/i;
+/** Attributes that carry URLs and must be checked for unsafe schemes. */
+const URL_ATTRS = new Set(["href", "src", "action", "formaction", "xlink:href"]);
+/** URL schemes that must not appear in URL-bearing attributes. */
+const DANGEROUS_SCHEME = /^\s*(javascript|data):/i;
+
+/**
+ * Parses `html` and returns its first element child with all executable
+ * content removed. Uses the Sanitizer API when available, falls back to a
+ * manual DOMParser scrub otherwise.
+ *
+ * The allowlist approach is intentional: unknown or future elements are
+ * stripped by default rather than permitted by oversight.
+ *
+ * @param wnd  Window whose document is used when adopting nodes.
+ * @param html Raw HTML string supplied by the caller.
+ * @returns    The sanitized first element child, or `null` for empty input.
+ */
+export function sanitizeHTML(wnd: Window, html: string): Element | null {
+    const host = wnd.document.createElement("div");
+
+    if ("Sanitizer" in wnd && typeof (host as any).setHTML === "function") {
+        try {
+            const sanitizer = new (wnd as any).Sanitizer({ allowElements: ALLOWED_ELEMENTS });
+            (host as any).setHTML(html, { sanitizer });
+            return host.firstElementChild as Element | null;
+        } catch {
+            // Sanitizer API present but call failed — fall through to DOMParser.
+        }
+    }
+
+    // DOMParser fallback: parse in an isolated document then scrub manually.
+    const scratch = wnd.document.implementation.createHTMLDocument("");
+    scratch.body.innerHTML = html;
+    scrubNode(scratch.body, new Set(ALLOWED_ELEMENTS));
+    while (scratch.body.firstChild) {
+        host.appendChild(wnd.document.adoptNode(scratch.body.firstChild));
+    }
+    return host.firstElementChild as Element | null;
+}
+
+function scrubNode(root: Element, allowed: Set<string>): void {
+    // Walk in reverse so removals don't shift indices.
+    const all = Array.from(root.querySelectorAll("*")).reverse();
+    for (const el of all) {
+        if (!allowed.has(el.localName)) {
+            // Replace disallowed element with its children to preserve text.
+            el.replaceWith(...Array.from(el.childNodes));
+            continue;
+        }
+        for (const { name, value } of Array.from(el.attributes)) {
+            if (
+                DANGEROUS_ATTR.test(name) ||
+                (URL_ATTRS.has(name) && DANGEROUS_SCHEME.test(value))
+            ) {
+                el.removeAttribute(name);
+            }
+        }
+    }
+}

package/src/index.ts

@@ -2,4 +2,5 @@ export * from './comms/index.ts';
 export * from './modules/index.ts';
 export * from './Loader.ts';
 export * from './protection/index.ts';
-export * from './keyboard/index.ts'
+export * from './helpers/sML.ts';
+export * from './keyboard/index.ts'

package/src/keyboard/KeyCombinationManager.ts

@@ -146,6 +146,7 @@ export class KeyCombinationManager {
         const handlers = this.createKeyboardHandlers(targetFrameSrc, shortcuts, dispatcher, wnd);
 
         return (event: KeyboardEvent) => {
+            if (!event.isTrusted) return;
             for (const handlerConfig of handlers) {
                 if (this.match(event, [handlerConfig])) {
                     const suppress = handlerConfig.suppressOnInteractiveElement;