@docentjs/dom 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1274 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _docentjs_core = require("@docentjs/core");
+//#region src/content.ts
+const SAFE_SCHEMES = /* @__PURE__ */ new Set([
+	"http:",
+	"https:",
+	"mailto:",
+	"tel:"
+]);
+function isSafeUrl(url) {
+	const match = /^([a-z][a-z0-9+.-]*):/i.exec(url.trim());
+	if (!match) return true;
+	return SAFE_SCHEMES.has(`${match[1]?.toLowerCase()}:`);
+}
+const INLINE = /(\*\*(.+?)\*\*)|(\*(.+?)\*)|(`(.+?)`)|(\[(.+?)\]\(((?:[^()\s]|\([^()]*\))+)\))/g;
+function appendInline(doc, parent, text) {
+	let last = 0;
+	for (const m of text.matchAll(INLINE)) {
+		const index = m.index ?? 0;
+		if (index > last) parent.appendChild(doc.createTextNode(text.slice(last, index)));
+		if (m[2] !== void 0) {
+			const el = doc.createElement("strong");
+			appendInline(doc, el, m[2]);
+			parent.appendChild(el);
+		} else if (m[4] !== void 0) {
+			const el = doc.createElement("em");
+			appendInline(doc, el, m[4]);
+			parent.appendChild(el);
+		} else if (m[6] !== void 0) {
+			const el = doc.createElement("code");
+			el.textContent = m[6];
+			parent.appendChild(el);
+		} else if (m[8] !== void 0 && m[9] !== void 0) {
+			if (isSafeUrl(m[9])) {
+				const a = doc.createElement("a");
+				a.href = m[9];
+				a.target = "_blank";
+				a.rel = "noopener noreferrer";
+				appendInline(doc, a, m[8]);
+				parent.appendChild(a);
+			} else parent.appendChild(doc.createTextNode(m[8]));
+		}
+		last = index + m[0].length;
+	}
+	if (last < text.length) parent.appendChild(doc.createTextNode(text.slice(last)));
+}
+function appendLines(doc, parent, text, inline) {
+	text.split("\n").forEach((line, i) => {
+		if (i > 0) parent.appendChild(doc.createElement("br"));
+		if (inline) appendInline(doc, parent, line);
+		else parent.appendChild(doc.createTextNode(line));
+	});
+}
+function renderBody(doc, body, format = "text") {
+	const frag = doc.createDocumentFragment();
+	for (const para of body.split(/\n{2,}/)) {
+		if (!para.trim()) continue;
+		const p = doc.createElement("p");
+		appendLines(doc, p, para, format === "markdown");
+		frag.appendChild(p);
+	}
+	return frag;
+}
+function renderMedia(doc, media) {
+	if (!isSafeUrl(media.src)) return null;
+	if (media.type === "image") {
+		const img = doc.createElement("img");
+		img.src = media.src;
+		img.alt = media.alt ?? "";
+		img.setAttribute("loading", "lazy");
+		return img;
+	}
+	const video = doc.createElement("video");
+	video.src = media.src;
+	video.controls = true;
+	video.playsInline = true;
+	if (media.alt) video.setAttribute("aria-label", media.alt);
+	return video;
+}
+//#endregion
+//#region src/occlusion.ts
+function isPinned(el) {
+	const view = el.ownerDocument.defaultView;
+	if (!view) return false;
+	const position = view.getComputedStyle(el).position;
+	return position === "fixed" || position === "sticky";
+}
+/** Nearest pinned ancestor (inclusive), or null. */
+function pinnedAncestor(el) {
+	let cur = el;
+	while (cur && cur !== cur.ownerDocument.documentElement) {
+		if (isPinned(cur)) return cur;
+		cur = cur.parentElement;
+	}
+	return null;
+}
+/**
+* Find a pinned element covering the target's top or bottom edge.
+* `ignore` is our own host, which sits above everything.
+*/
+function findOccluder(target, ignore, viewport) {
+	const doc = target.ownerDocument;
+	const r = target.getBoundingClientRect();
+	const vx = viewport.x ?? 0;
+	const vy = viewport.y ?? 0;
+	const x = Math.min(Math.max(r.left + r.width / 2, vx + 1), vx + viewport.width - 1);
+	const probes = [{
+		y: r.top + 1,
+		edge: "top"
+	}, {
+		y: r.bottom - 1,
+		edge: "bottom"
+	}];
+	for (const { y, edge } of probes) {
+		if (y < vy || y > vy + viewport.height) continue;
+		const top = doc.elementsFromPoint(x, y).filter((el) => el !== ignore)[0];
+		if (!top || top === target || target.contains(top) || top.contains(target)) continue;
+		const pinned = pinnedAncestor(top);
+		if (!pinned || pinned.contains(target)) continue;
+		return {
+			el: pinned,
+			rect: pinned.getBoundingClientRect(),
+			edge
+		};
+	}
+	return null;
+}
+/**
+* Scroll so nothing pinned covers the target. Returns true if it scrolled.
+* Runs at most twice to handle a header and a footer together.
+*/
+function uncover(target, ignore, viewport, margin = 8) {
+	const win = target.ownerDocument.defaultView;
+	if (!win || typeof target.ownerDocument.elementsFromPoint !== "function") return false;
+	let scrolled = false;
+	for (let i = 0; i < 2; i++) {
+		const occluder = findOccluder(target, ignore, viewport);
+		if (!occluder) break;
+		const r = target.getBoundingClientRect();
+		const delta = occluder.edge === "top" ? -(occluder.rect.bottom - r.top + margin) : r.bottom - occluder.rect.top + margin;
+		win.scrollBy({
+			top: delta,
+			behavior: "auto"
+		});
+		scrolled = true;
+	}
+	return scrolled;
+}
+//#endregion
+//#region src/position.ts
+const OPPOSITE = {
+	top: "bottom",
+	bottom: "top",
+	left: "right",
+	right: "left"
+};
+function parsePlacement(placement) {
+	if (placement === "auto") return {
+		side: "auto",
+		align: "center"
+	};
+	const [side, align] = placement.split("-");
+	return {
+		side,
+		align: align ?? "center"
+	};
+}
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+function isVertical(side) {
+	return side === "top" || side === "bottom";
+}
+/** Free space between the anchor and the viewport edge on each side. */
+function availableSpace(anchor, viewport) {
+	const vx = viewport.x ?? 0;
+	const vy = viewport.y ?? 0;
+	return {
+		top: anchor.y - vy,
+		bottom: vy + viewport.height - (anchor.y + anchor.height),
+		left: anchor.x - vx,
+		right: vx + viewport.width - (anchor.x + anchor.width)
+	};
+}
+function candidates(side, space) {
+	if (side === "auto") return Object.keys(space).sort((a, b) => space[b] - space[a]);
+	const perpendicular = isVertical(side) ? ["right", "left"] : ["bottom", "top"];
+	return [
+		side,
+		OPPOSITE[side],
+		...perpendicular.sort((a, b) => space[b] - space[a])
+	];
+}
+function computePosition(input) {
+	const { anchor, floating, viewport } = input;
+	const gap = input.gap ?? 12;
+	const edge = input.edgePadding ?? 8;
+	const arrowSize = input.arrowSize ?? 8;
+	const { side: preferred, align } = parsePlacement(input.placement);
+	const vx = viewport.x ?? 0;
+	const vy = viewport.y ?? 0;
+	const space = availableSpace(anchor, viewport);
+	const order = candidates(preferred, space);
+	const needed = (s) => (isVertical(s) ? floating.height : floating.width) + gap + edge;
+	const side = order.find((s) => space[s] >= needed(s)) ?? order[0];
+	let x = 0;
+	let y = 0;
+	if (side === "top") y = anchor.y - gap - floating.height;
+	if (side === "bottom") y = anchor.y + anchor.height + gap;
+	if (side === "left") x = anchor.x - gap - floating.width;
+	if (side === "right") x = anchor.x + anchor.width + gap;
+	if (isVertical(side)) {
+		if (align === "start") x = anchor.x;
+		else if (align === "end") x = anchor.x + anchor.width - floating.width;
+		else x = anchor.x + anchor.width / 2 - floating.width / 2;
+		x = clamp(x, vx + edge, Math.max(vx + edge, vx + viewport.width - edge - floating.width));
+	} else {
+		if (align === "start") y = anchor.y;
+		else if (align === "end") y = anchor.y + anchor.height - floating.height;
+		else y = anchor.y + anchor.height / 2 - floating.height / 2;
+		y = clamp(y, vy + edge, Math.max(vy + edge, vy + viewport.height - edge - floating.height));
+	}
+	const margin = arrowSize * 2;
+	const arrow = isVertical(side) ? clamp(anchor.x + anchor.width / 2 - x, margin, floating.width - margin) : clamp(anchor.y + anchor.height / 2 - y, margin, floating.height - margin);
+	return {
+		x: Math.round(x),
+		y: Math.round(y),
+		side,
+		align,
+		arrow: Math.round(arrow)
+	};
+}
+/** Centre a popover in the viewport, for steps without a target. */
+function centerPosition(floating, viewport) {
+	return {
+		x: Math.round((viewport.x ?? 0) + Math.max(0, (viewport.width - floating.width) / 2)),
+		y: Math.round((viewport.y ?? 0) + Math.max(0, (viewport.height - floating.height) / 2))
+	};
+}
+/** Grow a rect on every side. */
+function inflate(rect, by) {
+	return {
+		x: rect.x - by,
+		y: rect.y - by,
+		width: rect.width + by * 2,
+		height: rect.height + by * 2
+	};
+}
+/**
+* The part of a rect that is on screen. Positioning against this keeps the
+* popover and arrow near the visible portion of oversized targets.
+*/
+function clipToViewport(rect, viewport) {
+	const vx = viewport.x ?? 0;
+	const vy = viewport.y ?? 0;
+	const x1 = Math.max(vx, rect.x);
+	const y1 = Math.max(vy, rect.y);
+	const x2 = Math.min(vx + viewport.width, rect.x + rect.width);
+	const y2 = Math.min(vy + viewport.height, rect.y + rect.height);
+	if (x2 <= x1 || y2 <= y1) return rect;
+	return {
+		x: x1,
+		y: y1,
+		width: x2 - x1,
+		height: y2 - y1
+	};
+}
+//#endregion
+//#region src/overlay.ts
+/**
+* Full-viewport backdrop with a rounded cutout. The cutout is a `clip-path`
+* so pointer events pass through the hole to the page for free; a separate
+* blocker element covers it when the step forbids interaction.
+*/
+function holePath(viewport, hole, radius) {
+	const r = Math.max(0, Math.min(radius, hole.width / 2, hole.height / 2));
+	const { x, y, width: w, height: h } = hole;
+	return `path(evenodd, "${`M0 0H${viewport.width}V${viewport.height}H0Z`}${`M${x + r} ${y}H${x + w - r}A${r} ${r} 0 0 1 ${x + w} ${y + r}V${y + h - r}A${r} ${r} 0 0 1 ${x + w - r} ${y + h}H${x + r}A${r} ${r} 0 0 1 ${x} ${y + h - r}V${y + r}A${r} ${r} 0 0 1 ${x + r} ${y}Z`}")`;
+}
+var Overlay = class {
+	el;
+	blocker;
+	lastHole = null;
+	constructor(doc) {
+		this.el = doc.createElement("div");
+		this.el.setAttribute("part", "overlay");
+		this.el.className = "overlay";
+		this.blocker = doc.createElement("div");
+		this.blocker.className = "blocker";
+		this.blocker.hidden = true;
+	}
+	/** Current hole, padded, in viewport coordinates. */
+	get hole() {
+		return this.lastHole;
+	}
+	update(viewport, { target, padding, radius }, block) {
+		if (target) this.lastHole = inflate(target, padding);
+		else {
+			const c = this.lastHole;
+			const cx = c ? c.x + c.width / 2 : viewport.width / 2;
+			const cy = c ? c.y + c.height / 2 : viewport.height / 2;
+			this.lastHole = null;
+			this.el.style.clipPath = holePath(viewport, {
+				x: cx,
+				y: cy,
+				width: 0,
+				height: 0
+			}, 0);
+			this.blocker.hidden = true;
+			return;
+		}
+		const hole = this.lastHole;
+		this.el.style.clipPath = holePath(viewport, hole, radius);
+		this.blocker.hidden = !block;
+		if (block) {
+			this.blocker.style.transform = `translate(${hole.x}px, ${hole.y}px)`;
+			this.blocker.style.width = `${hole.width}px`;
+			this.blocker.style.height = `${hole.height}px`;
+		}
+	}
+};
+//#endregion
+//#region src/popover.ts
+const DEFAULT_LABELS = {
+	next: "Next",
+	back: "Back",
+	skip: "Skip",
+	done: "Done",
+	close: "Close",
+	progress: "{current} of {total}"
+};
+function h(doc, tag, className, part) {
+	const el = doc.createElement(tag);
+	el.className = className;
+	el.setAttribute("part", part);
+	return el;
+}
+function slot(doc, name, fallback) {
+	const s = doc.createElement("slot");
+	s.name = name;
+	if (fallback) s.appendChild(fallback);
+	return s;
+}
+function formatProgress(template, current, total) {
+	return template.replace("{current}", String(current)).replace("{total}", String(total));
+}
+/**
+* Resolve slot overrides into light-DOM elements carrying `slot="<name>"`.
+* A `null` result projects an empty element, which suppresses the fallback.
+*/
+function resolveSlots(doc, slots, ctx) {
+	const out = [];
+	for (const [name, render] of Object.entries(slots)) {
+		const content = render?.(ctx, doc);
+		if (content === void 0) continue;
+		let el;
+		if (content === null) el = doc.createElement("span");
+		else if (typeof content === "string") {
+			el = doc.createElement("span");
+			el.textContent = content;
+		} else if (content instanceof Element) el = content;
+		else {
+			el = doc.createElement("div");
+			el.appendChild(content);
+		}
+		el.setAttribute("slot", name);
+		out.push(el);
+	}
+	return out;
+}
+function buildPopover(doc, ctx, labels = {}, slots = {}) {
+	const { step, tour, actions } = ctx;
+	const options = tour.options ?? {};
+	const text = {
+		...DEFAULT_LABELS,
+		...options.labels,
+		...labels
+	};
+	const buttons = step.buttons ?? {};
+	const id = `docent-${tour.id}-${step.id}`;
+	const el = h(doc, "div", "popover", "popover");
+	el.setAttribute("role", "dialog");
+	el.tabIndex = -1;
+	const arrow = h(doc, "div", "arrow", "arrow");
+	el.appendChild(arrow);
+	const header = h(doc, "div", "header", "header");
+	let titleNode;
+	if (step.title) {
+		const title = h(doc, "h2", "title", "title");
+		title.id = `${id}-title`;
+		title.textContent = step.title;
+		titleNode = title;
+		el.setAttribute("aria-labelledby", title.id);
+	}
+	header.appendChild(slot(doc, "title", titleNode));
+	let closeNode;
+	if (options.allowClose !== false && buttons.close !== false) {
+		const close = h(doc, "button", "close", "close");
+		close.type = "button";
+		close.setAttribute("aria-label", text.close);
+		close.textContent = "×";
+		close.addEventListener("click", () => actions.skip());
+		closeNode = close;
+	}
+	header.appendChild(slot(doc, "close", closeNode));
+	el.appendChild(slot(doc, "header", header));
+	let bodyNode;
+	if (step.body) {
+		const body = h(doc, "div", "body", "body");
+		body.id = `${id}-body`;
+		body.appendChild(renderBody(doc, step.body, step.format));
+		bodyNode = body;
+		el.setAttribute("aria-describedby", body.id);
+	}
+	el.appendChild(slot(doc, "body", bodyNode));
+	let mediaNode;
+	if (step.media) {
+		const media = renderMedia(doc, step.media);
+		if (media) {
+			const wrap = h(doc, "div", "media", "media");
+			wrap.appendChild(media);
+			mediaNode = wrap;
+		}
+	}
+	el.appendChild(slot(doc, "media", mediaNode));
+	const footer = h(doc, "div", "footer", "footer");
+	const progress = h(doc, "div", "progress", "progress");
+	if (options.showProgress !== false) progress.textContent = formatProgress(text.progress, ctx.progress.current, ctx.progress.total);
+	footer.appendChild(slot(doc, "progress", progress));
+	const group = h(doc, "div", "buttons", "buttons");
+	let initialFocus = el;
+	const button = (label, part, primary, onClick) => {
+		const b = h(doc, "button", primary ? "button primary" : "button", `button ${part}`);
+		b.type = "button";
+		b.textContent = label;
+		b.addEventListener("click", onClick);
+		group.appendChild(b);
+		return b;
+	};
+	if (buttons.back !== false && ctx.canGoBack) button(text.back, "button-back", false, actions.back);
+	if (buttons.skip !== false && !ctx.isLast) button(text.skip, "button-skip", false, actions.skip);
+	if (buttons.next !== false) initialFocus = button(ctx.isLast ? text.done : text.next, "button-next", true, actions.next);
+	footer.appendChild(slot(doc, "buttons", group));
+	el.appendChild(slot(doc, "footer", footer));
+	const slotted = resolveSlots(doc, slots, ctx);
+	if (slotted.some((s) => s.getAttribute("slot") === "buttons" || s.getAttribute("slot") === "footer")) initialFocus = el;
+	return {
+		el,
+		arrow,
+		initialFocus,
+		slotted
+	};
+}
+/** Wrapper used in headless mode: a positioned shell that projects the app's own popover. */
+function buildHeadlessShell(doc) {
+	const el = h(doc, "div", "popover headless", "popover");
+	const arrow = h(doc, "div", "arrow", "arrow");
+	arrow.hidden = true;
+	el.appendChild(arrow);
+	const s = doc.createElement("slot");
+	s.name = "popover";
+	el.appendChild(s);
+	return {
+		el,
+		arrow
+	};
+}
+//#endregion
+//#region src/styles.ts
+/** Styles injected into the shadow root. Theme through the custom properties. */
+const STYLES = `
+:host {
+  --docent-font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --docent-bg: #ffffff;
+  --docent-fg: #111827;
+  --docent-muted: #6b7280;
+  --docent-accent: #2563eb;
+  --docent-accent-fg: #ffffff;
+  --docent-radius: 12px;
+  --docent-shadow: 0 10px 30px rgba(0, 0, 0, 0.18), 0 2px 6px rgba(0, 0, 0, 0.08);
+  --docent-width: 320px;
+  --docent-overlay: #000;
+  --docent-overlay-opacity: 0.55;
+  --docent-duration: 250ms;
+  position: fixed;
+  inset: 0;
+  z-index: var(--docent-z, 2147483000);
+  pointer-events: none;
+  font: 14px/1.5 var(--docent-font);
+  color: var(--docent-fg);
+}
+@media (prefers-color-scheme: dark) {
+  :host {
+    --docent-bg: #1f2937;
+    --docent-fg: #f9fafb;
+    --docent-muted: #9ca3af;
+    --docent-accent: #60a5fa;
+    --docent-accent-fg: #0b1220;
+  }
+}
+* { box-sizing: border-box; }
+.overlay {
+  position: absolute;
+  inset: 0;
+  background: var(--docent-overlay);
+  opacity: var(--docent-overlay-opacity);
+  pointer-events: auto;
+  transition: clip-path var(--docent-duration) ease;
+}
+.blocker {
+  position: absolute;
+  left: 0;
+  top: 0;
+  pointer-events: auto;
+}
+.popover {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: var(--docent-width);
+  max-width: calc(100vw - 32px);
+  background: var(--docent-bg);
+  border-radius: var(--docent-radius);
+  box-shadow: var(--docent-shadow);
+  padding: 16px;
+  pointer-events: auto;
+  outline: none;
+  transition: transform var(--docent-duration) ease, opacity var(--docent-duration) ease;
+}
+.popover[data-entering] { opacity: 0; transition: none; }
+.popover.headless {
+  width: auto;
+  max-width: none;
+  padding: 0;
+  background: none;
+  box-shadow: none;
+  border-radius: 0;
+}
+.arrow {
+  position: absolute;
+  width: 12px;
+  height: 12px;
+  background: var(--docent-bg);
+  transform: rotate(45deg);
+}
+.popover[data-side="top"] .arrow { bottom: -6px; }
+.popover[data-side="bottom"] .arrow { top: -6px; }
+.popover[data-side="left"] .arrow { right: -6px; }
+.popover[data-side="right"] .arrow { left: -6px; }
+.popover[data-side="center"] .arrow, .popover[data-side="sheet"] .arrow { display: none; }
+.popover.sheet {
+  max-width: none;
+  border-radius: var(--docent-radius) var(--docent-radius) 0 0;
+  padding-bottom: max(16px, env(safe-area-inset-bottom));
+}
+.header { display: flex; align-items: flex-start; gap: 8px; }
+.title { flex: 1; margin: 0; font-size: 16px; font-weight: 600; }
+.close {
+  appearance: none;
+  border: 0;
+  background: transparent;
+  color: var(--docent-muted);
+  font-size: 18px;
+  line-height: 1;
+  cursor: pointer;
+  padding: 2px 4px;
+  margin: -4px -6px 0 0;
+  border-radius: 6px;
+}
+.close:hover, .close:focus-visible { color: var(--docent-fg); background: rgba(127, 127, 127, 0.15); }
+.body { margin-top: 6px; }
+.body p { margin: 0 0 8px; }
+.body p:last-child { margin-bottom: 0; }
+.body code {
+  font-family: ui-monospace, monospace;
+  font-size: 0.9em;
+  padding: 1px 4px;
+  border-radius: 4px;
+  background: rgba(127, 127, 127, 0.15);
+}
+.body a { color: var(--docent-accent); }
+.media { margin: 10px 0 0; }
+.media img, .media video { display: block; max-width: 100%; border-radius: 8px; }
+.footer { display: flex; align-items: center; gap: 8px; margin-top: 14px; }
+.progress { flex: 1; color: var(--docent-muted); font-size: 12px; }
+.buttons { display: flex; gap: 8px; }
+.button {
+  appearance: none;
+  border: 0;
+  border-radius: 8px;
+  padding: 7px 12px;
+  font: inherit;
+  font-weight: 500;
+  cursor: pointer;
+  background: rgba(127, 127, 127, 0.15);
+  color: var(--docent-fg);
+}
+.button.primary { background: var(--docent-accent); color: var(--docent-accent-fg); }
+.button:focus-visible, .close:focus-visible { outline: 2px solid var(--docent-accent); outline-offset: 2px; }
+@media (prefers-reduced-motion: reduce) {
+  .overlay, .popover { transition: none; }
+}
+`;
+//#endregion
+//#region src/target.ts
+/** Attribute that `{ name }` targets resolve through. */
+const NAME_ATTRIBUTE = "data-docent";
+function escapeAttr(value) {
+	const css = globalThis.CSS;
+	return css?.escape ? css.escape(value) : value.replace(/["\\]/g, "\\$&");
+}
+function toSpec(target) {
+	return typeof target === "string" ? { selectors: [target] } : target;
+}
+/** Selectors to try, in order, for a target. */
+function candidateSelectors(target) {
+	const spec = toSpec(target);
+	const out = [];
+	if (spec.name) out.push(`[${NAME_ATTRIBUTE}="${escapeAttr(spec.name)}"]`);
+	if (spec.selectors) out.push(...spec.selectors);
+	return out;
+}
+function safeQueryAll(root, selector) {
+	try {
+		return Array.from(root.querySelectorAll(selector));
+	} catch {
+		return [];
+	}
+}
+/** Query the root, then every open shadow root beneath it. */
+function queryAllDeep(root, selector) {
+	const direct = safeQueryAll(root, selector);
+	if (direct.length > 0) return direct;
+	const out = [];
+	for (const el of safeQueryAll(root, "*")) if (el.shadowRoot) out.push(...queryAllDeep(el.shadowRoot, selector));
+	return out;
+}
+function resolveTarget(target, root = document) {
+	const spec = toSpec(target);
+	let scope = root;
+	if (spec.within) {
+		const container = queryAllDeep(root, spec.within)[0];
+		if (!container) return null;
+		scope = container;
+	}
+	for (const selector of candidateSelectors(spec)) {
+		const matches = queryAllDeep(scope, selector);
+		if (matches.length > 0) return matches[spec.nth ?? 0] ?? null;
+	}
+	return null;
+}
+/**
+* Resolve now, or watch the DOM until the target appears, the timeout passes,
+* or the signal aborts. Resolves `null` when it never shows up.
+*/
+function waitForTarget(target, timeoutMs, signal, root = document) {
+	const now = resolveTarget(target, root);
+	if (now || signal?.aborted) return Promise.resolve(now);
+	return new Promise((resolve) => {
+		let scheduled = false;
+		const observed = root.nodeType === Node.DOCUMENT_NODE ? root.documentElement : root;
+		const done = (el) => {
+			observer.disconnect();
+			if (timer !== void 0) clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			resolve(el);
+		};
+		const check = () => {
+			scheduled = false;
+			const el = resolveTarget(target, root);
+			if (el) done(el);
+		};
+		const observer = new MutationObserver(() => {
+			if (scheduled) return;
+			scheduled = true;
+			queueMicrotask(check);
+		});
+		const onAbort = () => done(null);
+		const timer = Number.isFinite(timeoutMs) ? setTimeout(() => done(null), timeoutMs) : void 0;
+		signal?.addEventListener("abort", onAbort, { once: true });
+		observer.observe(observed, {
+			childList: true,
+			subtree: true,
+			attributes: true
+		});
+	});
+}
+//#endregion
+//#region src/theme.ts
+/** Token → CSS custom property (without the `--docent-` prefix). */
+const THEME_VARS = {
+	background: "bg",
+	foreground: "fg",
+	muted: "muted",
+	accent: "accent",
+	accentForeground: "accent-fg",
+	radius: "radius",
+	shadow: "shadow",
+	font: "font",
+	width: "width",
+	overlay: "overlay",
+	overlayOpacity: "overlay-opacity",
+	duration: "duration",
+	zIndex: "z"
+};
+/** Write theme tokens as inline custom properties on an element. Clears unset ones. */
+function applyTheme(el, theme) {
+	for (const key of Object.keys(THEME_VARS)) {
+		const value = theme?.[key];
+		const prop = `--docent-${THEME_VARS[key]}`;
+		if (value === void 0) el.style.removeProperty(prop);
+		else el.style.setProperty(prop, value);
+	}
+}
+function mergeThemes(...themes) {
+	return Object.assign({}, ...themes.filter(Boolean));
+}
+//#endregion
+//#region src/renderer.ts
+const FOCUSABLE = "a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex=\"-1\"])";
+var DomRenderer = class {
+	doc;
+	options;
+	host;
+	shadow;
+	overlay;
+	templateStyle;
+	popover;
+	arrow;
+	headlessContainer;
+	ctx;
+	target = null;
+	cleanups = [];
+	frame;
+	previousFocus = null;
+	/** Set once per step after the sheet has scrolled the target clear. */
+	sheetAdjusted = false;
+	constructor(options = {}) {
+		this.options = options;
+		this.doc = options.document ?? document;
+	}
+	hasTarget(target) {
+		return resolveTarget(target, this.doc) !== null;
+	}
+	async waitForTarget(target, timeoutMs, signal) {
+		return await waitForTarget(target, timeoutMs, signal, this.doc) !== null;
+	}
+	currentRoute() {
+		const { pathname, search } = this.doc.defaultView?.location ?? {
+			pathname: "/",
+			search: ""
+		};
+		return `${pathname}${search}`;
+	}
+	show(ctx) {
+		const firstStep = !this.host;
+		const host = this.mount();
+		this.teardownStep();
+		this.ctx = ctx;
+		this.target = ctx.step.target === void 0 ? null : resolveTarget(ctx.step.target, this.doc);
+		const template = this.template(ctx);
+		applyTheme(host, mergeThemes(this.options.theme, template?.theme, ctx.tour.options?.theme));
+		this.setTemplateCss(template?.css);
+		const initialFocus = this.options.headless ? this.buildHeadless(ctx, host, this.options.headless) : this.buildDefault(ctx, host, template);
+		this.popover?.setAttribute("data-entering", "");
+		if (this.target) {
+			const smooth = this.scrollIntoView(this.target, ctx.step);
+			if (this.options.avoidOcclusion !== false) {
+				const target = this.target;
+				this.afterScroll(smooth, () => {
+					if (this.target === target && uncover(target, host, this.viewport())) this.update();
+				});
+			}
+		}
+		this.update();
+		this.listen();
+		this.wireAdvance(ctx.step);
+		if (firstStep) this.previousFocus = this.doc.activeElement;
+		requestAnimationFrame(() => {
+			this.popover?.removeAttribute("data-entering");
+			initialFocus.focus({ preventScroll: true });
+		});
+	}
+	hide() {
+		this.teardownStep();
+		if (this.host) {
+			this.host.remove();
+			this.host = void 0;
+			this.shadow = void 0;
+			this.overlay = void 0;
+			this.templateStyle = void 0;
+		}
+		const prev = this.previousFocus;
+		this.previousFocus = null;
+		if (prev instanceof HTMLElement && prev.isConnected) prev.focus({ preventScroll: true });
+	}
+	/** Re-measure and re-position everything. Safe to call often. */
+	update() {
+		const ctx = this.ctx;
+		const overlay = this.overlay;
+		const popover = this.popover;
+		const win = this.doc.defaultView;
+		if (!ctx || !overlay || !popover || !win) return;
+		const viewport = this.viewport();
+		const overlaySize = {
+			width: overlay.el.offsetWidth,
+			height: overlay.el.offsetHeight
+		};
+		const spotlight = {
+			...this.options.spotlight,
+			...ctx.tour.options?.spotlight,
+			...ctx.step.spotlight
+		};
+		const padding = spotlight.padding ?? 6;
+		const radius = spotlight.radius ?? 6;
+		const external = this.headlessContainer;
+		const sheet = this.isSheet(viewport);
+		popover.classList.toggle("sheet", sheet);
+		popover.style.width = sheet ? `${viewport.width}px` : "";
+		const floating = {
+			width: popover.offsetWidth,
+			height: popover.offsetHeight
+		};
+		if (sheet) {
+			const rect = this.target?.isConnected ? toRect(this.target.getBoundingClientRect()) : null;
+			overlay.update(overlaySize, {
+				target: rect,
+				padding,
+				radius
+			}, this.blocksInteraction(ctx.step));
+			const vx = viewport.x ?? 0;
+			const top = (viewport.y ?? 0) + viewport.height - floating.height;
+			popover.style.transform = `translate(${vx}px, ${top}px)`;
+			popover.setAttribute("data-side", "sheet");
+			external?.setAttribute("data-side", "sheet");
+			this.keepClearOfSheet(rect, top);
+			return;
+		}
+		if (!this.target?.isConnected) {
+			overlay.update(overlaySize, {
+				target: null,
+				padding,
+				radius
+			}, false);
+			const { x, y } = centerPosition(floating, viewport);
+			popover.style.transform = `translate(${x}px, ${y}px)`;
+			popover.setAttribute("data-side", "center");
+			external?.setAttribute("data-side", "center");
+			return;
+		}
+		const rect = toRect(this.target.getBoundingClientRect());
+		overlay.update(overlaySize, {
+			target: rect,
+			padding,
+			radius
+		}, this.blocksInteraction(ctx.step));
+		const pos = computePosition({
+			anchor: clipToViewport(overlay.hole ?? rect, viewport),
+			floating,
+			viewport,
+			placement: ctx.step.placement ?? "auto",
+			gap: this.options.gap ?? 12
+		});
+		popover.style.transform = `translate(${pos.x}px, ${pos.y}px)`;
+		popover.setAttribute("data-side", pos.side);
+		if (this.arrow) {
+			const vertical = pos.side === "top" || pos.side === "bottom";
+			this.arrow.style.left = vertical ? `${pos.arrow - 6}px` : "";
+			this.arrow.style.top = vertical ? "" : `${pos.arrow - 6}px`;
+		}
+		if (external) {
+			external.setAttribute("data-side", pos.side);
+			external.style.setProperty("--docent-arrow", `${pos.arrow}px`);
+		}
+	}
+	/**
+	* The visible area in layout-viewport coordinates. Uses the visual viewport
+	* so pinch zoom, the on-screen keyboard and pages that overflow on mobile
+	* (where `innerWidth` grows past the screen) all position correctly.
+	*/
+	viewport() {
+		const vv = this.doc.defaultView?.visualViewport;
+		if (vv) return {
+			x: vv.offsetLeft,
+			y: vv.offsetTop,
+			width: vv.width,
+			height: vv.height
+		};
+		const el = this.doc.documentElement;
+		return {
+			x: 0,
+			y: 0,
+			width: el.clientWidth,
+			height: el.clientHeight
+		};
+	}
+	isSheet(viewport) {
+		const breakpoint = this.options.sheetBreakpoint ?? 480;
+		return breakpoint > 0 && viewport.width < breakpoint;
+	}
+	/** In sheet mode, scroll once so the target is not hidden behind the sheet. */
+	keepClearOfSheet(target, sheetTop) {
+		const win = this.doc.defaultView;
+		if (!target || !win || this.sheetAdjusted) return;
+		const overlap = target.y + target.height - sheetTop;
+		if (overlap <= 0) return;
+		this.sheetAdjusted = true;
+		win.scrollBy({
+			top: overlap + 16,
+			behavior: "auto"
+		});
+	}
+	/** Run after a smooth scroll settles (scrollend, or a short fallback), or right away. */
+	afterScroll(smooth, fn) {
+		const win = this.doc.defaultView;
+		if (!smooth || !win) {
+			fn();
+			return;
+		}
+		let done = false;
+		const finish = () => {
+			if (done) return;
+			done = true;
+			win.removeEventListener("scrollend", finish);
+			clearTimeout(timer);
+			fn();
+		};
+		const timer = setTimeout(finish, 600);
+		win.addEventListener("scrollend", finish, { once: true });
+		this.cleanups.push(() => {
+			done = true;
+			win.removeEventListener("scrollend", finish);
+			clearTimeout(timer);
+		});
+	}
+	template(ctx) {
+		const name = ctx.tour.options?.template ?? this.options.template;
+		return name === void 0 ? void 0 : this.options.templates?.[name];
+	}
+	buildDefault(ctx, host, template) {
+		const slots = {
+			...this.options.slots,
+			...template?.slots
+		};
+		const { el, arrow, initialFocus, slotted } = buildPopover(this.doc, ctx, this.options.labels ?? {}, slots);
+		this.popover = el;
+		this.arrow = arrow;
+		for (const node of slotted) {
+			host.appendChild(node);
+			this.cleanups.push(() => node.remove());
+		}
+		this.shadow?.appendChild(el);
+		return initialFocus;
+	}
+	buildHeadless(ctx, host, headless) {
+		const { el, arrow } = buildHeadlessShell(this.doc);
+		this.popover = el;
+		this.arrow = arrow;
+		this.shadow?.appendChild(el);
+		const container = this.doc.createElement("div");
+		container.setAttribute("slot", "popover");
+		container.setAttribute("data-docent-popover", "");
+		container.setAttribute("role", "dialog");
+		container.tabIndex = -1;
+		host.appendChild(container);
+		this.headlessContainer = container;
+		const cleanup = headless.render(ctx, container);
+		this.cleanups.push(() => {
+			cleanup?.();
+			container.remove();
+			this.headlessContainer = void 0;
+		});
+		return container;
+	}
+	setTemplateCss(css) {
+		if (!this.shadow) return;
+		if (!css) {
+			this.templateStyle?.remove();
+			this.templateStyle = void 0;
+			return;
+		}
+		if (!this.templateStyle) {
+			this.templateStyle = this.doc.createElement("style");
+			this.shadow.appendChild(this.templateStyle);
+		}
+		if (this.templateStyle.textContent !== css) this.templateStyle.textContent = css;
+	}
+	mount() {
+		if (this.host) return this.host;
+		const host = this.doc.createElement("div");
+		host.setAttribute("data-docent-host", "");
+		const shadow = host.attachShadow({ mode: "open" });
+		const style = this.doc.createElement("style");
+		style.textContent = this.options.css ? `${STYLES}\n${this.options.css}` : STYLES;
+		shadow.appendChild(style);
+		const overlay = new Overlay(this.doc);
+		shadow.appendChild(overlay.el);
+		shadow.appendChild(overlay.blocker);
+		this.doc.body.appendChild(host);
+		this.host = host;
+		this.shadow = shadow;
+		this.overlay = overlay;
+		return host;
+	}
+	teardownStep() {
+		for (const c of this.cleanups) c();
+		this.cleanups = [];
+		if (this.frame !== void 0) cancelAnimationFrame(this.frame);
+		this.frame = void 0;
+		this.popover?.remove();
+		this.popover = void 0;
+		this.arrow = void 0;
+		this.ctx = void 0;
+		this.target = null;
+		this.sheetAdjusted = false;
+	}
+	blocksInteraction(step) {
+		if (step.interaction) return step.interaction === "block";
+		const advance = step.advance;
+		return !(typeof advance === "object" && (advance.on === "click" || advance.on === "input"));
+	}
+	/** Returns true when a smooth scroll was started (callers must wait for it to settle). */
+	scrollIntoView(el, step) {
+		const scroll = {
+			...this.ctx?.tour.options?.scroll,
+			...step.scroll
+		};
+		if (scroll.enabled === false) return false;
+		const r = el.getBoundingClientRect();
+		const v = this.viewport();
+		const vx = v.x ?? 0;
+		const vy = v.y ?? 0;
+		const behavior = scroll.behavior ?? "auto";
+		if (r.height > v.height || r.width > v.width) {
+			const topVisible = r.top >= vy && r.top < vy + v.height && r.left < vx + v.width;
+			if (!topVisible) el.scrollIntoView({
+				block: "start",
+				inline: "start",
+				behavior
+			});
+			return !topVisible && behavior === "smooth";
+		}
+		if (r.top >= vy && r.left >= vx && r.bottom <= vy + v.height && r.right <= vx + v.width) return false;
+		el.scrollIntoView({
+			block: scroll.block ?? "center",
+			inline: "nearest",
+			behavior
+		});
+		return behavior === "smooth";
+	}
+	scheduleUpdate = () => {
+		if (this.frame !== void 0) return;
+		this.frame = requestAnimationFrame(() => {
+			this.frame = void 0;
+			this.update();
+		});
+	};
+	listen() {
+		const win = this.doc.defaultView;
+		const ctx = this.ctx;
+		if (!win || !ctx) return;
+		const on = (type, handler, opts) => {
+			win.addEventListener(type, handler, opts);
+			this.cleanups.push(() => win.removeEventListener(type, handler, opts));
+		};
+		on("scroll", this.scheduleUpdate, {
+			capture: true,
+			passive: true
+		});
+		on("resize", this.scheduleUpdate, { passive: true });
+		const vv = win.visualViewport;
+		if (vv) {
+			vv.addEventListener("resize", this.scheduleUpdate);
+			vv.addEventListener("scroll", this.scheduleUpdate);
+			this.cleanups.push(() => {
+				vv.removeEventListener("resize", this.scheduleUpdate);
+				vv.removeEventListener("scroll", this.scheduleUpdate);
+			});
+		}
+		if (typeof ResizeObserver !== "undefined") {
+			const ro = new ResizeObserver(this.scheduleUpdate);
+			if (this.target) ro.observe(this.target);
+			ro.observe(this.doc.documentElement);
+			if (this.popover) ro.observe(this.popover);
+			if (this.headlessContainer) ro.observe(this.headlessContainer);
+			this.cleanups.push(() => ro.disconnect());
+		}
+		const options = ctx.tour.options ?? {};
+		on("keydown", (e) => this.onKeydown(e, ctx), { capture: true });
+		if (options.closeOnOverlayClick && this.overlay) {
+			const overlayEl = this.overlay.el;
+			const handler = () => ctx.actions.skip();
+			overlayEl.addEventListener("click", handler);
+			this.cleanups.push(() => overlayEl.removeEventListener("click", handler));
+		}
+	}
+	onKeydown(e, ctx) {
+		const options = ctx.tour.options ?? {};
+		if (e.key === "Escape" && options.allowClose !== false) {
+			e.preventDefault();
+			ctx.actions.skip();
+			return;
+		}
+		if (e.key === "Tab") {
+			this.trapTab(e);
+			return;
+		}
+		if (options.keyboard === false) return;
+		if (e.target instanceof HTMLElement && /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName)) return;
+		if (e.key === "ArrowRight" && ctx.step.buttons?.next !== false) {
+			e.preventDefault();
+			ctx.actions.next();
+		} else if (e.key === "ArrowLeft" && ctx.canGoBack && ctx.step.buttons?.back !== false) {
+			e.preventDefault();
+			ctx.actions.back();
+		}
+	}
+	/** Keep Tab cycling inside the popover when focus is already in it. */
+	trapTab(e) {
+		const scope = this.headlessContainer ?? this.popover;
+		if (!scope) return;
+		const active = this.headlessContainer ? this.doc.activeElement : this.shadow?.activeElement;
+		const inside = active && (scope.contains(active) || this.host?.contains(active));
+		if (!active || !inside) return;
+		const items = (this.headlessContainer ? [scope] : [scope, ...this.host ? [this.host] : []]).flatMap((r) => Array.from(r.querySelectorAll(FOCUSABLE)));
+		if (items.length === 0) return;
+		const first = items[0];
+		const last = items[items.length - 1];
+		if (e.shiftKey && active === first) {
+			e.preventDefault();
+			last.focus();
+		} else if (!e.shiftKey && active === last) {
+			e.preventDefault();
+			first.focus();
+		}
+	}
+	wireAdvance(step) {
+		const advance = step.advance;
+		const ctx = this.ctx;
+		if (!ctx || typeof advance !== "object") return;
+		if (advance.on !== "click" && advance.on !== "input") return;
+		const el = advance.target === void 0 ? this.target : resolveTarget(advance.target, this.doc);
+		if (!el) return;
+		if (advance.on === "click") {
+			const handler = () => ctx.actions.next();
+			el.addEventListener("click", handler, { once: true });
+			this.cleanups.push(() => el.removeEventListener("click", handler));
+			return;
+		}
+		const pattern = advance.match ? new RegExp(advance.match) : /.+/;
+		const handler = (e) => {
+			const value = e.target.value ?? "";
+			if (pattern.test(value)) ctx.actions.next();
+		};
+		el.addEventListener("input", handler);
+		this.cleanups.push(() => el.removeEventListener("input", handler));
+	}
+};
+function toRect(r) {
+	return {
+		x: r.left,
+		y: r.top,
+		width: r.width,
+		height: r.height
+	};
+}
+//#endregion
+//#region src/storage.ts
+/**
+* `localStorage`-backed adapter. Falls back to memory when storage is
+* unavailable (private mode, blocked cookies, SSR).
+*/
+function createLocalStorage(storage) {
+	let backing;
+	try {
+		backing = storage ?? globalThis.localStorage;
+		const probe = "__docent__";
+		backing.setItem(probe, "1");
+		backing.removeItem(probe);
+	} catch {
+		return (0, _docentjs_core.createMemoryStorage)();
+	}
+	const guard = (fn, fallback) => {
+		try {
+			return fn();
+		} catch {
+			return fallback;
+		}
+	};
+	return {
+		get: (key) => guard(() => backing.getItem(key), null),
+		set: (key, value) => guard(() => backing.setItem(key, value), void 0),
+		remove: (key) => guard(() => backing.removeItem(key), void 0)
+	};
+}
+//#endregion
+//#region src/create.ts
+/**
+* A controller pre-wired for the browser: DOM renderer, localStorage
+* persistence and route change tracking.
+*/
+var DomTourController = class extends _docentjs_core.TourController {
+	cleanups = [];
+	constructor(tour, options = {}) {
+		const { renderer: rendererOptions, followRoutes, ...rest } = options;
+		const renderer = new DomRenderer(rendererOptions);
+		super({
+			...rest,
+			tour,
+			renderer,
+			storage: rest.storage ?? createLocalStorage()
+		});
+		if (followRoutes !== false && typeof window !== "undefined") {
+			const onChange = () => void this.routeChanged();
+			for (const type of ["popstate", "hashchange"]) {
+				window.addEventListener(type, onChange);
+				this.cleanups.push(() => window.removeEventListener(type, onChange));
+			}
+			const nav = window.navigation;
+			if (nav) {
+				nav.addEventListener("navigatesuccess", onChange);
+				this.cleanups.push(() => nav.removeEventListener("navigatesuccess", onChange));
+			}
+		}
+	}
+	async destroy() {
+		for (const c of this.cleanups) c();
+		this.cleanups.length = 0;
+		await super.destroy();
+	}
+};
+/** Create a browser-ready tour. Call `.start()` or `.resume()` on the result. */
+function createTour(tour, options) {
+	return new DomTourController(tour, options);
+}
+//#endregion
+exports.DEFAULT_LABELS = DEFAULT_LABELS;
+exports.DomRenderer = DomRenderer;
+exports.DomTourController = DomTourController;
+exports.NAME_ATTRIBUTE = NAME_ATTRIBUTE;
+exports.Overlay = Overlay;
+exports.THEME_VARS = THEME_VARS;
+exports.applyTheme = applyTheme;
+exports.availableSpace = availableSpace;
+exports.buildHeadlessShell = buildHeadlessShell;
+exports.buildPopover = buildPopover;
+exports.candidateSelectors = candidateSelectors;
+exports.centerPosition = centerPosition;
+exports.computePosition = computePosition;
+exports.createLocalStorage = createLocalStorage;
+exports.createTour = createTour;
+Object.defineProperty(exports, "defineTour", {
+	enumerable: true,
+	get: function() {
+		return _docentjs_core.defineTour;
+	}
+});
+exports.findOccluder = findOccluder;
+exports.formatProgress = formatProgress;
+exports.holePath = holePath;
+exports.inflate = inflate;
+exports.isSafeUrl = isSafeUrl;
+exports.mergeThemes = mergeThemes;
+exports.parsePlacement = parsePlacement;
+exports.queryAllDeep = queryAllDeep;
+exports.renderBody = renderBody;
+exports.renderMedia = renderMedia;
+exports.resolveSlots = resolveSlots;
+exports.resolveTarget = resolveTarget;
+exports.toSpec = toSpec;
+exports.uncover = uncover;
+exports.waitForTarget = waitForTarget;
+
+//# sourceMappingURL=index.cjs.map