@mpgd/tutorial 0.1.0 → 0.1.2

package/dist/driver.js

@@ -25,20 +25,42 @@ export function createDriverTutorialPresenter(input) {
     let destroyed = false;
     let reportedActive = false;
     let targetSemanticsGuard;
+    let targetShadowPointerStyle;
     let targetRestorePending = false;
+    let restartPreferredOnFrame = false;
+    let restartingInstance = false;
     let dismissedPresentationKey = null;
     let retryableDismissedKey = null;
     let missingTargetErrorKey = null;
     let syncModalSemantics;
+    let targetAcknowledgeBinding;
+    let targetClickState;
+    let targetHitTestFrame;
+    let targetGeometryTimer;
+    let targetOverlayPointerRestore;
     const pendingSkipOperations = new Set();
+    const reportError = (error) => {
+        try {
+            input.onError?.(error);
+        }
+        catch {
+            // Error reporting must not interrupt presenter lifecycle handling.
+        }
+    };
     const reportActive = (active) => {
         if (reportedActive === active) {
             return;
         }
         reportedActive = active;
-        input.onActiveChange?.(active);
+        try {
+            input.onActiveChange?.(active);
+        }
+        catch (error) {
+            reportError(error);
+        }
     };
-    const scheduleRefresh = () => {
+    const scheduleRefresh = (restartPreferred = false) => {
+        restartPreferredOnFrame ||= restartPreferred;
         if (destroyed || frame !== undefined || dismissedPresentationKey !== null) {
             return;
         }
@@ -47,14 +69,24 @@ export function createDriverTutorialPresenter(input) {
             if (destroyed || dismissedPresentationKey !== null) {
                 return;
             }
+            const shouldRestartPreferred = restartPreferredOnFrame;
+            restartPreferredOnFrame = false;
             const currentInstance = instance;
             if (currentInstance === null || !currentInstance.isActive()) {
                 driveActiveStep();
                 return;
             }
-            rebindActiveTarget(currentInstance, activePresentation);
+            const presentation = activePresentation;
+            if (shouldRestartPreferred
+                && presentation !== null
+                && shouldPreferActivatableTutorialTarget(presentation)) {
+                restartActiveInstance(currentInstance, presentation);
+                return;
+            }
+            rebindActiveTarget(currentInstance, presentation);
         });
     };
+    const scheduleHostRefresh = () => scheduleRefresh(true);
     const createInstance = (presentation) => {
         let created;
         let modalSemanticsGuard;
@@ -63,9 +95,16 @@ export function createDriverTutorialPresenter(input) {
             if (popover === null) {
                 return;
             }
-            const modalSelector = input.modalSelector ?? '[role="dialog"][aria-modal="true"]';
-            const modal = resolveUnderlyingTutorialModal(popover, presentation.step.interaction, created.getActiveElement(), modalSelector, modalSemanticsGuard?.modal ?? null);
-            if (modalSemanticsGuard?.modal === modal && modalSemanticsGuard.popover === popover) {
+            const modalSelector = input.modalSelector
+                ?? '[role="dialog"][aria-modal="true"], [role="alertdialog"][aria-modal="true"]';
+            const retainCurrentModal = modalSemanticsGuard
+                ?.isOwnedAttributeCurrent('aria-modal') ?? false;
+            const modal = resolveUnderlyingTutorialModal(popover, presentation.step.interaction, created.getActiveElement(), modalSelector, modalSemanticsGuard?.modal ?? null, retainCurrentModal);
+            if (modalSemanticsGuard?.modal === modal
+                && modalSemanticsGuard.popover === popover
+                && (presentation.step.interaction !== 'blocked'
+                    || modal === null
+                    || retainCurrentModal)) {
                 return;
             }
             modalSemanticsGuard?.restore();
@@ -98,14 +137,21 @@ export function createDriverTutorialPresenter(input) {
                 const dismissedKey = activePresentationKey;
                 dismissedPresentationKey = dismissedKey;
                 retryableDismissedKey = null;
+                const skipping = (() => {
+                    try {
+                        return Promise.resolve(input.onSkip());
+                    }
+                    catch (error) {
+                        return Promise.reject(error);
+                    }
+                })();
                 destroyInstancePreservingTarget(created);
-                const skipOperation = Promise.resolve()
-                    .then(() => input.onSkip())
+                const skipOperation = skipping
                     .catch((error) => {
                     if (dismissedPresentationKey === dismissedKey) {
                         retryableDismissedKey = dismissedKey;
                     }
-                    input.onError?.(error);
+                    reportError(error);
                 });
                 pendingSkipOperations.add(skipOperation);
                 void skipOperation
@@ -113,6 +159,8 @@ export function createDriverTutorialPresenter(input) {
                     .catch(() => undefined);
             },
             onDestroyed: () => {
+                clearTargetAcknowledgeBinding(created);
+                clearTargetClickState(created);
                 if (!targetRestorePending) {
                     targetSemanticsGuard?.restore(true);
                 }
@@ -124,11 +172,15 @@ export function createDriverTutorialPresenter(input) {
                     syncModalSemantics = undefined;
                 }
                 if (instance === created) {
+                    cancelTargetGeometryMonitor();
+                    clearTargetGeometryObservers();
                     instance = null;
-                    clearTutorialState(stateHost);
-                    reportActive(false);
+                    if (!restartingInstance) {
+                        clearTutorialState(stateHost);
+                        reportActive(false);
+                    }
                 }
-                if (!destroyed && activePresentation !== null) {
+                if (!destroyed && !restartingInstance && activePresentation !== null) {
                     scheduleRefresh();
                 }
             },
@@ -142,8 +194,16 @@ export function createDriverTutorialPresenter(input) {
                 popover = wrapper;
                 syncModalSemantics = syncCreatedModalSemantics;
                 syncCreatedModalSemantics();
-                if (presentation.step.advance.kind === 'acknowledge') {
-                    const initialFocus = created.getActiveStep()?.advanceOnClick === true
+                if (presentation.step.advance.kind === 'acknowledge'
+                    || presentation.step.interaction === 'blocked') {
+                    const activeTarget = created.getActiveElement();
+                    const acknowledgeFromTarget = activeTarget instanceof HTMLElement
+                        && targetClickState?.driver === created
+                        && targetClickState.target === activeTarget
+                        && targetClickState.stepId === presentation.step.id
+                        && targetClickState.acknowledgeOnTargetClick;
+                    const initialFocus = presentation.step.advance.kind !== 'acknowledge'
+                        || acknowledgeFromTarget
                         ? closeButton
                         : nextButton;
                     browserWindow.queueMicrotask(() => initialFocus.focus());
@@ -177,20 +237,30 @@ export function createDriverTutorialPresenter(input) {
         else {
             missingTargetErrorKey = null;
         }
+        const targetActivatable = target !== null
+            && isActivatableTutorialTarget(target, browserWindow);
+        const targetClickMode = resolveTutorialTargetClickMode(presentation, target ?? undefined, targetActivatable);
         const nextInstance = createInstance(presentation);
         instance = nextInstance;
+        setTargetClickState(nextInstance, presentation, target ?? undefined, targetClickMode);
         targetSemanticsGuard?.restore();
         targetSemanticsGuard = target === null
             ? undefined
             : preserveTutorialTargetSemantics(target, browserWindow);
         try {
-            stateHost.setAttribute(tutorialDomAttributes.active, 'true');
-            stateHost.setAttribute(tutorialDomAttributes.step, presentation.step.id);
             nextInstance.setSteps([
-                createDriveStep(input, presentation, target ?? undefined, ownerDocument),
+                createDriveStep(input, presentation, target ?? undefined, targetClickMode.acknowledgeOnTargetClick, ownerDocument, reportError),
             ]);
-            applyDriverTargetMutation(() => nextInstance.drive());
+            applyDriverTargetMutation(() => {
+                syncTargetShadowPointerStyle(presentation, target ?? undefined, targetActivatable);
+                stateHost.setAttribute(tutorialDomAttributes.active, 'true');
+                stateHost.setAttribute(tutorialDomAttributes.step, presentation.step.id);
+                nextInstance.drive();
+            });
+            downgradeInactiveTargetClickMode(nextInstance, presentation, target ?? undefined, targetClickMode);
             syncModalSemantics?.();
+            syncTargetGeometryObservers(presentation);
+            syncTargetGeometryMonitor(nextInstance, presentation);
             reportActive(true);
         }
         catch (error) {
@@ -205,20 +275,26 @@ export function createDriverTutorialPresenter(input) {
                 clearTutorialState(stateHost);
                 reportActive(false);
             }
-            input.onError?.(error);
+            reportError(error);
         }
     };
     const resolvePresentationTarget = (presentation, presentationKey = activePresentationKey) => {
         if (presentation.step.target === null) {
             return null;
         }
+        const presentationTarget = presentation.step.target;
         try {
             if (input.resolveTarget !== undefined) {
-                return input.resolveTarget(presentation.step.target, root);
+                const target = input.resolveTarget(presentationTarget, root);
+                if (target !== null && target.ownerDocument !== ownerDocument) {
+                    throw new Error('Tutorial target must belong to the presenter document.');
+                }
+                return target;
             }
             return resolveVisibleTutorialTarget({
+                preferActivatable: shouldPreferActivatableTutorialTarget(presentation),
                 root,
-                target: presentation.step.target,
+                target: presentationTarget,
                 targetAttribute,
                 view: browserWindow,
             });
@@ -228,35 +304,409 @@ export function createDriverTutorialPresenter(input) {
                 && presentationKey === activePresentationKey
                 && missingTargetErrorKey !== presentationKey) {
                 missingTargetErrorKey = presentationKey;
-                input.onError?.(error);
+                reportError(error);
             }
             return null;
         }
     };
-    const observationRoot = root.nodeType === 9 ? ownerDocument.documentElement : root;
-    const mutationObserver = new browserWindow.MutationObserver((records) => {
+    const resizeObservationRoot = root.nodeType === 9
+        ? ownerDocument.documentElement
+        : root;
+    const mutationOptions = {
+        attributes: true,
+        characterData: true,
+        childList: true,
+        subtree: true,
+    };
+    const mutationObserver = new browserWindow.MutationObserver(processMutationRecords);
+    let observedShadowRoots = new Set();
+    let observingDocumentMutations = false;
+    let resizeObserver = null;
+    let intersectionObserver = null;
+    const observedGeometryTargets = new Set();
+    const targetVisibility = new Map();
+    function processMutationRecords(records) {
         if (activePresentation === null && instance === null) {
+            observeDocumentOnlyMutations();
             return;
         }
-        if (records.some((record) => !isDriverOwnedMutation(record))) {
-            scheduleRefresh();
+        reconcileMutationRoots();
+        const hostRecords = records.filter((record) => !isDriverOwnedMutation(record));
+        if (hostRecords.length > 0) {
+            scheduleRefresh(hostRecords.some(isTargetSelectionMutation));
         }
-    });
-    mutationObserver.observe(observationRoot, {
-        attributes: true,
-        childList: true,
-        subtree: true,
-    });
-    const resizeObserver = typeof browserWindow.ResizeObserver === 'function'
-        ? new browserWindow.ResizeObserver(scheduleRefresh)
+    }
+    function isTargetSelectionMutation(record) {
+        const presentation = activePresentation;
+        if (presentation === null
+            || presentation.step.target === null
+            || !shouldPreferActivatableTutorialTarget(presentation)) {
+            return false;
+        }
+        const activeElement = instance?.getActiveElement();
+        const currentTarget = activeElement instanceof HTMLElement
+            && activeElement.id !== 'driver-dummy-element'
+            ? activeElement
+            : null;
+        if (record.type === 'characterData') {
+            return record.target.parentElement instanceof HTMLStyleElement
+                && stylesheetMutationAffectsLookupRoot(record.target);
+        }
+        if (record.type === 'attributes') {
+            if (isStylesheetAttributeMutation(record)
+                && stylesheetMutationAffectsLookupRoot(record.target)) {
+                return true;
+            }
+            if (!(record.target instanceof Element)) {
+                return false;
+            }
+            const mutationTarget = record.target;
+            return collectTargetSelectionElements(presentation, currentTarget)
+                .some((target) => attributeMutationMayAffectTarget(target, mutationTarget));
+        }
+        if (record.type !== 'childList') {
+            return false;
+        }
+        const changedNodes = [...record.addedNodes, ...record.removedNodes];
+        const touchesLookupRoot = childListTouchesLookupRoot(record, changedNodes);
+        if (isStylesheetDomMutation(record, changedNodes)
+            && stylesheetMutationAffectsLookupRoot(record.target)) {
+            return true;
+        }
+        if (!touchesLookupRoot) {
+            return false;
+        }
+        if (currentTarget !== null && !currentTarget.isConnected) {
+            return true;
+        }
+        if (currentTarget !== null && changedNodes.some((node) => node instanceof Element && isComposedAncestorOrSelf(currentTarget, node))) {
+            return true;
+        }
+        return input.resolveTarget === undefined && changedNodes.some((node) => mutationNodeMayContainTarget(node, presentation.step.target ?? ''));
+    }
+    function childListTouchesLookupRoot(record, changedNodes) {
+        if (root.nodeType === 9 || isNodeWithinLookupRoot(record.target)) {
+            return true;
+        }
+        return changedNodes.some((node) => {
+            if (node === root) {
+                return true;
+            }
+            return node instanceof Element && isComposedAncestorOrSelf(root, node);
+        });
+    }
+    function isNodeWithinLookupRoot(node) {
+        if (root.nodeType === 9) {
+            return true;
+        }
+        const element = node instanceof ShadowRoot
+            ? node.host
+            : node instanceof Element
+                ? node
+                : node.parentElement;
+        return element !== null && isComposedAncestorOrSelf(element, root);
+    }
+    function isStylesheetDomMutation(record, changedNodes) {
+        return isStylesheetElement(record.target)
+            || changedNodes.some(nodeContainsStylesheetElement);
+    }
+    function isStylesheetAttributeMutation(record) {
+        if (record.target instanceof HTMLStyleElement) {
+            return true;
+        }
+        return record.target instanceof HTMLLinkElement
+            && ['disabled', 'href', 'media', 'rel'].includes(record.attributeName ?? '');
+    }
+    function stylesheetMutationAffectsLookupRoot(node) {
+        const treeScope = node.getRootNode();
+        if (treeScope === ownerDocument) {
+            return true;
+        }
+        const presentation = activePresentation;
+        if (presentation === null) {
+            return false;
+        }
+        return collectTargetSelectionElements(presentation)
+            .some((target) => composedElementUsesTreeScope(target, treeScope));
+    }
+    function collectTargetSelectionElements(presentation, currentTarget) {
+        const targets = new Set();
+        const activeTarget = currentTarget ?? instance?.getActiveElement();
+        if (activeTarget instanceof HTMLElement && activeTarget.id !== 'driver-dummy-element') {
+            targets.add(activeTarget);
+        }
+        if (input.resolveTarget === undefined && presentation.step.target !== null) {
+            for (const candidate of findComposedTutorialTargets(root, targetAttribute, presentation.step.target)) {
+                targets.add(candidate);
+            }
+        }
+        return [...targets];
+    }
+    function attributeMutationMayAffectTarget(target, mutationTarget) {
+        if (isComposedAncestorOrSelf(target, mutationTarget)) {
+            return true;
+        }
+        if (target.getRootNode() !== mutationTarget.getRootNode()) {
+            return false;
+        }
+        if (target.getRootNode() instanceof ShadowRoot) {
+            return true;
+        }
+        if (root instanceof HTMLElement && isNodeWithinLookupRoot(mutationTarget)) {
+            return true;
+        }
+        if (target.contains(mutationTarget)
+            || target.parentElement !== null
+                && mutationTarget.parentElement === target.parentElement) {
+            return true;
+        }
+        return composedAncestorBranchesAreSiblings(target, mutationTarget);
+    }
+    function composedAncestorBranchesAreSiblings(target, mutationTarget) {
+        const targetAncestors = collectComposedAncestors(target);
+        let mutationAncestor = mutationTarget;
+        while (mutationAncestor !== null) {
+            const mutationParent = getComposedParentElement(mutationAncestor);
+            if (mutationParent !== null
+                && mutationParent !== ownerDocument.body
+                && mutationParent !== ownerDocument.documentElement
+                && targetAncestors.some((targetAncestor) => getComposedParentElement(targetAncestor) === mutationParent)) {
+                return true;
+            }
+            mutationAncestor = mutationParent;
+        }
+        return false;
+    }
+    function collectComposedAncestors(element) {
+        const ancestors = [];
+        let current = element;
+        while (current !== null) {
+            ancestors.push(current);
+            current = getComposedParentElement(current);
+        }
+        return ancestors;
+    }
+    function nodeContainsStylesheetElement(node) {
+        return isStylesheetElement(node)
+            || [...node.childNodes].some(nodeContainsStylesheetElement);
+    }
+    function isStylesheetElement(node) {
+        if (node instanceof HTMLStyleElement) {
+            return true;
+        }
+        return node instanceof HTMLLinkElement
+            && node.rel.toLowerCase().split(/\s+/u).includes('stylesheet');
+    }
+    function mutationNodeMayContainTarget(node, target) {
+        if (node instanceof HTMLElement
+            && (node.getAttribute(targetAttribute) === target || node.shadowRoot !== null)) {
+            return true;
+        }
+        return [...node.childNodes].some((child) => mutationNodeMayContainTarget(child, target));
+    }
+    function reconcileMutationRoots(force = false) {
+        if (destroyed) {
+            return;
+        }
+        if (activePresentation === null && instance === null) {
+            observeDocumentOnlyMutations(force);
+            return;
+        }
+        const nextShadowRoots = new Set(findOpenTutorialShadowRoots(ownerDocument));
+        const rootsChanged = nextShadowRoots.size !== observedShadowRoots.size
+            || [...nextShadowRoots].some((shadowRoot) => !observedShadowRoots.has(shadowRoot));
+        if (!force && observingDocumentMutations && !rootsChanged) {
+            return;
+        }
+        mutationObserver.disconnect();
+        mutationObserver.observe(ownerDocument.documentElement, mutationOptions);
+        observingDocumentMutations = true;
+        for (const shadowRoot of nextShadowRoots) {
+            mutationObserver.observe(shadowRoot, mutationOptions);
+        }
+        observedShadowRoots = nextShadowRoots;
+    }
+    function observeDocumentOnlyMutations(force = false) {
+        if (!force && observingDocumentMutations && observedShadowRoots.size === 0) {
+            return;
+        }
+        mutationObserver.disconnect();
+        mutationObserver.observe(ownerDocument.documentElement, mutationOptions);
+        observingDocumentMutations = true;
+        observedShadowRoots.clear();
+    }
+    function syncTargetGeometryObservers(presentation) {
+        const nextTargets = shouldPreferActivatableTutorialTarget(presentation)
+            ? new Set(collectTargetSelectionElements(presentation))
+            : new Set();
+        for (const target of observedGeometryTargets) {
+            if (nextTargets.has(target)) {
+                continue;
+            }
+            intersectionObserver?.unobserve(target);
+            if (target !== resizeObservationRoot) {
+                resizeObserver?.unobserve(target);
+            }
+            observedGeometryTargets.delete(target);
+            targetVisibility.delete(target);
+        }
+        for (const target of nextTargets) {
+            if (observedGeometryTargets.has(target)) {
+                continue;
+            }
+            observedGeometryTargets.add(target);
+            targetVisibility.set(target, isVisibleTutorialTarget(target, browserWindow));
+            resizeObserver?.observe(target);
+            intersectionObserver?.observe(target);
+        }
+    }
+    function clearTargetGeometryObservers() {
+        for (const target of observedGeometryTargets) {
+            intersectionObserver?.unobserve(target);
+            if (target !== resizeObservationRoot) {
+                resizeObserver?.unobserve(target);
+            }
+        }
+        intersectionObserver?.takeRecords();
+        observedGeometryTargets.clear();
+        targetVisibility.clear();
+    }
+    function syncTargetGeometryMonitor(currentInstance, presentation) {
+        cancelTargetGeometryMonitor();
+        if (!shouldPreferActivatableTutorialTarget(presentation)) {
+            return;
+        }
+        const target = currentInstance.getActiveElement();
+        if (!(target instanceof HTMLElement) || target.id === 'driver-dummy-element') {
+            return;
+        }
+        const presentationKey = activePresentationKey;
+        let previousRect = readTutorialTargetRect(target);
+        let previousVisible = isVisibleTutorialTargetWithRect(target, browserWindow, previousRect);
+        let previousActivatable = isActivatableTutorialTarget(target, browserWindow);
+        const monitor = () => {
+            targetGeometryTimer = undefined;
+            const currentPresentation = activePresentation;
+            if (destroyed
+                || instance !== currentInstance
+                || !currentInstance.isActive()
+                || currentPresentation === null
+                || activePresentationKey !== presentationKey
+                || !shouldPreferActivatableTutorialTarget(currentPresentation)
+                || currentInstance.getActiveElement() !== target) {
+                return;
+            }
+            const nextRect = readTutorialTargetRect(target);
+            const rectChanged = !tutorialTargetRectsEqual(previousRect, nextRect);
+            const selectionInvalid = !target.isConnected
+                || !isNodeWithinLookupRoot(target)
+                || (input.resolveTarget === undefined
+                    && target.getAttribute(targetAttribute) !== currentPresentation.step.target);
+            const nextVisible = !selectionInvalid
+                && isVisibleTutorialTargetWithRect(target, browserWindow, nextRect);
+            const visibilityChanged = nextVisible !== previousVisible;
+            const nextActivatable = isActivatableTutorialTarget(target, browserWindow);
+            const activatableChanged = nextActivatable !== previousActivatable;
+            if (rectChanged || selectionInvalid || visibilityChanged || activatableChanged) {
+                if (selectionInvalid || visibilityChanged) {
+                    scheduleHostRefresh();
+                }
+                else if (activatableChanged) {
+                    scheduleRefresh();
+                }
+                else {
+                    scheduleRefresh();
+                }
+                previousRect = nextRect;
+                previousVisible = nextVisible;
+                previousActivatable = nextActivatable;
+            }
+            targetGeometryTimer = browserWindow.setTimeout(monitor, 250);
+        };
+        targetGeometryTimer = browserWindow.setTimeout(monitor, 250);
+    }
+    function cancelTargetGeometryMonitor() {
+        if (targetGeometryTimer === undefined) {
+            return;
+        }
+        browserWindow.clearTimeout(targetGeometryTimer);
+        targetGeometryTimer = undefined;
+    }
+    function recordTargetVisibilityChange(target) {
+        const previous = targetVisibility.get(target);
+        const next = isVisibleTutorialTarget(target, browserWindow);
+        targetVisibility.set(target, next);
+        return previous !== undefined && previous !== next;
+    }
+    function processIntersectionRecords(entries) {
+        const visibilityChanges = entries.map((entry) => (entry.target instanceof HTMLElement
+            && observedGeometryTargets.has(entry.target)
+            && recordTargetVisibilityChange(entry.target)));
+        if (visibilityChanges.some(Boolean) && preferredTargetIdentityChanged()) {
+            scheduleHostRefresh();
+        }
+    }
+    function processResizeRecords(entries) {
+        const visibilityChanges = entries.map((entry) => (entry.target instanceof HTMLElement
+            && observedGeometryTargets.has(entry.target)
+            && recordTargetVisibilityChange(entry.target)));
+        if (visibilityChanges.some(Boolean) && preferredTargetIdentityChanged()) {
+            scheduleHostRefresh();
+            return;
+        }
+        if (entries.some((entry) => entry.target === resizeObservationRoot)) {
+            scheduleViewportRefresh();
+        }
+    }
+    function preferredTargetIdentityChanged() {
+        const presentation = activePresentation;
+        const currentTarget = instance?.getActiveElement();
+        if (presentation === null
+            || presentation.step.target === null
+            || input.resolveTarget !== undefined
+            || !(currentTarget instanceof HTMLElement)) {
+            return true;
+        }
+        const currentVisible = targetVisibility.get(currentTarget)
+            ?? isVisibleTutorialTarget(currentTarget, browserWindow);
+        if (currentVisible && isStructurallyActivatableTutorialTarget(currentTarget)) {
+            return false;
+        }
+        const candidates = findComposedTutorialTargets(root, targetAttribute, presentation.step.target);
+        const nextTarget = candidates.find((candidate) => (isStructurallyActivatableTutorialTarget(candidate)
+            && (targetVisibility.get(candidate)
+                ?? isVisibleTutorialTarget(candidate, browserWindow))))
+            ?? candidates.find((candidate) => (targetVisibility.get(candidate) ?? isVisibleTutorialTarget(candidate, browserWindow)))
+            ?? currentTarget;
+        return nextTarget !== currentTarget;
+    }
+    function scheduleViewportRefresh() {
+        const presentation = activePresentation;
+        const activeElement = instance?.getActiveElement();
+        const restartPreferred = presentation !== null
+            && shouldPreferActivatableTutorialTarget(presentation)
+            && (!(activeElement instanceof HTMLElement)
+                || !isVisibleTutorialTarget(activeElement, browserWindow));
+        scheduleRefresh(restartPreferred);
+    }
+    reconcileMutationRoots(true);
+    resizeObserver = typeof browserWindow.ResizeObserver === 'function'
+        ? new browserWindow.ResizeObserver(processResizeRecords)
+        : null;
+    intersectionObserver = typeof browserWindow.IntersectionObserver === 'function'
+        ? new browserWindow.IntersectionObserver(processIntersectionRecords, { threshold: 0 })
         : null;
-    resizeObserver?.observe(observationRoot);
-    observationRoot.addEventListener('scroll', scheduleRefresh, true);
-    browserWindow.visualViewport?.addEventListener('resize', scheduleRefresh);
-    browserWindow.visualViewport?.addEventListener('scroll', scheduleRefresh);
-    browserWindow.addEventListener('orientationchange', scheduleRefresh);
+    resizeObserver?.observe(resizeObservationRoot);
+    ownerDocument.addEventListener('scroll', scheduleViewportRefresh, true);
+    browserWindow.addEventListener('resize', scheduleViewportRefresh);
+    browserWindow.visualViewport?.addEventListener('resize', scheduleViewportRefresh);
+    browserWindow.visualViewport?.addEventListener('scroll', scheduleViewportRefresh);
+    browserWindow.addEventListener('orientationchange', scheduleViewportRefresh);
     return {
         destroy() {
+            if (destroyed) {
+                return;
+            }
             destroyed = true;
             activePresentation = null;
             activePresentationKey = null;
@@ -264,11 +714,17 @@ export function createDriverTutorialPresenter(input) {
             retryableDismissedKey = null;
             missingTargetErrorKey = null;
             mutationObserver.disconnect();
+            observingDocumentMutations = false;
+            observedShadowRoots.clear();
+            cancelTargetGeometryMonitor();
+            clearTargetGeometryObservers();
             resizeObserver?.disconnect();
-            observationRoot.removeEventListener('scroll', scheduleRefresh, true);
-            browserWindow.visualViewport?.removeEventListener('resize', scheduleRefresh);
-            browserWindow.visualViewport?.removeEventListener('scroll', scheduleRefresh);
-            browserWindow.removeEventListener('orientationchange', scheduleRefresh);
+            intersectionObserver?.disconnect();
+            ownerDocument.removeEventListener('scroll', scheduleViewportRefresh, true);
+            browserWindow.removeEventListener('resize', scheduleViewportRefresh);
+            browserWindow.visualViewport?.removeEventListener('resize', scheduleViewportRefresh);
+            browserWindow.visualViewport?.removeEventListener('scroll', scheduleViewportRefresh);
+            browserWindow.removeEventListener('orientationchange', scheduleViewportRefresh);
             if (frame !== undefined) {
                 browserWindow.cancelAnimationFrame(frame);
             }
@@ -277,14 +733,26 @@ export function createDriverTutorialPresenter(input) {
             }
             instance = null;
             targetSemanticsGuard = undefined;
+            targetShadowPointerStyle?.remove();
+            targetShadowPointerStyle = undefined;
+            clearTargetAcknowledgeBinding();
+            clearTargetClickState();
             clearTutorialState(stateHost);
             reportActive(false);
         },
         present(presentation) {
+            if (destroyed) {
+                return;
+            }
             const nextKey = presentation === null
                 ? null
                 : JSON.stringify([
                     presentation.step.id,
+                    presentation.step.target,
+                    presentation.step.interaction,
+                    presentation.step.advance,
+                    presentation.step.side ?? null,
+                    presentation.step.align ?? null,
                     presentation.copy.title,
                     presentation.copy.description,
                     presentation.copy.next,
@@ -305,6 +773,7 @@ export function createDriverTutorialPresenter(input) {
             }
             if (activePresentationKey === nextKey) {
                 activePresentation = presentation;
+                reconcileMutationRoots(true);
                 scheduleRefresh();
                 return;
             }
@@ -315,11 +784,16 @@ export function createDriverTutorialPresenter(input) {
             if (previousInstance !== null) {
                 destroyInstancePreservingTarget(previousInstance);
             }
+            reconcileMutationRoots(true);
             clearTutorialState(stateHost);
             reportActive(false);
             scheduleRefresh();
         },
-        refresh: scheduleRefresh,
+        refresh() {
+            // attachShadow() itself emits no mutation, so explicit refresh also discovers new roots.
+            reconcileMutationRoots();
+            scheduleHostRefresh();
+        },
         resetForReplay() {
             dismissedPresentationKey = null;
             retryableDismissedKey = null;
@@ -332,7 +806,51 @@ export function createDriverTutorialPresenter(input) {
             }
         },
     };
+    function restartActiveInstance(currentInstance, presentation) {
+        const presentationKey = activePresentationKey;
+        restartingInstance = true;
+        try {
+            applyDriverTargetMutation(() => destroyInstancePreservingTarget(currentInstance));
+        }
+        finally {
+            restartingInstance = false;
+        }
+        if (!destroyed
+            && dismissedPresentationKey === null
+            && activePresentation === presentation
+            && activePresentationKey === presentationKey) {
+            driveActiveStep();
+        }
+        if (instance === null || !instance.isActive()) {
+            clearTutorialState(stateHost);
+            reportActive(false);
+        }
+    }
     function rebindActiveTarget(currentInstance, presentation) {
+        if (presentation !== null && shouldPreferActivatableTutorialTarget(presentation)) {
+            if (input.resolveTarget !== undefined && presentation.step.target !== null) {
+                const presentationKey = activePresentationKey;
+                const target = resolvePresentationTarget(presentation, presentationKey);
+                if (destroyed
+                    || activePresentation !== presentation
+                    || activePresentationKey !== presentationKey
+                    || instance !== currentInstance
+                    || !currentInstance.isActive()) {
+                    return;
+                }
+                const activeElement = currentInstance.getActiveElement();
+                const targetUnchanged = target === activeElement
+                    || (target === null && activeElement?.id === 'driver-dummy-element');
+                if (!targetUnchanged) {
+                    restartActiveInstance(currentInstance, presentation);
+                    return;
+                }
+            }
+            applyDriverTargetMutation(() => currentInstance.refresh());
+            syncModalSemantics?.();
+            syncPreferredTargetInteraction(currentInstance, presentation);
+            return;
+        }
         if (presentation === null || presentation.step.target === null || !currentInstance.isActive()) {
             applyDriverTargetMutation(() => currentInstance.refresh());
             syncModalSemantics?.();
@@ -388,18 +906,213 @@ export function createDriverTutorialPresenter(input) {
     function rebindTarget(currentInstance, presentation, target) {
         const previousTarget = currentInstance.getActiveElement();
         targetSemanticsGuard?.restore();
-        const restorePreviousTarget = !(previousTarget instanceof HTMLElement)
+        const restorePreviousTarget = previousTarget === target
+            || !(previousTarget instanceof HTMLElement)
             || previousTarget.id === 'driver-dummy-element'
             ? undefined
             : captureTutorialTargetSemantics(previousTarget, target?.parentElement ?? null);
         targetSemanticsGuard = target === undefined
             ? undefined
             : preserveTutorialTargetSemantics(target, browserWindow);
-        const nextStep = createDriveStep(input, presentation, target, ownerDocument);
-        applyDriverTargetMutation(() => currentInstance.highlight(nextStep));
+        const targetActivatable = target !== undefined
+            && isActivatableTutorialTarget(target, browserWindow);
+        const targetClickMode = resolveTutorialTargetClickMode(presentation, target, targetActivatable);
+        applyTargetClickMode(currentInstance, presentation, target, targetClickMode, targetActivatable);
+        downgradeInactiveTargetClickMode(currentInstance, presentation, target, targetClickMode);
         restorePreviousTarget?.();
         syncModalSemantics?.();
     }
+    function syncPreferredTargetInteraction(currentInstance, presentation) {
+        const target = currentInstance.getActiveElement();
+        if (!(target instanceof HTMLElement) || target.id === 'driver-dummy-element') {
+            return;
+        }
+        const targetActivatable = isActivatableTutorialTarget(target, browserWindow);
+        const desiredMode = resolveTutorialTargetClickMode(presentation, target, targetActivatable);
+        if (targetClickState?.acknowledgeOnTargetClick !== desiredMode.acknowledgeOnTargetClick) {
+            applyTargetClickMode(currentInstance, presentation, target, desiredMode, targetActivatable);
+        }
+        downgradeInactiveTargetClickMode(currentInstance, presentation, target, desiredMode);
+    }
+    function applyTargetClickMode(currentInstance, presentation, target, mode, targetActivatable) {
+        clearTargetOverlayPointerGuard();
+        const nextStep = createDriveStep(input, presentation, target, mode.acknowledgeOnTargetClick, ownerDocument, reportError);
+        clearTargetAcknowledgeBinding(currentInstance);
+        setTargetClickState(currentInstance, presentation, target, mode);
+        applyDriverTargetMutation(() => {
+            syncTargetShadowPointerStyle(presentation, target, targetActivatable);
+            currentInstance.highlight(nextStep);
+        });
+    }
+    function downgradeInactiveTargetClickMode(currentInstance, presentation, target, mode) {
+        const shadowTargetHitTestable = target === undefined
+            || isShadowTutorialTargetHitTestable(target);
+        if (mode.acknowledgeOnTargetClick
+            && target !== undefined
+            && (!isActivatableTutorialTarget(target, browserWindow)
+                || !shadowTargetHitTestable)) {
+            applyTargetClickMode(currentInstance, presentation, target, { acknowledgeOnTargetClick: false }, true);
+        }
+        else if (target !== undefined && shouldAllowTutorialTargetInteraction(presentation)) {
+            if (shadowTargetHitTestable) {
+                clearTargetOverlayPointerGuard();
+                scheduleShadowTargetHitTest(currentInstance, presentation, target);
+            }
+            else {
+                allowShadowTargetThroughOverlay(target);
+            }
+        }
+        syncTargetAcknowledgeBinding(currentInstance, presentation);
+    }
+    function isShadowTutorialTargetHitTestable(target) {
+        if (typeof ownerDocument.elementFromPoint !== 'function') {
+            return true;
+        }
+        const shadowRoots = [];
+        let current = target;
+        while (current !== null) {
+            const treeScope = current.getRootNode();
+            if (!(treeScope instanceof ShadowRoot)) {
+                break;
+            }
+            shadowRoots.unshift(treeScope);
+            current = treeScope.host;
+        }
+        const visibleRect = resolveTutorialTargetVisibleRect(target, browserWindow);
+        if (visibleRect === null) {
+            return false;
+        }
+        const x = (visibleRect.left + visibleRect.right) / 2;
+        const y = (visibleRect.top + visibleRect.bottom) / 2;
+        let hit = ownerDocument.elementFromPoint(x, y);
+        const outerHost = shadowRoots[0]?.host;
+        if (outerHost === undefined) {
+            return hit instanceof Element && isComposedAncestorOrSelf(hit, target);
+        }
+        if (!(hit instanceof Element)
+            || !isComposedAncestorOrSelf(hit, outerHost)) {
+            return false;
+        }
+        for (const [index, shadowRoot] of shadowRoots.entries()) {
+            if (typeof shadowRoot.elementFromPoint !== 'function') {
+                return false;
+            }
+            hit = shadowRoot.elementFromPoint(x, y);
+            const expectedTarget = shadowRoots[index + 1]?.host ?? target;
+            if (!(hit instanceof Element)
+                || !isComposedAncestorOrSelf(hit, expectedTarget)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    function scheduleShadowTargetHitTest(currentInstance, presentation, target) {
+        if (typeof ownerDocument.elementFromPoint !== 'function') {
+            return;
+        }
+        cancelShadowTargetHitTest();
+        const state = targetClickState;
+        const presentationKey = activePresentationKey;
+        targetHitTestFrame = browserWindow.requestAnimationFrame(() => {
+            targetHitTestFrame = undefined;
+            if (destroyed
+                || instance !== currentInstance
+                || !currentInstance.isActive()
+                || activePresentation !== presentation
+                || activePresentationKey !== presentationKey
+                || targetClickState?.driver !== currentInstance
+                || targetClickState.target !== target
+                || targetClickState.stepId !== presentation.step.id
+                || isShadowTutorialTargetHitTestable(target)) {
+                return;
+            }
+            if (state?.acknowledgeOnTargetClick === true) {
+                applyTargetClickMode(currentInstance, presentation, target, { acknowledgeOnTargetClick: false }, true);
+                syncTargetAcknowledgeBinding(currentInstance, presentation);
+                syncModalSemantics?.();
+            }
+            else {
+                allowShadowTargetThroughOverlay(target);
+            }
+        });
+    }
+    function allowShadowTargetThroughOverlay(target) {
+        clearTargetOverlayPointerGuard();
+        const overlay = ownerDocument.querySelector('.driver-overlay');
+        const rect = resolveTutorialTargetVisibleRect(target, browserWindow);
+        if (overlay === null || rect === null) {
+            return;
+        }
+        const x = (rect.left + rect.right) / 2;
+        const y = (rect.top + rect.bottom) / 2;
+        const blockingHit = ownerDocument.elementFromPoint(x, y);
+        if (!(blockingHit instanceof Element)
+            || (blockingHit !== overlay && !overlay.contains(blockingHit))) {
+            return;
+        }
+        const previousValue = overlay.style.getPropertyValue('pointer-events');
+        const previousPriority = overlay.style.getPropertyPriority('pointer-events');
+        const overlayZIndex = browserWindow.getComputedStyle(overlay).zIndex;
+        overlay.style.setProperty('pointer-events', 'none', 'important');
+        if (!isShadowTutorialTargetHitTestable(target)) {
+            if (previousValue === '') {
+                overlay.style.removeProperty('pointer-events');
+            }
+            else {
+                overlay.style.setProperty('pointer-events', previousValue, previousPriority);
+            }
+            return;
+        }
+        const viewport = resolveViewportRect(browserWindow);
+        const regions = [
+            { bottom: rect.top, left: viewport.left, right: viewport.right, top: viewport.top },
+            { bottom: viewport.bottom, left: viewport.left, right: viewport.right, top: rect.bottom },
+            { bottom: rect.bottom, left: viewport.left, right: rect.left, top: rect.top },
+            { bottom: rect.bottom, left: rect.right, right: viewport.right, top: rect.top },
+        ];
+        const blockers = regions.filter((region) => (region.right > region.left && region.bottom > region.top)).map((region) => {
+            const blocker = ownerDocument.createElement('div');
+            blocker.dataset.mpgdTutorialOutsideBlocker = 'true';
+            blocker.setAttribute('aria-hidden', 'true');
+            Object.assign(blocker.style, {
+                background: 'transparent',
+                height: `${region.bottom - region.top}px`,
+                left: `${region.left}px`,
+                pointerEvents: 'auto',
+                position: 'fixed',
+                top: `${region.top}px`,
+                width: `${region.right - region.left}px`,
+                zIndex: overlayZIndex,
+            });
+            ownerDocument.body.appendChild(blocker);
+            return blocker;
+        });
+        targetOverlayPointerRestore = () => {
+            for (const blocker of blockers) {
+                blocker.remove();
+            }
+            if (overlay.style.getPropertyValue('pointer-events') === 'none'
+                && overlay.style.getPropertyPriority('pointer-events') === 'important') {
+                if (previousValue === '') {
+                    overlay.style.removeProperty('pointer-events');
+                }
+                else {
+                    overlay.style.setProperty('pointer-events', previousValue, previousPriority);
+                }
+            }
+        };
+    }
+    function clearTargetOverlayPointerGuard() {
+        targetOverlayPointerRestore?.();
+        targetOverlayPointerRestore = undefined;
+    }
+    function cancelShadowTargetHitTest() {
+        if (targetHitTestFrame === undefined) {
+            return;
+        }
+        browserWindow.cancelAnimationFrame(targetHitTestFrame);
+        targetHitTestFrame = undefined;
+    }
     function reportMissingTarget(presentation, presentationKey = activePresentationKey) {
         if (presentationKey === null
             || presentationKey !== activePresentationKey
@@ -407,11 +1120,121 @@ export function createDriverTutorialPresenter(input) {
             return;
         }
         missingTargetErrorKey = presentationKey;
-        input.onError?.(new Error(`Tutorial target was not found: ${String(presentation.step.target)}`));
+        const target = String(presentation.step.target);
+        reportError(new Error(`Tutorial target was not found: ${target}`));
+    }
+    function syncTargetAcknowledgeBinding(currentInstance, presentation) {
+        clearTargetAcknowledgeBinding(currentInstance);
+        const state = targetClickState;
+        if (state === undefined
+            || state.driver !== currentInstance
+            || state.stepId !== presentation.step.id
+            || !state.acknowledgeOnTargetClick) {
+            return;
+        }
+        const { target } = state;
+        const presentationKey = activePresentationKey;
+        let acknowledgementQueued = false;
+        const listener = () => {
+            const targetActivatableAtCapture = isActivatableTutorialTarget(target, browserWindow);
+            if (acknowledgementQueued || !targetActivatableAtCapture) {
+                return;
+            }
+            acknowledgementQueued = true;
+            browserWindow.queueMicrotask(() => {
+                acknowledgementQueued = false;
+                if (destroyed
+                    || instance !== currentInstance
+                    || activePresentationKey !== presentationKey
+                    || targetClickState !== state) {
+                    return;
+                }
+                try {
+                    input.onAcknowledge(presentation.step.id);
+                }
+                catch (error) {
+                    reportError(error);
+                }
+            });
+        };
+        target.addEventListener('click', listener, true);
+        targetAcknowledgeBinding = {
+            driver: currentInstance,
+            listener,
+            stepId: presentation.step.id,
+            target,
+        };
+    }
+    function clearTargetAcknowledgeBinding(currentInstance) {
+        const binding = targetAcknowledgeBinding;
+        if (binding === undefined
+            || (currentInstance !== undefined && binding.driver !== currentInstance)) {
+            return;
+        }
+        binding.target.removeEventListener('click', binding.listener, true);
+        targetAcknowledgeBinding = undefined;
+    }
+    function setTargetClickState(currentInstance, presentation, target, mode) {
+        cancelShadowTargetHitTest();
+        targetClickState = target === undefined
+            ? undefined
+            : {
+                ...mode,
+                driver: currentInstance,
+                stepId: presentation.step.id,
+                target,
+            };
+    }
+    function clearTargetClickState(currentInstance) {
+        if (currentInstance !== undefined && targetClickState?.driver !== currentInstance) {
+            return;
+        }
+        cancelShadowTargetHitTest();
+        clearTargetOverlayPointerGuard();
+        targetClickState = undefined;
+    }
+    function syncTargetShadowPointerStyle(presentation, target, targetActivatable) {
+        targetShadowPointerStyle?.remove();
+        targetShadowPointerStyle = undefined;
+        if (target === undefined
+            || !targetActivatable
+            || !shouldAllowTutorialTargetInteraction(presentation)) {
+            return;
+        }
+        const targetRoot = target.getRootNode();
+        if (!(targetRoot instanceof ShadowRoot)) {
+            return;
+        }
+        const targetPosition = browserWindow.getComputedStyle(target).position;
+        const positionRule = targetPosition === '' || targetPosition === 'static'
+            ? 'position: relative !important;'
+            : '';
+        const style = ownerDocument.createElement('style');
+        style.textContent = `
+      .driver-active-element:not(.driver-no-interaction) {
+        ${positionRule}
+        z-index: 1000000001 !important;
+        pointer-events: auto !important;
+      }
+      .driver-active-element:not(.driver-no-interaction) * {
+        pointer-events: auto !important;
+      }
+      .driver-no-interaction,
+      .driver-no-interaction * {
+        pointer-events: none !important;
+      }
+    `;
+        targetRoot.appendChild(style);
+        targetShadowPointerStyle = style;
     }
     function destroyInstancePreservingTarget(currentInstance) {
+        cancelTargetGeometryMonitor();
+        clearTargetGeometryObservers();
         const target = currentInstance.getActiveElement();
         targetSemanticsGuard?.restore();
+        targetSemanticsGuard = undefined;
+        targetShadowPointerStyle?.remove();
+        targetShadowPointerStyle = undefined;
         const restoreAfterDestroy = !(target instanceof HTMLElement)
             ? undefined
             : captureTutorialTargetSemantics(target);
@@ -419,12 +1242,30 @@ export function createDriverTutorialPresenter(input) {
         currentInstance.destroy();
         targetRestorePending = false;
         restoreAfterDestroy?.();
-        targetSemanticsGuard = undefined;
     }
     function applyDriverTargetMutation(mutation) {
-        return targetSemanticsGuard === undefined
-            ? mutation()
-            : targetSemanticsGuard.applyDriverMutation(mutation);
+        processMutationRecords(mutationObserver.takeRecords());
+        mutationObserver.disconnect();
+        try {
+            return targetSemanticsGuard === undefined
+                ? mutation()
+                : targetSemanticsGuard.applyDriverMutation(mutation);
+        }
+        finally {
+            if (!destroyed) {
+                reconcileMutationRoots(true);
+            }
+        }
+    }
+    function resolveTutorialTargetClickMode(presentation, target, targetActivatable) {
+        return {
+            acknowledgeOnTargetClick: target !== undefined
+                && presentation.acknowledgeOnTargetClick === true
+                && presentation.step.advance.kind === 'acknowledge'
+                && presentation.step.target !== null
+                && target.id !== 'driver-dummy-element'
+                && targetActivatable,
+        };
     }
 }
 export function resolveVisibleTutorialTarget(input) {
@@ -438,39 +1279,103 @@ export function resolveVisibleTutorialTarget(input) {
         return null;
     }
     const attribute = input.targetAttribute ?? tutorialDomAttributes.target;
-    const selector = `[${attribute}="${escapeAttributeValue(input.target)}"]`;
-    const candidates = [...root.querySelectorAll(selector)];
+    const candidates = findComposedTutorialTargets(root, attribute, input.target);
+    if (input.preferActivatable === true) {
+        return candidates.find((element) => isActivatableTutorialTarget(element, view)
+            && isVisibleTutorialTarget(element, view))
+            ?? candidates.find((element) => (isActivatableTutorialTarget(element, view) && isEligibleTutorialTarget(element, view)))
+            ?? candidates.find((element) => isVisibleTutorialTarget(element, view))
+            ?? candidates.find((element) => isEligibleTutorialTarget(element, view))
+            ?? null;
+    }
     return candidates.find((element) => isVisibleTutorialTarget(element, view))
-        ?? candidates.find((element) => isRenderableTutorialTarget(element, view))
+        ?? candidates.find((element) => isEligibleTutorialTarget(element, view))
         ?? null;
 }
+function findComposedTutorialTargets(root, attribute, target) {
+    return findComposedTutorialCandidates(root, `[${attribute}]`)
+        .filter((candidate) => candidate.getAttribute(attribute) === target);
+}
 export function isVisibleTutorialTarget(element, view = window) {
-    if (!isRenderableTutorialTarget(element, view)) {
+    return isVisibleTutorialTargetWithRect(element, view, element.getBoundingClientRect());
+}
+function isVisibleTutorialTargetWithRect(element, view, rect) {
+    if (!isEligibleTutorialTargetWithRect(element, view, rect)) {
         return false;
     }
-    let visible = intersectRect(element.getBoundingClientRect(), {
-        bottom: view.innerHeight,
-        left: 0,
-        right: view.innerWidth,
-        top: 0,
-    });
-    let ancestor = element.parentElement;
+    const visible = resolveTutorialTargetVisibleRect(element, view, rect);
+    return visible !== null;
+}
+function resolveTutorialTargetVisibleRect(element, view, rect = element.getBoundingClientRect()) {
+    let visible = intersectRect(rect, resolveViewportRect(view));
+    let ancestor = getComposedParentElement(element);
     while (visible !== null && ancestor !== null) {
         const style = view.getComputedStyle(ancestor);
         if (style.display === 'none'
             || style.visibility === 'hidden'
             || Number.parseFloat(style.opacity || '1') <= 0) {
-            return false;
+            return null;
         }
         if ([style.overflow, style.overflowX, style.overflowY].some((value) => value === 'auto' || value === 'clip' || value === 'hidden' || value === 'scroll')) {
             visible = intersectRect(visible, ancestor.getBoundingClientRect());
         }
-        ancestor = ancestor.parentElement;
+        ancestor = getComposedParentElement(ancestor);
     }
-    return visible !== null && visible.right > visible.left && visible.bottom > visible.top;
+    return visible;
+}
+function readTutorialTargetRect(element) {
+    const rect = element.getBoundingClientRect();
+    return {
+        bottom: rect.bottom,
+        height: rect.height,
+        left: rect.left,
+        right: rect.right,
+        top: rect.top,
+        width: rect.width,
+    };
+}
+function tutorialTargetRectsEqual(left, right) {
+    return left.bottom === right.bottom
+        && left.height === right.height
+        && left.left === right.left
+        && left.right === right.right
+        && left.top === right.top
+        && left.width === right.width;
+}
+function resolveViewportRect(view) {
+    const visualViewport = view.visualViewport;
+    if (visualViewport !== undefined
+        && visualViewport !== null
+        && Number.isFinite(visualViewport.offsetLeft)
+        && Number.isFinite(visualViewport.offsetTop)
+        && Number.isFinite(visualViewport.width)
+        && Number.isFinite(visualViewport.height)
+        && visualViewport.width > 0
+        && visualViewport.height > 0) {
+        return {
+            bottom: visualViewport.offsetTop + visualViewport.height,
+            left: visualViewport.offsetLeft,
+            right: visualViewport.offsetLeft + visualViewport.width,
+            top: visualViewport.offsetTop,
+        };
+    }
+    return {
+        bottom: view.innerHeight,
+        left: 0,
+        right: view.innerWidth,
+        top: 0,
+    };
 }
 export function bindTutorialReplayTrigger(input) {
     let pending = false;
+    const reportError = (error) => {
+        try {
+            input.onError?.(error);
+        }
+        catch {
+            // Error reporting must not interrupt replay trigger lifecycle handling.
+        }
+    };
     const listener = () => {
         if (pending) {
             return;
@@ -482,7 +1387,7 @@ export function bindTutorialReplayTrigger(input) {
             .then(() => input.presenter.waitForPendingSkip())
             .then(() => input.director.replay())
             .then(() => input.presenter.resetForReplay())
-            .catch((error) => input.onError?.(error))
+            .catch(reportError)
             .finally(() => {
             pending = false;
         });
@@ -490,20 +1395,17 @@ export function bindTutorialReplayTrigger(input) {
     input.element.addEventListener('click', listener);
     return () => input.element.removeEventListener('click', listener);
 }
-function createDriveStep(input, presentation, target, ownerDocument) {
+function createDriveStep(input, presentation, target, acknowledgeOnTargetClick, ownerDocument, reportError) {
     const { step } = presentation;
     const actionGated = step.advance.kind === 'action' || step.advance.kind === 'signal';
-    const acknowledgeOnTargetClick = presentation.acknowledgeOnTargetClick === true
-        && step.advance.kind === 'acknowledge'
-        && step.target !== null
-        && target !== undefined;
     const targetInteraction = presentation.allowTargetInteraction === true
         || acknowledgeOnTargetClick
         || step.interaction === 'target'
         || step.interaction === 'gameplay';
     return {
         ...(target === undefined ? {} : { element: target }),
-        advanceOnClick: acknowledgeOnTargetClick,
+        // The presenter owns target clicks so Shadow DOM retargeting cannot hide them from Driver.
+        advanceOnClick: false,
         disableActiveInteraction: !targetInteraction,
         popover: {
             ...(step.side === undefined ? {} : { side: step.side }),
@@ -519,26 +1421,128 @@ function createDriveStep(input, presentation, target, ownerDocument) {
                 ? ['close']
                 : ['next', 'close'],
             title: escapeTutorialText(ownerDocument, presentation.copy.title),
-            onNextClick: () => input.onAcknowledge(step.id),
+            onNextClick: () => {
+                try {
+                    input.onAcknowledge(step.id);
+                }
+                catch (error) {
+                    reportError(error);
+                }
+            },
         },
     };
 }
-function resolveUnderlyingTutorialModal(popover, interaction, activeElement, modalSelector, currentModal) {
-    const activeModal = activeElement?.closest(modalSelector) ?? null;
+function shouldAllowTutorialTargetInteraction(presentation) {
+    const { step } = presentation;
+    return presentation.allowTargetInteraction === true
+        || (presentation.acknowledgeOnTargetClick === true
+            && step.advance.kind === 'acknowledge')
+        || step.interaction === 'target'
+        || step.interaction === 'gameplay';
+}
+function shouldPreferActivatableTutorialTarget(presentation) {
+    const { step } = presentation;
+    const targetInteraction = presentation.allowTargetInteraction === true
+        || step.interaction === 'target'
+        || step.interaction === 'gameplay';
+    const acknowledgeOnTargetClick = presentation.acknowledgeOnTargetClick === true
+        && step.advance.kind === 'acknowledge';
+    const targetGated = targetInteraction
+        && (step.advance.kind === 'action' || step.advance.kind === 'signal');
+    return acknowledgeOnTargetClick || targetGated;
+}
+function resolveUnderlyingTutorialModal(popover, interaction, activeElement, modalSelector, currentModal, retainCurrentModal) {
+    const activeModal = findClosestComposedTutorialModal(activeElement, modalSelector);
+    const view = popover.ownerDocument.defaultView;
+    const isRenderableModal = (candidate) => (candidate !== null
+        && candidate !== popover
+        && !popover.contains(candidate)
+        && view !== null
+        && isEligibleUnderlyingTutorialModal(candidate, view));
+    const hostReactivatedCurrentModal = currentModal?.getAttribute('aria-modal')
+        ?.toLowerCase() === 'true';
+    const canSelectCurrentModal = interaction !== 'blocked'
+        || retainCurrentModal
+        || hostReactivatedCurrentModal;
+    const isSelectableModal = (candidate) => (isRenderableModal(candidate)
+        && (candidate !== currentModal || canSelectCurrentModal));
+    const renderableActiveModal = isSelectableModal(activeModal) ? activeModal : null;
+    const renderableCurrentModal = isRenderableModal(currentModal) ? currentModal : null;
     if (interaction !== 'blocked') {
-        return activeModal;
+        return renderableActiveModal;
     }
-    if (activeElement !== undefined
-        && currentModal?.isConnected === true
-        && currentModal.contains(activeElement)) {
-        return currentModal;
+    if (retainCurrentModal
+        && activeElement !== undefined
+        && renderableCurrentModal?.contains(activeElement) === true) {
+        return renderableCurrentModal;
     }
-    return activeModal
-        ?? [...popover.ownerDocument.querySelectorAll(modalSelector)]
-            .find((candidate) => candidate !== popover && !popover.contains(candidate))
-        ?? (currentModal?.isConnected === true ? currentModal : null)
+    return renderableActiveModal
+        ?? (canSelectCurrentModal ? renderableCurrentModal : null)
+        ?? findComposedTutorialCandidates(popover.ownerDocument, modalSelector)
+            .find(isSelectableModal)
         ?? null;
 }
+function findClosestComposedTutorialModal(activeElement, selector) {
+    let current = activeElement ?? null;
+    while (current !== null) {
+        if (current instanceof HTMLElement && current.matches(selector)) {
+            return current;
+        }
+        current = getComposedParentElement(current);
+    }
+    return null;
+}
+function findComposedTutorialCandidates(root, selector) {
+    const matches = [];
+    visitComposedTutorialElements(root, (element) => {
+        if (element instanceof HTMLElement && element.matches(selector)) {
+            matches.push(element);
+        }
+    });
+    return matches;
+}
+function findOpenTutorialShadowRoots(ownerDocument) {
+    const shadowRoots = [];
+    visitComposedTutorialElements(ownerDocument, (element) => {
+        if (element.shadowRoot !== null) {
+            shadowRoots.push(element.shadowRoot);
+        }
+    });
+    return shadowRoots;
+}
+function visitComposedTutorialElements(root, visitor) {
+    const visited = new Set();
+    const visit = (element) => {
+        if (visited.has(element)) {
+            return;
+        }
+        visited.add(element);
+        visitor(element);
+        visitComposedChildren(element);
+    };
+    const visitChildren = (parent) => {
+        for (const child of parent.children) {
+            visit(child);
+        }
+    };
+    const visitComposedChildren = (parent) => {
+        if (parent instanceof Element && parent.shadowRoot !== null) {
+            visitChildren(parent.shadowRoot);
+            return;
+        }
+        if (parent instanceof HTMLSlotElement) {
+            const assignedElements = parent.assignedElements({ flatten: true });
+            if (assignedElements.length > 0) {
+                for (const assignedElement of assignedElements) {
+                    visit(assignedElement);
+                }
+                return;
+            }
+        }
+        visitChildren(parent);
+    };
+    visitComposedChildren(root);
+}
 function configureTutorialModalSemantics(popover, interaction, underlyingModal) {
     const ownedAttributes = new Map();
     if (interaction === 'blocked') {
@@ -557,15 +1561,23 @@ function configureTutorialModalSemantics(popover, interaction, underlyingModal)
             ownedAttributes.set('aria-owns', [...ownedIds].join(' '));
         }
     }
-    const restore = underlyingModal === null
-        ? () => undefined
+    const attributeGuard = underlyingModal === null
+        ? null
         : preserveTutorialModalSemantics(underlyingModal, ownedAttributes, popover.ownerDocument);
-    return { modal: underlyingModal, popover, restore };
+    return {
+        isOwnedAttributeCurrent: (attribute) => attributeGuard?.isOwned(attribute) ?? false,
+        modal: underlyingModal,
+        popover,
+        restore: () => attributeGuard?.restore(),
+    };
 }
 function preserveTutorialModalSemantics(element, ownedAttributes, ownerDocument) {
     const view = ownerDocument.defaultView;
     if (view === null || ownedAttributes.size === 0) {
-        return () => undefined;
+        return {
+            isOwned: () => false,
+            restore: () => undefined,
+        };
     }
     const previous = new Map();
     const hostValues = new Map();
@@ -586,25 +1598,49 @@ function preserveTutorialModalSemantics(element, ownedAttributes, ownerDocument)
         element.setAttribute(attribute, value);
     }
     if (previous.size === 0) {
-        return () => undefined;
+        return {
+            isOwned: () => false,
+            restore: () => undefined,
+        };
     }
     const observer = new view.MutationObserver(captureHostMutations);
     observer.observe(element, {
         attributeFilter: [...previous.keys()],
         attributes: true,
     });
-    return () => {
-        captureHostMutations(observer.takeRecords());
-        observer.disconnect();
-        for (const [attribute, previousValue] of previous) {
-            if (hostValues.has(attribute)) {
-                restoreAttribute(element, attribute, hostValues.get(attribute) ?? null);
-                continue;
+    return {
+        isOwned(attribute) {
+            captureHostMutations(observer.takeRecords());
+            return previous.has(attribute)
+                && !hostValues.has(attribute)
+                && element.getAttribute(attribute) === ownedAttributes.get(attribute);
+        },
+        restore() {
+            captureHostMutations(observer.takeRecords());
+            observer.disconnect();
+            for (const [attribute, previousValue] of previous) {
+                if (hostValues.has(attribute)) {
+                    const hostValue = hostValues.get(attribute) ?? null;
+                    const restoredHostValue = attribute === 'aria-owns'
+                        ? removeTutorialOwnedAriaTokens(hostValue, ownedAttributes.get(attribute) ?? '', previousValue)
+                        : hostValue;
+                    restoreAttribute(element, attribute, restoredHostValue);
+                    continue;
+                }
+                restoreOwnedAttribute(element, attribute, ownedAttributes.get(attribute) ?? null, previousValue);
             }
-            restoreOwnedAttribute(element, attribute, ownedAttributes.get(attribute) ?? null, previousValue);
-        }
+        },
     };
 }
+function removeTutorialOwnedAriaTokens(hostValue, ownedValue, previousValue) {
+    if (hostValue === null) {
+        return null;
+    }
+    const previousTokens = new Set((previousValue ?? '').split(/\s+/u).filter(Boolean));
+    const tutorialTokens = new Set(ownedValue.split(/\s+/u).filter((token) => token !== '' && !previousTokens.has(token)));
+    const remaining = hostValue.split(/\s+/u).filter((token) => token !== '' && !tutorialTokens.has(token));
+    return remaining.length === 0 ? null : remaining.join(' ');
+}
 function isTutorialModalAttribute(attribute) {
     return attribute === 'aria-modal' || attribute === 'aria-owns';
 }
@@ -691,7 +1727,9 @@ function clearDetachedDriverTargetClasses(element, decoratedParent, preservedPar
     }
 }
 function isRenderableTutorialTarget(element, view) {
-    const rect = element.getBoundingClientRect();
+    return isRenderableTutorialTargetWithRect(element, view, element.getBoundingClientRect());
+}
+function isRenderableTutorialTargetWithRect(element, view, rect) {
     if (!element.isConnected || rect.width <= 0 || rect.height <= 0) {
         return false;
     }
@@ -703,10 +1741,85 @@ function isRenderableTutorialTarget(element, view) {
             || Number.parseFloat(style.opacity || '1') <= 0) {
             return false;
         }
-        current = current.parentElement;
+        current = getComposedParentElement(current);
+    }
+    return true;
+}
+function isEligibleUnderlyingTutorialModal(element, view) {
+    return isEligibleTutorialTarget(element, view);
+}
+function isEligibleTutorialTarget(element, view) {
+    return isRenderableTutorialTarget(element, view)
+        && isSemanticallyActiveTutorialElement(element);
+}
+function isEligibleTutorialTargetWithRect(element, view, rect) {
+    return isRenderableTutorialTargetWithRect(element, view, rect)
+        && isSemanticallyActiveTutorialElement(element);
+}
+function isActivatableTutorialTarget(element, view = element.ownerDocument.defaultView) {
+    if (view === null
+        || view.getComputedStyle(element).pointerEvents === 'none'
+        || !isStructurallyActivatableTutorialTarget(element)
+        || !isSemanticallyActiveTutorialElement(element)) {
+        return false;
+    }
+    return true;
+}
+function isStructurallyActivatableTutorialTarget(element) {
+    if (element.matches(':disabled')) {
+        return false;
+    }
+    let current = element;
+    while (current !== null) {
+        if (current.getAttribute('aria-disabled')?.toLowerCase() === 'true') {
+            return false;
+        }
+        current = getComposedParentElement(current);
+    }
+    return true;
+}
+function isSemanticallyActiveTutorialElement(element) {
+    let current = element;
+    while (current !== null) {
+        if (current.getAttribute('aria-hidden')?.toLowerCase() === 'true'
+            || current.inert
+            || current.hasAttribute('inert')) {
+            return false;
+        }
+        current = getComposedParentElement(current);
     }
     return true;
 }
+function getComposedParentElement(element) {
+    if (element.assignedSlot !== null) {
+        return element.assignedSlot;
+    }
+    if (element.parentElement !== null) {
+        return element.parentElement;
+    }
+    const root = element.getRootNode();
+    return root instanceof ShadowRoot && root.host instanceof HTMLElement ? root.host : null;
+}
+function isComposedAncestorOrSelf(element, candidateAncestor) {
+    let current = element;
+    while (current !== null) {
+        if (current === candidateAncestor) {
+            return true;
+        }
+        current = getComposedParentElement(current);
+    }
+    return false;
+}
+function composedElementUsesTreeScope(element, treeScope) {
+    let current = element;
+    while (current !== null) {
+        if (current.getRootNode() === treeScope) {
+            return true;
+        }
+        current = getComposedParentElement(current);
+    }
+    return false;
+}
 function intersectRect(left, right) {
     const intersection = {
         bottom: Math.min(left.bottom, right.bottom),
@@ -737,16 +1850,21 @@ function restoreOwnedAttribute(element, name, ownedValue, previousValue) {
     restoreAttribute(element, name, previousValue);
 }
 function isDriverOwnedMutation(record) {
+    if (record.type === 'childList'
+        && [...record.addedNodes, ...record.removedNodes].every(isTutorialOutsideBlocker)) {
+        return true;
+    }
     const target = record.target;
-    if (target.nodeType !== 1) {
+    const element = target instanceof Element ? target : target.parentElement;
+    if (element === null) {
         return false;
     }
-    const element = target;
-    return element.matches('.driver-overlay, .driver-popover, .driver-popover *')
-        || element.closest('.driver-overlay, .driver-popover') !== null;
+    return element.matches('.driver-overlay, .driver-popover, .driver-popover *, '
+        + '[data-mpgd-tutorial-outside-blocker]')
+        || element.closest('.driver-overlay, .driver-popover, [data-mpgd-tutorial-outside-blocker]') !== null;
 }
-function escapeAttributeValue(value) {
-    return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+function isTutorialOutsideBlocker(node) {
+    return node instanceof Element && node.matches('[data-mpgd-tutorial-outside-blocker]');
 }
 function escapeTutorialText(ownerDocument, value) {
     const element = ownerDocument.createElement('span');