@guided-tour-s4marth/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DataGenie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/conditions.d.ts

@@ -0,0 +1,12 @@
+import type { Condition, Tour } from './schema.js';
+export interface RuntimeContext {
+    route: string;
+    role?: string;
+    appVersion: string;
+    flags: Record<string, boolean>;
+    seenTours: Set<string>;
+    customPredicates?: Record<string, () => boolean>;
+}
+export declare function evaluateCondition(condition: Condition, ctx: RuntimeContext): boolean;
+export declare function isTourEligible(tour: Tour, ctx: RuntimeContext): boolean;
+//# sourceMappingURL=conditions.d.ts.map

package/dist/conditions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC;CAClD;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAyBpF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAGvE"}

package/dist/conditions.js

@@ -0,0 +1,34 @@
+import { satisfies as semverSatisfies, valid as semverValid } from 'semver';
+export function evaluateCondition(condition, ctx) {
+    switch (condition.kind) {
+        case 'route': {
+            try {
+                return new RegExp(condition.match).test(ctx.route);
+            }
+            catch {
+                return ctx.route.includes(condition.match);
+            }
+        }
+        case 'role':
+            return ctx.role != null && condition.in.includes(ctx.role);
+        case 'version': {
+            if (!semverValid(ctx.appVersion)) {
+                console.warn(`[tour] invalid semver for appVersion: "${ctx.appVersion}"`);
+                return false;
+            }
+            return semverSatisfies(ctx.appVersion, condition.range);
+        }
+        case 'flag':
+            return (ctx.flags[condition.key] ?? false) === condition.on;
+        case 'seen':
+            return ctx.seenTours.has(condition.tourId) === condition.value;
+        case 'custom':
+            return ctx.customPredicates?.[condition.predicateId]?.() ?? false;
+    }
+}
+export function isTourEligible(tour, ctx) {
+    if (tour.status !== 'active')
+        return false;
+    return tour.conditions.every(c => evaluateCondition(c, ctx));
+}
+//# sourceMappingURL=conditions.js.map

package/dist/conditions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditions.js","sourceRoot":"","sources":["../src/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,IAAI,eAAe,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,QAAQ,CAAC;AAY5E,MAAM,UAAU,iBAAiB,CAAC,SAAoB,EAAE,GAAmB;IACzE,QAAQ,SAAS,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,IAAI,CAAC;gBACH,OAAO,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACrD,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;QACD,KAAK,MAAM;YACT,OAAO,GAAG,CAAC,IAAI,IAAI,IAAI,IAAI,SAAS,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC7D,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACjC,OAAO,CAAC,IAAI,CAAC,0CAA0C,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC;gBAC1E,OAAO,KAAK,CAAC;YACf,CAAC;YACD,OAAO,eAAe,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;QAC1D,CAAC;QACD,KAAK,MAAM;YACT,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC;QAC9D,KAAK,MAAM;YACT,OAAO,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC;QACjE,KAAK,QAAQ;YACX,OAAO,GAAG,CAAC,gBAAgB,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,EAAE,IAAI,KAAK,CAAC;IACtE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAU,EAAE,GAAmB;IAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { parseTour, parseTours, Tour, Step, Condition, ThemeOverrides, InteractionAction } from './schema.js';
+export type { Tour as TourType, Step as StepType, Condition as ConditionType, ThemeOverrides as ThemeOverridesType, InteractionAction as InteractionActionType } from './schema.js';
+export { evaluateCondition, isTourEligible } from './conditions.js';
+export type { RuntimeContext } from './conditions.js';
+export { resolveAnchor, waitForAnchor } from './resolver.js';
+export type { AnchorMeta, AnchorMetaMap } from './resolver.js';
+export { encodeLocator, decodeLocator, resolveLocator, resolveXPath, waitForLocator, signatureMatches, buildLocator, getXPath, } from './locator.js';
+export type { TourLocator, TourSignature, LocatorStatus } from './locator.js';
+export { playTour } from './player.js';
+export type { PlayerOptions } from './player.js';
+export { localSeenStore, createBackendSeenStore } from './persistence.js';
+export type { SeenStore } from './persistence.js';
+export { setTelemetryHandler, emit, PREVIEW_TOUR_ID } from './telemetry.js';
+export type { TourEvent, TelemetryHandler } from './telemetry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9G,YAAY,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,QAAQ,EAAE,SAAS,IAAI,aAAa,EAAE,cAAc,IAAI,kBAAkB,EAAE,iBAAiB,IAAI,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpL,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,QAAQ,GACT,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5E,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { parseTour, parseTours, Tour, Step, Condition, ThemeOverrides, InteractionAction } from './schema.js';
+export { evaluateCondition, isTourEligible } from './conditions.js';
+export { resolveAnchor, waitForAnchor } from './resolver.js';
+export { encodeLocator, decodeLocator, resolveLocator, resolveXPath, waitForLocator, signatureMatches, buildLocator, getXPath, } from './locator.js';
+export { playTour } from './player.js';
+export { localSeenStore, createBackendSeenStore } from './persistence.js';
+export { setTelemetryHandler, emit, PREVIEW_TOUR_ID } from './telemetry.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9G,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,QAAQ,GACT,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1E,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/locator.d.ts

