@guided-tour-s4marth/core 0.1.0

package/dist/player.js

@@ -0,0 +1,270 @@
+import { driver } from 'driver.js';
+import { resolveAnchor, waitForAnchor } from './resolver.js';
+import { decodeLocator, waitForLocator } from './locator.js';
+import { emit } from './telemetry.js';
+function waitMs(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+async function runPrepare(step, anchorMeta, navigate, waitForElement) {
+    if (!step.prepare?.length)
+        return;
+    for (const action of step.prepare) {
+        if (action.action === 'navigate') {
+            if (navigate)
+                await navigate(action.route);
+            // Give React time to commit the new route before continuing
+            await waitMs(300);
+        }
+        else if (action.action === 'click') {
+            const el = resolveAnchor(action.anchorId, anchorMeta);
+            if (el)
+                el.click();
+            await waitMs(150);
+        }
+        else if (action.action === 'wait') {
+            if (action.anchorId && waitForElement) {
+                const selector = `[data-tour="${CSS.escape(action.anchorId)}"]`;
+                await waitForElement(selector, action.timeoutMs);
+            }
+            else {
+                await waitMs(action.timeoutMs ?? 300);
+            }
+        }
+    }
+}
+// The full polished stylesheet is static and driven by CSS variables with good
+// defaults; a tour/provider theme only overrides the variables it sets. This is
+// injected once (idempotent) so even an un-themed tour looks modern out of the box.
+// Note: backdrop-filter: blur() is intentionally excluded — it blurs the cutout too.
+const TOUR_STYLESHEET = `
+.driver-popover {
+  background: var(--tour-bg, #ffffff);
+  color: var(--tour-text, #0f172a);
+  font-family: var(--tour-font, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
+  border-radius: var(--tour-radius, 14px);
+  border: 1px solid var(--tour-border, rgba(15,23,42,0.08));
+  box-shadow: var(--tour-shadow, 0 16px 40px rgba(2,6,23,0.28), 0 2px 8px rgba(2,6,23,0.12));
+  padding: 18px 18px 14px;
+  max-width: 340px;
+  animation: tour-pop-in 0.24s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+.driver-popover-title {
+  font-size: 15px; font-weight: 650; line-height: 1.35;
+  color: var(--tour-text, #0f172a); margin: 0 0 6px;
+}
+.driver-popover-description {
+  font-size: 13px; line-height: 1.55;
+  color: var(--tour-muted, #64748b); margin: 0;
+}
+.driver-popover-progress-text {
+  font-size: 11px; font-weight: 600; letter-spacing: 0.05em; text-transform: uppercase;
+  color: var(--tour-muted, #94a3b8);
+}
+.driver-popover-footer { margin-top: 16px; gap: 8px; }
+.driver-popover-footer button {
+  font-family: inherit; font-size: 12.5px; font-weight: 600;
+  padding: 7px 14px; border-radius: calc(var(--tour-radius, 14px) * 0.55);
+  cursor: pointer; text-shadow: none;
+  transition: background 0.15s ease, box-shadow 0.15s ease, filter 0.15s ease, transform 0.06s ease;
+}
+.driver-popover-footer button:active { transform: translateY(0.5px); }
+.driver-popover-footer button:focus-visible {
+  outline: 2px solid var(--tour-primary, #6366f1); outline-offset: 2px;
+}
+.driver-popover-next-btn, .driver-popover-done-btn {
+  background: var(--tour-primary, #6366f1);
+  color: var(--tour-primary-text, #ffffff);
+  border: 1px solid var(--tour-primary, #6366f1);
+}
+.driver-popover-next-btn:hover, .driver-popover-done-btn:hover {
+  filter: brightness(1.08);
+}
+.driver-popover-prev-btn {
+  background: transparent; color: var(--tour-muted, #64748b);
+  border: 1px solid var(--tour-border, rgba(100,116,139,0.30));
+}
+.driver-popover-prev-btn:hover { background: var(--tour-hover, rgba(15,23,42,0.05)); }
+.driver-popover-close-btn {
+  color: var(--tour-muted, #94a3b8);
+  transition: color 0.15s ease, transform 0.15s ease;
+}
+.driver-popover-close-btn:hover { color: var(--tour-text, #0f172a); transform: scale(1.12); }
+.driver-popover-arrow-side-left.driver-popover-arrow { border-left-color: var(--tour-bg, #ffffff); }
+.driver-popover-arrow-side-right.driver-popover-arrow { border-right-color: var(--tour-bg, #ffffff); }
+.driver-popover-arrow-side-top.driver-popover-arrow { border-top-color: var(--tour-bg, #ffffff); }
+.driver-popover-arrow-side-bottom.driver-popover-arrow { border-bottom-color: var(--tour-bg, #ffffff); }
+@keyframes tour-pop-in { from { opacity: 0; transform: translateY(6px) scale(0.98); } to { opacity: 1; transform: none; } }
+@media (prefers-reduced-motion: reduce) { .driver-popover { animation: none; } }
+`;
+function injectThemeStyle(theme) {
+    let el = document.getElementById('__tour-theme__');
+    if (!el) {
+        el = document.createElement('style');
+        el.id = '__tour-theme__';
+        document.head.appendChild(el);
+    }
+    // Only the variables the theme overrides are emitted; everything else uses the
+    // built-in defaults baked into TOUR_STYLESHEET via var() fallbacks.
+    const vars = [];
+    if (theme.popoverBg)
+        vars.push(`--tour-bg:${theme.popoverBg}`);
+    if (theme.textColor)
+        vars.push(`--tour-text:${theme.textColor}`);
+    if (theme.mutedColor)
+        vars.push(`--tour-muted:${theme.mutedColor}`);
+    if (theme.primaryColor)
+        vars.push(`--tour-primary:${theme.primaryColor}`);
+    if (theme.primaryTextColor)
+        vars.push(`--tour-primary-text:${theme.primaryTextColor}`);
+    if (theme.borderRadius)
+        vars.push(`--tour-radius:${theme.borderRadius}`);
+    if (theme.fontFamily)
+        vars.push(`--tour-font:${theme.fontFamily}`);
+    if (theme.shadow)
+        vars.push(`--tour-shadow:${theme.shadow}`);
+    el.textContent = `${vars.length ? `:root{${vars.join(';')}}` : ''}\n${TOUR_STYLESHEET}`;
+}
+function buildPopover(step, stepNumber, totalVisible, isLast) {
+    const side = step.placement === 'auto' ? undefined : step.placement;
+    return {
+        title: step.title,
+        description: step.body,
+        showButtons: ['next', 'close'],
+        showProgress: true,
+        progressText: `${stepNumber} of ${totalVisible}`,
+        ...(isLast ? { nextBtnText: 'Done' } : {}),
+        ...(side ? { side } : {}),
+    };
+}
+// ─── Main ─────────────────────────────────────────────────────────────────────
+export async function playTour(opts) {
+    const { tour, anchorMeta = {}, theme, onComplete, onSkip, onStepChange, onUnavailable, navigate, waitForElement } = opts;
+    // Always inject — the stylesheet carries the polished defaults, and any theme
+    // (provider theme < tour.theme) just overrides the CSS variables it sets.
+    const mergedTheme = { ...theme, ...(tour.theme ?? {}) };
+    injectThemeStyle(mergedTheme);
+    emit({ type: 'tour.started', tourId: tour.id });
+    // Count displayable steps upfront for the progress indicator.
+    // Floating steps (no anchorId) always count; anchored steps count even if
+    // the element isn't in DOM yet — we'll wait for it below.
+    const totalVisible = tour.steps.length;
+    let stepNumber = 0;
+    let shownCount = 0; // steps actually displayed
+    const missingAnchors = []; // anchored steps whose target never resolved
+    // ── One persistent driver instance for the whole tour ──────────────────────
+    // Reusing it lets driver.js animate the spotlight gliding between elements (and
+    // smooth-scroll them into view) — the "shifting focus" feel — instead of the
+    // overlay disappearing and popping back for each step.
+    let currentResolve = null;
+    let torn = false;
+    const settle = (action) => {
+        const resolve = currentResolve;
+        currentResolve = null;
+        resolve?.(action);
+    };
+    const teardown = () => {
+        if (torn)
+            return;
+        torn = true;
+        driverObj.destroy();
+    };
+    const driverObj = driver({
+        allowClose: true,
+        overlayColor: mergedTheme.overlayColor ?? '#0b1220',
+        overlayOpacity: mergedTheme.overlayOpacity ?? 0.55,
+        stagePadding: mergedTheme.stagePadding ?? 8,
+        stageRadius: mergedTheme.stageRadius ?? 8,
+        animate: mergedTheme.animate ?? true,
+        smoothScroll: true,
+        ...(mergedTheme.popoverClass ? { popoverClass: mergedTheme.popoverClass } : {}),
+        // Manual mode (hooks defined): the buttons do only what these say, so we
+        // drive step transitions ourselves via highlight() — keeping one instance.
+        // Next does NOT destroy; we just resolve and the loop highlights the next
+        // step on the same instance (the animated move). Close/esc tear down.
+        onNextClick: () => settle('next'),
+        onCloseClick: () => settle('skip'),
+        onDestroyStarted: () => { settle('skip'); teardown(); },
+    });
+    const waitForAction = () => new Promise(resolve => { currentResolve = resolve; });
+    for (let i = 0; i < tour.steps.length; i++) {
+        const step = tour.steps[i];
+        if (!step)
+            continue;
+        // ── 1. Run this step's prepare path (navigate + click + wait) ──────────
+        // This runs just before the step is shown, NOT at tour start.
+        // Navigations actually fire here, in the right sequence.
+        await runPrepare(step, anchorMeta, navigate, waitForElement);
+        // ── 2. Wait for the anchor element to appear in the DOM ────────────────
+        // Only wait the full timeout when this step navigated (new route renders
+        // async); otherwise a short wait, so a missing anchor doesn't hang for 5s.
+        const locator = step.anchorId ? decodeLocator(step.anchorId) : null;
+        if (step.anchorId) {
+            const hadNav = step.prepare?.some(a => a.action === 'navigate') ?? false;
+            const timeout = hadNav ? 5000 : 1500;
+            if (locator) {
+                // Encoded multi-signal locator — wait for it to resolve (signals/heal).
+                await waitForLocator(locator, timeout);
+            }
+            else if (waitForElement) {
+                await waitForElement(`[data-tour="${CSS.escape(step.anchorId)}"]`, timeout);
+            }
+            else {
+                await waitForAnchor(step.anchorId, timeout);
+            }
+        }
+        // ── 3. Resolve element ────────────────────────────────────────────────
+        let element;
+        if (step.anchorId) {
+            const el = resolveAnchor(step.anchorId, anchorMeta, tour.id, i);
+            if (!el) {
+                // Target missing — skip this step but keep the tour going. Telemetry
+                // (anchor.broken) already emitted by resolveAnchor.
+                missingAnchors.push(step.anchorId);
+                continue;
+            }
+            element = el;
+            // No manual scroll/settle here — driver.js (smoothScroll) scrolls the
+            // element into view and animates the stage as part of highlight().
+        }
+        stepNumber++;
+        const isLast = i === tour.steps.length - 1;
+        // ── 4. Emit telemetry + notify step change ─────────────────────────────
+        onStepChange?.(i);
+        const viewedEvent = step.anchorId
+            ? { type: 'step.viewed', tourId: tour.id, stepIndex: i, anchorId: step.anchorId }
+            : { type: 'step.viewed', tourId: tour.id, stepIndex: i };
+        emit(viewedEvent);
+        // ── 5. Move the spotlight to this step (animated) and wait for action ──
+        driverObj.highlight({
+            ...(element ? { element } : {}),
+            popover: buildPopover(step, stepNumber, totalVisible, isLast),
+        });
+        shownCount++;
+        const action = await waitForAction();
+        if (action === 'skip') {
+            emit({ type: 'tour.skipped', tourId: tour.id, stepIndex: i });
+            teardown();
+            onSkip?.(i);
+            return;
+        }
+        if (isLast) {
+            emit({ type: 'tour.completed', tourId: tour.id });
+            teardown();
+            onComplete?.();
+            return;
+        }
+        // action === 'next' — loop continues; the next highlight() animates the move
+    }
+    // Loop finished without the user skipping/completing mid-way.
+    teardown();
+    if (shownCount === 0) {
+        // Every anchored step's target was missing — nothing was shown. Do NOT
+        // complete or mark seen; surface it so it can show once the UI is fixed.
+        emit({ type: 'tour.unavailable', tourId: tour.id, missingAnchors });
+        onUnavailable?.(missingAnchors);
+        return;
+    }
+    emit({ type: 'tour.completed', tourId: tour.id });
+    onComplete?.();
+}
+//# sourceMappingURL=player.js.map

package/dist/player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"player.js","sourceRoot":"","sources":["../src/player.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGnC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAsB,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAiBtC,SAAS,MAAM,CAAC,EAAU;IACxB,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,IAAU,EACV,UAAyB,EACzB,QAAmC,EACnC,cAA+C;IAE/C,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM;QAAE,OAAO;IAElC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAClC,IAAI,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,IAAI,QAAQ;gBAAE,MAAM,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3C,4DAA4D;YAC5D,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;YACrC,MAAM,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACtD,IAAI,EAAE;gBAAG,EAAkB,CAAC,KAAK,EAAE,CAAC;YACpC,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACpC,IAAI,MAAM,CAAC,QAAQ,IAAI,cAAc,EAAE,CAAC;gBACtC,MAAM,QAAQ,GAAG,eAAe,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAChE,MAAM,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;YACnD,CAAC;iBAAM,CAAC;gBACN,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,gFAAgF;AAChF,oFAAoF;AACpF,qFAAqF;AACrF,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2DvB,CAAC;AAEF,SAAS,gBAAgB,CAAC,KAAqB;IAC7C,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC;IACnD,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,EAAE,CAAC,EAAE,GAAG,gBAAgB,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IAED,+EAA+E;IAC/E,oEAAoE;IACpE,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,KAAK,CAAC,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,aAAa,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IAC/D,IAAI,KAAK,CAAC,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IACjE,IAAI,KAAK,CAAC,UAAU;QAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,YAAY;QAAE,IAAI,CAAC,IAAI,CAAC,kBAAkB,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;IAC1E,IAAI,KAAK,CAAC,gBAAgB;QAAE,IAAI,CAAC,IAAI,CAAC,uBAAuB,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACvF,IAAI,KAAK,CAAC,YAAY;QAAE,IAAI,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;IACzE,IAAI,KAAK,CAAC,UAAU;QAAE,IAAI,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;IACnE,IAAI,KAAK,CAAC,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAE7D,EAAE,CAAC,WAAW,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,eAAe,EAAE,CAAC;AAC1F,CAAC;AAUD,SAAS,YAAY,CACnB,IAAU,EACV,UAAkB,EAClB,YAAoB,EACpB,MAAe;IAGf,MAAM,IAAI,GACR,IAAI,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,IAAI,CAAC,SAAkB,CAAC;IAEnE,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,IAAI;QACtB,WAAW,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QAC9B,YAAY,EAAE,IAAI;QAClB,YAAY,EAAE,GAAG,UAAU,OAAO,YAAY,EAAE;QAChD,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1B,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAmB;IAChD,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IAEzH,8EAA8E;IAC9E,0EAA0E;IAC1E,MAAM,WAAW,GAAmB,EAAE,GAAG,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;IACxE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAE9B,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAEhD,8DAA8D;IAC9D,0EAA0E;IAC1E,0DAA0D;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACvC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,UAAU,GAAG,CAAC,CAAC,CAAiB,2BAA2B;IAC/D,MAAM,cAAc,GAAa,EAAE,CAAC,CAAC,6CAA6C;IAElF,8EAA8E;IAC9E,gFAAgF;IAChF,6EAA6E;IAC7E,uDAAuD;IACvD,IAAI,cAAc,GAAqC,IAAI,CAAC;IAC5D,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,MAAM,MAAM,GAAG,CAAC,MAAkB,EAAE,EAAE;QACpC,MAAM,OAAO,GAAG,cAAc,CAAC;QAC/B,cAAc,GAAG,IAAI,CAAC;QACtB,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,IAAI,IAAI;YAAE,OAAO;QACjB,IAAI,GAAG,IAAI,CAAC;QACZ,SAAS,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,MAAM,CAAC;QACvB,UAAU,EAAE,IAAI;QAChB,YAAY,EAAE,WAAW,CAAC,YAAY,IAAI,SAAS;QACnD,cAAc,EAAE,WAAW,CAAC,cAAc,IAAI,IAAI;QAClD,YAAY,EAAE,WAAW,CAAC,YAAY,IAAI,CAAC;QAC3C,WAAW,EAAE,WAAW,CAAC,WAAW,IAAI,CAAC;QACzC,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,IAAI;QACpC,YAAY,EAAE,IAAI;QAClB,GAAG,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAE/E,yEAAyE;QACzE,2EAA2E;QAC3E,0EAA0E;QAC1E,sEAAsE;QACtE,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;QACjC,YAAY,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;QAClC,gBAAgB,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;KACxD,CAAC,CAAC;IAEH,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,IAAI,OAAO,CAAa,OAAO,CAAC,EAAE,GAAG,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9F,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,0EAA0E;QAC1E,8DAA8D;QAC9D,yDAAyD;QACzD,MAAM,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;QAE7D,0EAA0E;QAC1E,yEAAyE;QACzE,2EAA2E;QAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACpE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,IAAI,KAAK,CAAC;YACzE,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACrC,IAAI,OAAO,EAAE,CAAC;gBACZ,wEAAwE;gBACxE,MAAM,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzC,CAAC;iBAAM,IAAI,cAAc,EAAE,CAAC;gBAC1B,MAAM,cAAc,CAAC,eAAe,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC9E,CAAC;iBAAM,CAAC;gBACN,MAAM,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QAED,yEAAyE;QACzE,IAAI,OAA4B,CAAC;QACjC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAChE,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,qEAAqE;gBACrE,oDAAoD;gBACpD,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACnC,SAAS;YACX,CAAC;YACD,OAAO,GAAG,EAAE,CAAC;YACb,sEAAsE;YACtE,mEAAmE;QACrE,CAAC;QAED,UAAU,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QAE3C,0EAA0E;QAC1E,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;QAClB,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ;YAC/B,CAAC,CAAC,EAAE,IAAI,EAAE,aAAsB,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE;YAC1F,CAAC,CAAC,EAAE,IAAI,EAAE,aAAsB,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;QACpE,IAAI,CAAC,WAAW,CAAC,CAAC;QAElB,0EAA0E;QAC1E,SAAS,CAAC,SAAS,CAAC;YAClB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,OAAO,EAAE,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,CAAC;SAC9D,CAAC,CAAC;QACH,UAAU,EAAE,CAAC;QAEb,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;QAErC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9D,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;YACZ,OAAO;QACT,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;YAClD,QAAQ,EAAE,CAAC;YACX,UAAU,EAAE,EAAE,CAAC;YACf,OAAO;QACT,CAAC;QACD,6EAA6E;IAC/E,CAAC;IAED,8DAA8D;IAC9D,QAAQ,EAAE,CAAC;IACX,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACrB,uEAAuE;QACvE,yEAAyE;QACzE,IAAI,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,cAAc,EAAE,CAAC,CAAC;QACpE,aAAa,EAAE,CAAC,cAAc,CAAC,CAAC;QAChC,OAAO;IACT,CAAC;IAED,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAClD,UAAU,EAAE,EAAE,CAAC;AACjB,CAAC"}

package/dist/resolver.d.ts

@@ -0,0 +1,20 @@
+export interface AnchorMeta {
+    testid?: string;
+    role?: string;
+    name?: string;
+}
+export type AnchorMetaMap = Record<string, AnchorMeta>;
+/**
+ * Resolve a step's target from its `anchorId`.
+ *
+ * `anchorId` carries one of two things (no schema change — the field is reused):
+ *   - an encoded multi-signal locator (`loc:<json>`) → resolved via signals +
+ *     signature, with self-heal and rot detection (the modern path), or
+ *   - a plain string → treated as a legacy `data-tour` selector.
+ *
+ * Emits telemetry: `anchor.healed` (recovered via signature), `anchor.mismatch`
+ * (resolved the wrong element — skipped), `anchor.broken` (nothing found).
+ */
+export declare function resolveAnchor(anchorId: string, metaMap?: AnchorMetaMap, tourId?: string, stepIndex?: number): Element | null;
+export declare function waitForAnchor(anchorId: string, timeoutMs?: number): Promise<Element | null>;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,aAAkB,EAC3B,MAAM,SAAK,EACX,SAAS,SAAI,GACZ,OAAO,GAAG,IAAI,CA2ChB;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAsBzF"}

package/dist/resolver.js

@@ -0,0 +1,81 @@
+import { emit } from './telemetry.js';
+import { decodeLocator, resolveLocator } from './locator.js';
+/**
+ * Resolve a step's target from its `anchorId`.
+ *
+ * `anchorId` carries one of two things (no schema change — the field is reused):
+ *   - an encoded multi-signal locator (`loc:<json>`) → resolved via signals +
+ *     signature, with self-heal and rot detection (the modern path), or
+ *   - a plain string → treated as a legacy `data-tour` selector.
+ *
+ * Emits telemetry: `anchor.healed` (recovered via signature), `anchor.mismatch`
+ * (resolved the wrong element — skipped), `anchor.broken` (nothing found).
+ */
+export function resolveAnchor(anchorId, metaMap = {}, tourId = '', stepIndex = 0) {
+    // ── Modern path: encoded locator + signature ──────────────────────────────
+    const locator = decodeLocator(anchorId);
+    if (locator) {
+        const { el, status } = resolveLocator(locator);
+        if (status === 'healed')
+            emit({ type: 'anchor.healed', anchorId, tourId, stepIndex });
+        if (status === 'mismatch')
+            emit({ type: 'anchor.mismatch', anchorId, tourId, stepIndex });
+        if (!el) {
+            if (status !== 'mismatch')
+                emit({ type: 'anchor.broken', anchorId, tourId, stepIndex });
+            return null;
+        }
+        return el;
+    }
+    // ── Legacy path: plain data-tour selector (+ registry metadata fallbacks) ──
+    const escaped = CSS.escape(anchorId);
+    const primary = document.querySelector(`[data-tour="${escaped}"]`);
+    if (primary)
+        return primary;
+    const meta = metaMap[anchorId];
+    if (meta?.testid) {
+        const el = document.querySelector(`[data-testid="${CSS.escape(meta.testid)}"]`);
+        if (el) {
+            emit({ type: 'anchor.fallback', anchorId, strategy: 'testid' });
+            return el;
+        }
+    }
+    if (meta?.role && meta?.name) {
+        const candidates = document.querySelectorAll(`[role="${meta.role}"]`);
+        for (const el of Array.from(candidates)) {
+            const label = el.getAttribute('aria-label') ??
+                el.getAttribute('aria-labelledby') ??
+                el.textContent?.trim();
+            if (label === meta.name) {
+                emit({ type: 'anchor.fallback', anchorId, strategy: 'role' });
+                return el;
+            }
+        }
+    }
+    emit({ type: 'anchor.broken', anchorId, tourId, stepIndex });
+    return null;
+}
+export function waitForAnchor(anchorId, timeoutMs = 5000) {
+    return new Promise(resolve => {
+        const escaped = CSS.escape(anchorId);
+        const existing = document.querySelector(`[data-tour="${escaped}"]`);
+        if (existing) {
+            resolve(existing);
+            return;
+        }
+        const observer = new MutationObserver(() => {
+            const el = document.querySelector(`[data-tour="${escaped}"]`);
+            if (el) {
+                observer.disconnect();
+                clearTimeout(timer);
+                resolve(el);
+            }
+        });
+        observer.observe(document.body, { childList: true, subtree: true, attributes: true });
+        const timer = setTimeout(() => {
+            observer.disconnect();
+            resolve(null);
+        }, timeoutMs);
+    });
+}
+//# sourceMappingURL=resolver.js.map

package/dist/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"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"}