@@ -0,0 +1,37 @@
+export interface TourSignature {
+    tag: string;
+    role?: string;
+    name?: string;
+    text?: string;
+}
+export interface TourLocator {
+    testid?: string;
+    domId?: string;
+    role?: string;
+    name?: string;
+    text?: string;
+    xpath?: string;
+    signature: TourSignature;
+    route?: string;
+}
+export declare function encodeLocator(loc: TourLocator): string;
+export declare function decodeLocator(anchorId: string | undefined | null): TourLocator | null;
+export declare function resolveXPath(xpath: string): Element | null;
+export declare function getXPath(el: Element): string;
+export declare function buildLocator(el: Element): TourLocator;
+/** True if the element plausibly *is* the signature's target. Tag must match;
+ *  any provided name/text must be contained. Lenient on role (often implicit). */
+export declare function signatureMatches(el: Element, sig: TourSignature): boolean;
+export type LocatorStatus = 'ok' | 'healed' | 'mismatch' | 'broken';
+/** Resolve a locator against the live DOM.
+ *  - ok:       a signal resolved to a unique element matching the signature
+ *  - healed:   signals failed, but a unique element matches the signature
+ *  - mismatch: a signal resolved a unique element, but its signature differs (rot)
+ *  - broken:   nothing usable found */
+export declare function resolveLocator(loc: TourLocator): {
+    el: Element | null;
+    status: LocatorStatus;
+};
+/** Wait for a locator to resolve (post-navigation / async render). */
+export declare function waitForLocator(loc: TourLocator, timeoutMs?: number): Promise<Element | null>;
+//# sourceMappingURL=locator.d.ts.map

package/dist/locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../src/locator.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;IAIzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAEtD;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAQrF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAO1D;AAWD,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAiB5C;AAQD,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,WAAW,CAiCrD;AAMD;kFACkF;AAClF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CASzE;AAMD,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEpE;;;;uCAIuC;AACvC,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG;IAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAiC9F;AAED,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,SAAS,SAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAqB1F"}

package/dist/locator.js

@@ -0,0 +1,188 @@
+// ─── Locator + signature ────────────────────────────────────────────────────
+// A tour step targets an element by a multi-signal locator (no build-time
+// data-tour anchor needed). The locator is encoded into the Step.anchorId string
+// (reusing that field — no schema change): `loc:<json>`. A plain string anchorId
+// is treated as a legacy data-tour / CSS selector.
+//
+// The `signature` captures *what* the element is (tag, role, accessible name,
+// text). It serves two jobs:
+//   1. detect rot — if a signal resolves to an element whose signature no longer
+//      matches, that's "wrong element" rot (not silently highlighted).
+//   2. self-heal — if the signals miss, find a unique element matching the
+//      signature and re-bind to it (recovers from many UI refactors, no deploy).
+const PREFIX = 'loc:';
+export function encodeLocator(loc) {
+    return PREFIX + JSON.stringify(loc);
+}
+export function decodeLocator(anchorId) {
+    if (!anchorId || !anchorId.startsWith(PREFIX))
+        return null;
+    try {
+        const parsed = JSON.parse(anchorId.slice(PREFIX.length));
+        return parsed && parsed.signature ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveXPath(xpath) {
+    try {
+        const r = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+        return r.singleNodeValue ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Pseudo-XPath construction ─────────────────────────────────────────────────
+// Anchors on the nearest ancestor `id` for stability across re-renders;
+// otherwise uses tag:nth-of-type segments.
+function xpathLiteral(s) {
+    if (!s.includes('"'))
+        return `"${s}"`;
+    if (!s.includes("'"))
+        return `'${s}'`;
+    return 'concat("' + s.split('"').join('",\'"\',"') + '")';
+}
+export function getXPath(el) {
+    const segs = [];
+    let node = el;
+    while (node && node.nodeType === 1) {
+        if (node.id) {
+            segs.unshift(`*[@id=${xpathLiteral(node.id)}]`);
+            return '//' + segs.join('/');
+        }
+        const tag = node.tagName.toLowerCase();
+        let i = 1;
+        for (let sib = node.previousElementSibling; sib; sib = sib.previousElementSibling) {
+            if (sib.tagName === node.tagName)
+                i++;
+        }
+        segs.unshift(`${tag}[${i}]`);
+        node = node.parentElement;
+    }
+    return '/' + segs.join('/');
+}
+// ── Build a multi-signal locator + signature for an element ────────────────────
+// Signals (testid → id → xpath) are each verified UNIQUE before being recorded,
+// so resolveLocator can trust them. The signature (tag/role/name/text) captures
+// what the element *is* — used for rot detection and self-heal. Single source of
+// locator construction, shared by the recorder (capture) and the health auditor
+// (re-point suggestion).
+export function buildLocator(el) {
+    const tag = el.tagName.toLowerCase();
+    const role = el.getAttribute('role') ?? undefined;
+    const ariaLabel = el.getAttribute('aria-label')?.trim() || undefined;
+    const text = (el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 80) || undefined;
+    const signature = { tag };
+    if (role)
+        signature.role = role;
+    if (ariaLabel)
+        signature.name = ariaLabel;
+    if (text)
+        signature.text = text;
+    const loc = { signature };
+    // testid — only if it's on the element itself AND unique in the document.
+    const testid = el.getAttribute('data-testid') ?? undefined;
+    if (testid && document.querySelectorAll(`[data-testid="${CSS.escape(testid)}"]`).length === 1) {
+        loc.testid = testid;
+    }
+    // dom id — only if it actually resolves back to this element.
+    if (el.id && document.getElementById(el.id) === el)
+        loc.domId = el.id;
+    // xpath — always recorded as the precise last-resort signal.
+    loc.xpath = getXPath(el);
+    if (role)
+        loc.role = role;
+    if (ariaLabel)
+        loc.name = ariaLabel;
+    if (text)
+        loc.text = text;
+    // Route the element was captured on — metadata for the offline auditor (which
+    // screen to load). Ignored by runtime resolution.
+    loc.route = location.pathname + location.search;
+    return loc;
+}
+function accessibleName(el) {
+    return (el.getAttribute('aria-label') ?? el.textContent ?? '').trim();
+}
+/** True if the element plausibly *is* the signature's target. Tag must match;
+ *  any provided name/text must be contained. Lenient on role (often implicit). */
+export function signatureMatches(el, sig) {
+    if (sig.tag && el.tagName.toLowerCase() !== sig.tag.toLowerCase())
+        return false;
+    const text = (el.textContent ?? '').trim().toLowerCase();
+    if (sig.text && !text.includes(sig.text.toLowerCase()))
+        return false;
+    if (sig.name) {
+        const name = accessibleName(el).toLowerCase();
+        if (!name.includes(sig.name.toLowerCase()))
+            return false;
+    }
+    return true;
+}
+function unique(nodes) {
+    return nodes.length === 1 ? nodes[0] : null;
+}
+/** Resolve a locator against the live DOM.
+ *  - ok:       a signal resolved to a unique element matching the signature
+ *  - healed:   signals failed, but a unique element matches the signature
+ *  - mismatch: a signal resolved a unique element, but its signature differs (rot)
+ *  - broken:   nothing usable found */
+export function resolveLocator(loc) {
+    let sawCandidate = false;
+    const tryEl = (el) => {
+        if (!el)
+            return null;
+        sawCandidate = true;
+        return signatureMatches(el, loc.signature) ? { el, status: 'ok' } : null;
+    };
+    // 1–4: encoded signals, each must resolve to a UNIQUE element + match signature.
+    if (loc.testid) {
+        const r = tryEl(unique(document.querySelectorAll(`[data-testid="${CSS.escape(loc.testid)}"]`)));
+        if (r)
+            return r;
+    }
+    if (loc.domId) {
+        const r = tryEl(document.getElementById(loc.domId));
+        if (r)
+            return r;
+    }
+    if (loc.xpath) {
+        const r = tryEl(resolveXPath(loc.xpath));
+        if (r)
+            return r;
+    }
+    // 5: self-heal — a single element anywhere matching the signature.
+    if (loc.signature.tag) {
+        const healed = Array.from(document.getElementsByTagName(loc.signature.tag)).filter(e => signatureMatches(e, loc.signature));
+        if (healed.length === 1)
+            return { el: healed[0], status: 'healed' };
+    }
+    // A signal hit a unique element but the signature didn't match → wrong element.
+    return { el: null, status: sawCandidate ? 'mismatch' : 'broken' };
+}
+/** Wait for a locator to resolve (post-navigation / async render). */
+export function waitForLocator(loc, timeoutMs = 5000) {
+    return new Promise(resolve => {
+        const now = resolveLocator(loc);
+        if (now.el) {
+            resolve(now.el);
+            return;
+        }
+        const observer = new MutationObserver(() => {
+            const r = resolveLocator(loc);
+            if (r.el) {
+                observer.disconnect();
+                clearTimeout(timer);
+                resolve(r.el);
+            }
+        });
+        observer.observe(document.body, { childList: true, subtree: true, attributes: true });
+        const timer = setTimeout(() => {
+            observer.disconnect();
+            resolve(null);
+        }, timeoutMs);
+    });
+}
+//# sourceMappingURL=locator.js.map

package/dist/locator.js.map

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

package/dist/persistence.d.ts

@@ -0,0 +1,44 @@
+export interface SeenStore {
+    hasSeen(userId: string, tourId: string): Promise<boolean>;
+    markSeen(userId: string, tourId: string): Promise<void>;
+    getAll(userId: string): Promise<Set<string>>;
+}
+export declare const localSeenStore: SeenStore;
+export interface BackendSeenStoreOpts<TProfile = unknown> {
+    /**
+     * URL to fetch the user profile (or any object containing the seen-tours list).
+     * e.g. (userId) => `/api/users/${userId}`
+     */
+    getUrl: (userId: string) => string;
+    /**
+     * Extract the seen-tour IDs from whatever the getUrl endpoint returns.
+     * Defaults to treating the response as a bare string[].
+     *
+     * Example for a user-profile response:
+     *   extractSeenTours: (profile) => profile.preferences?.seenTours ?? []
+     */
+    extractSeenTours?: (data: TProfile) => string[];
+    /**
+     * URL to PATCH / POST when marking a tour seen.
+     * e.g. `/api/users/me/preferences`
+     */
+    updateUrl: (userId: string) => string;
+    /**
+     * HTTP method for the update request. Defaults to 'PATCH'.
+     */
+    updateMethod?: 'PATCH' | 'POST' | 'PUT';
+    /**
+     * Build the request body for the update call.
+     * Receives the full updated seen-tours set so you can embed it however
+     * your endpoint expects.
+     *
+     * Defaults to: (seenTours) => ({ seenTours: Array.from(seenTours) })
+     *
+     * Example for a nested preferences object:
+     *   buildBody: (seenTours) => ({ preferences: { seenTours: Array.from(seenTours) } })
+     */
+    buildBody?: (seenTours: Set<string>) => unknown;
+    headers?: Record<string, string>;
+}
+export declare function createBackendSeenStore<TProfile = unknown>(opts: BackendSeenStoreOpts<TProfile>): SeenStore;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CAC9C;AAMD,eAAO,MAAM,cAAc,EAAE,SAgB5B,CAAC;AAEF,MAAM,WAAW,oBAAoB,CAAC,QAAQ,GAAG,OAAO;IACtD;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAEnC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,EAAE,CAAC;IAEhD;;;OAGG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAEtC;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IAExC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC;IAEhD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,GAAG,OAAO,EACvD,IAAI,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GACnC,SAAS,CA6CX"}

package/dist/persistence.js

@@ -0,0 +1,57 @@
+function storageKey(userId, tourId) {
+    return `tour.seen.${userId}.${tourId}`;
+}
+export const localSeenStore = {
+    async hasSeen(userId, tourId) {
+        return localStorage.getItem(storageKey(userId, tourId)) === '1';
+    },
+    async markSeen(userId, tourId) {
+        localStorage.setItem(storageKey(userId, tourId), '1');
+    },
+    async getAll(userId) {
+        const prefix = `tour.seen.${userId}.`;
+        const seen = new Set();
+        for (let i = 0; i < localStorage.length; i++) {
+            const k = localStorage.key(i);
+            if (k?.startsWith(prefix))
+                seen.add(k.slice(prefix.length));
+        }
+        return seen;
+    },
+};
+export function createBackendSeenStore(opts) {
+    const { getUrl, extractSeenTours = (data) => data, updateUrl, updateMethod = 'PATCH', buildBody = (seen) => ({ seenTours: Array.from(seen) }), headers = {}, } = opts;
+    const cache = new Map();
+    const jsonHeaders = { 'Content-Type': 'application/json', ...headers };
+    return {
+        async hasSeen(userId, tourId) {
+            const all = await this.getAll(userId);
+            return all.has(tourId);
+        },
+        async markSeen(userId, tourId) {
+            const all = await this.getAll(userId);
+            if (all.has(tourId))
+                return; // already marked, skip the request
+            all.add(tourId);
+            cache.set(userId, all);
+            await fetch(updateUrl(userId), {
+                method: updateMethod,
+                headers: jsonHeaders,
+                body: JSON.stringify(buildBody(all)),
+            });
+        },
+        async getAll(userId) {
+            if (!cache.has(userId)) {
+                const res = await fetch(getUrl(userId), { headers });
+                if (!res.ok) {
+                    cache.set(userId, new Set());
+                    return cache.get(userId);
+                }
+                const data = (await res.json());
+                cache.set(userId, new Set(extractSeenTours(data)));
+            }
+            return cache.get(userId);
+        },
+    };
+}
+//# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

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

package/dist/player.d.ts

@@ -0,0 +1,18 @@
+import type { Tour, ThemeOverrides } from './schema.js';
+import { type AnchorMetaMap } from './resolver.js';
+export interface PlayerOptions {
+    tour: Tour;
+    anchorMeta?: AnchorMetaMap;
+    theme?: ThemeOverrides;
+    onComplete?: () => void;
+    onSkip?: (stepIndex: number) => void;
+    /** Fired with the 0-based index of each step as it's shown. */
+    onStepChange?: (stepIndex: number) => void;
+    /** No step could be shown (all anchored targets missing). The caller should
+     *  NOT mark the tour seen so it can show once the UI is fixed. */
+    onUnavailable?: (missingAnchors: string[]) => void;
+    navigate?: (route: string) => void | Promise<void>;
+    waitForElement?: (selector: string, timeoutMs?: number) => Promise<Element | null>;
+}
+export declare function playTour(opts: PlayerOptions): Promise<void>;
+//# sourceMappingURL=player.d.ts.map

package/dist/player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"player.d.ts","sourceRoot":"","sources":["../src/player.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAQ,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAIjF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C;sEACkE;IAClE,aAAa,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACnD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CACpF;AAyJD,wBAAsB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA+IjE"}