@docentjs/dom 0.3.1 → 0.5.0

package/dist/index.js

@@ -1,3 +1,4 @@
+import { n as arrowGap, r as isConnector, t as CONNECTOR_STYLES } from "./arrows-Dcnwi9T-.js";
 import { Docent, TourController, createMemoryStorage, defineTour } from "@docentjs/core";
 //#region src/content.ts
 const SAFE_SCHEMES = /* @__PURE__ */ new Set([
@@ -266,19 +267,46 @@ function clipToViewport(rect, viewport) {
 }
 //#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`}")`;
 }
+/** The padded cutout and its corner radius for a shape. */
+function holeFor(target, padding, radius, shape = "rounded") {
+	if (shape === "circle") {
+		const cx = target.x + target.width / 2;
+		const cy = target.y + target.height / 2;
+		const rr = Math.hypot(target.width, target.height) / 2 + padding;
+		return {
+			hole: {
+				x: cx - rr,
+				y: cy - rr,
+				width: rr * 2,
+				height: rr * 2
+			},
+			radius: rr
+		};
+	}
+	const hole = inflate(target, padding);
+	if (shape === "rect") return {
+		hole,
+		radius: 0
+	};
+	if (shape === "pill") return {
+		hole,
+		radius: Math.min(hole.width, hole.height) / 2
+	};
+	return {
+		hole,
+		radius: Math.max(0, Math.min(radius, hole.width / 2, hole.height / 2))
+	};
+}
 var Overlay = class {
 	el;
 	blocker;
+	/** Hairline of light around the cutout. */
+	ring;
 	lastHole = null;
 	constructor(doc) {
 		this.el = doc.createElement("div");
@@ -287,29 +315,52 @@ var Overlay = class {
 		this.blocker = doc.createElement("div");
 		this.blocker.className = "blocker";
 		this.blocker.hidden = true;
+		this.ring = doc.createElement("div");
+		this.ring.className = "ring";
+		this.ring.setAttribute("part", "ring");
+		this.ring.style.opacity = "0";
+	}
+	/** Move the ring to a rect; a zero-size rect collapses it (modal steps). */
+	placeRing(rect, radius, visible) {
+		Object.assign(this.ring.style, {
+			transform: `translate(${rect.x}px, ${rect.y}px)`,
+			width: `${rect.width}px`,
+			height: `${rect.height}px`,
+			borderRadius: `${radius}px`,
+			opacity: visible ? "1" : "0"
+		});
 	}
 	/** 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 {
+	update(viewport, { target, padding, radius, shape }, block) {
+		if (!target) {
 			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.setCentre(cx, cy);
 			this.el.style.clipPath = holePath(viewport, {
 				x: cx,
 				y: cy,
 				width: 0,
 				height: 0
 			}, 0);
+			this.placeRing({
+				x: cx,
+				y: cy,
+				width: 0,
+				height: 0
+			}, 0, false);
 			this.blocker.hidden = true;
 			return;
 		}
-		const hole = this.lastHole;
-		this.el.style.clipPath = holePath(viewport, hole, radius);
+		const { hole, radius: r } = holeFor(target, padding, radius, shape);
+		this.lastHole = hole;
+		this.setCentre(hole.x + hole.width / 2, hole.y + hole.height / 2);
+		this.el.style.clipPath = holePath(viewport, hole, r);
+		this.placeRing(hole, r, true);
 		this.blocker.hidden = !block;
 		if (block) {
 			this.blocker.style.transform = `translate(${hole.x}px, ${hole.y}px)`;
@@ -317,6 +368,11 @@ var Overlay = class {
 			this.blocker.style.height = `${hole.height}px`;
 		}
 	}
+	/** Exposed for the vignette style, which is centred on the cutout. */
+	setCentre(x, y) {
+		this.el.style.setProperty("--docent-hole-x", `${Math.round(x)}px`);
+		this.el.style.setProperty("--docent-hole-y", `${Math.round(y)}px`);
+	}
 };
 //#endregion
 //#region src/popover.ts
@@ -340,6 +396,37 @@ function slot(doc, name, fallback) {
 	if (fallback) s.appendChild(fallback);
 	return s;
 }
+const SVG_NS = "http://www.w3.org/2000/svg";
+/** A 14px stroked X, drawn rather than typed so it centers optically in any font. */
+function closeIcon(doc) {
+	const svg = doc.createElementNS(SVG_NS, "svg");
+	svg.setAttribute("viewBox", "0 0 14 14");
+	svg.setAttribute("aria-hidden", "true");
+	svg.setAttribute("fill", "none");
+	const path = doc.createElementNS(SVG_NS, "path");
+	path.setAttribute("d", "M3.5 3.5l7 7m0-7l-7 7");
+	path.setAttribute("stroke", "currentColor");
+	path.setAttribute("stroke-width", "1.6");
+	path.setAttribute("stroke-linecap", "round");
+	svg.appendChild(path);
+	return svg;
+}
+/** A small forward arrow for the primary action, so direction reads at a glance. */
+function arrowIcon(doc) {
+	const svg = doc.createElementNS(SVG_NS, "svg");
+	svg.setAttribute("viewBox", "0 0 12 12");
+	svg.setAttribute("aria-hidden", "true");
+	svg.setAttribute("fill", "none");
+	svg.setAttribute("class", "icon");
+	const path = doc.createElementNS(SVG_NS, "path");
+	path.setAttribute("d", "M2.5 6h7m-3-3l3 3-3 3");
+	path.setAttribute("stroke", "currentColor");
+	path.setAttribute("stroke-width", "1.5");
+	path.setAttribute("stroke-linecap", "round");
+	path.setAttribute("stroke-linejoin", "round");
+	svg.appendChild(path);
+	return svg;
+}
 function formatProgress(template, current, total) {
 	return template.replace("{current}", String(current)).replace("{total}", String(total));
 }
@@ -397,7 +484,7 @@ function buildPopover(doc, ctx, labels = {}, slots = {}) {
 		const close = h(doc, "button", "close", "close");
 		close.type = "button";
 		close.setAttribute("aria-label", text.close);
-		close.textContent = "×";
+		close.appendChild(closeIcon(doc));
 		close.addEventListener("click", () => actions.skip());
 		closeNode = close;
 	}
@@ -424,7 +511,15 @@ function buildPopover(doc, ctx, labels = {}, slots = {}) {
 	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);
+	if (options.showProgress !== false) {
+		const meter = h(doc, "span", "meter", "meter");
+		meter.setAttribute("aria-hidden", "true");
+		progress.style.setProperty("--docent-step", String(ctx.progress.current));
+		progress.style.setProperty("--docent-steps", String(Math.max(1, ctx.progress.total)));
+		const count = h(doc, "span", "count", "count");
+		count.textContent = formatProgress(text.progress, ctx.progress.current, ctx.progress.total);
+		progress.append(meter, count);
+	}
 	footer.appendChild(slot(doc, "progress", progress));
 	const group = h(doc, "div", "buttons", "buttons");
 	let initialFocus = el;
@@ -436,9 +531,12 @@ function buildPopover(doc, ctx, labels = {}, slots = {}) {
 		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);
+	if (buttons.back !== false && ctx.canGoBack) button(text.back, "button-back", false, actions.back);
+	if (buttons.next !== false) {
+		initialFocus = button(ctx.isLast ? text.done : text.next, "button-next", true, actions.next);
+		if (!ctx.isLast) initialFocus.appendChild(arrowIcon(doc));
+	}
 	footer.appendChild(slot(doc, "buttons", group));
 	el.appendChild(slot(doc, "footer", footer));
 	const slotted = resolveSlots(doc, slots, ctx);
@@ -466,146 +564,15 @@ function buildHeadlessShell(doc) {
 }
 //#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: 220ms;
-  /* Fast start, gentle stop: movement begins the moment you click. */
-  --docent-easing: cubic-bezier(0.2, 0.8, 0.2, 1);
-  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) var(--docent-easing);
-}
-.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) var(--docent-easing), opacity var(--docent-duration) var(--docent-easing);
-}
-.popover[data-entering] { opacity: 0; transition: none; }
-/* Between steps the popover slides; only its content cross-fades, briefly. */
-.popover[data-moving] > * { animation: docent-swap 160ms ease-out; }
-@keyframes docent-swap { from { opacity: 0; } to { opacity: 1; } }
-.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; }
-  .popover[data-moving] > * { animation: none; }
-}
-`;
+/**
+* Styles injected into the shadow root. Theme through the custom properties.
+*
+* Design: quiet precision (see .impeccable.md). The popover inherits the host
+* site's font; hierarchy comes from size, weight, tracking and color. Colors
+* are ink tinted toward the Docent hue (OKLCH 285). Light is the default;
+* dark is opt-in through tokens or the `dark` preset.
+*/
+const STYLES = `:host{--docent-bg:oklch(99.4% 0.003 285);--docent-fg:oklch(23% 0.018 285);--docent-muted:oklch(52% 0.014 285);--docent-accent:oklch(26% 0.02 285);--docent-accent-fg:oklch(98.5% 0.004 285);--docent-radius:14px;--docent-shadow:0 1px 2px oklch(23% 0.02 285 / 0.06),0 8px 24px -6px oklch(23% 0.02 285 / 0.16),0 28px 56px -16px oklch(23% 0.02 285 / 0.24);--docent-width:344px;--docent-overlay:oklch(20% 0.02 285);--docent-overlay-opacity:0.52;--docent-duration:220ms;--docent-easing:cubic-bezier(0.2,0.8,0.2,1);--_line:color-mix(in oklch,var(--docent-fg) 11%,transparent);--_soft:color-mix(in oklch,var(--docent-fg) 6%,transparent);--_body:color-mix(in oklch,var(--docent-fg) 80%,var(--docent-bg));position:fixed;inset:0;z-index:var(--docent-z,2147483000);pointer-events:none;color:var(--docent-fg);font-family:var(--docent-font);font-size:14px;font-weight:400;font-style:normal;line-height:1.55;letter-spacing:normal;text-transform:none;text-align:start;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}*{box-sizing:border-box}.overlay{--_scrim:color-mix(in oklch,var(--docent-overlay) calc(var(--docent-overlay-opacity) * 100%),transparent);position:absolute;inset:0;background:var(--_scrim);pointer-events:auto;transition:clip-path var(--docent-duration) var(--docent-easing)}:host([data-overlay="blur"]) .overlay{-webkit-backdrop-filter:blur(var(--docent-blur,4px));backdrop-filter:blur(var(--docent-blur,4px))}:host([data-overlay="vignette"]) .overlay{background:radial-gradient( circle at var(--docent-hole-x,50%) var(--docent-hole-y,50%),transparent 0,color-mix(in oklch,var(--docent-overlay) calc(var(--docent-overlay-opacity) * 30%),transparent) 22%,var(--_scrim) 78% )}:host([data-overlay="none"]) .overlay{background:transparent;pointer-events:none}.blocker{position:absolute;left:0;top:0;pointer-events:auto}.ring{position:absolute;left:0;top:0;pointer-events:none;color:var(--docent-ring,oklch(98% 0.004 285));box-shadow:0 0 0 1px color-mix(in oklch,currentColor 58%,transparent),0 0 0 6px color-mix(in oklch,currentColor 8%,transparent);transition:transform var(--docent-duration) var(--docent-easing),width var(--docent-duration) var(--docent-easing),height var(--docent-duration) var(--docent-easing),border-radius var(--docent-duration) var(--docent-easing),opacity var(--docent-duration) var(--docent-easing)}:host([data-overlay="none"]) .ring{color:var(--docent-ring,var(--docent-accent))}:host([data-ring="none"]) .ring{box-shadow:none}:host([data-ring="glow"]) .ring{box-shadow:0 0 0 1.5px color-mix(in oklch,currentColor 85%,transparent),0 0 20px 4px color-mix(in oklch,currentColor 42%,transparent)}:host([data-ring="solid"]) .ring{box-shadow:0 0 0 2px currentColor}:host([data-ring="dashed"]) .ring{box-shadow:none;outline:1.5px dashed color-mix(in oklch,currentColor 85%,transparent);outline-offset:3px}:host([data-ring="pulse"]) .ring::after{content:"";position:absolute;inset:0;border-radius:inherit;animation:docent-pulse 1.8s var(--docent-easing) infinite}@keyframes docent-pulse{from{box-shadow:0 0 0 0 color-mix(in oklch,currentColor 60%,transparent)}to{box-shadow:0 0 0 14px transparent}}:host(:not([data-arrow="caret"])) .arrow{display:none}:host([data-tracking]) .overlay,:host([data-tracking]) .ring,:host([data-tracking]) .popover{transition:none}.popover{position:absolute;left:0;top:0;display:flex;flex-direction:column;width:var(--docent-width);max-width:calc(100vw - 32px);padding:20px 20px 16px;background:var(--docent-bg);border-radius:var(--docent-radius);box-shadow:0 0 0 1px var(--_line),var(--docent-shadow);pointer-events:auto;outline:none;transition:transform var(--docent-duration) var(--docent-easing),opacity var(--docent-duration) var(--docent-easing),scale var(--docent-duration) var(--docent-easing)}.popover[data-side="bottom"]{transform-origin:50% 0}.popover[data-side="top"]{transform-origin:50% 100%}.popover[data-side="right"]{transform-origin:0 50%}.popover[data-side="left"]{transform-origin:100% 50%}.popover[data-entering]{opacity:0;scale:0.97;transition:none}.popover[data-moving]>*{animation:docent-swap 160ms ease-out}@keyframes docent-swap{from{opacity:0}to{opacity:1}}.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="bottom"] .arrow{top:-6px;border-top:1px solid var(--_line);border-left:1px solid var(--_line);border-top-left-radius:2px}.popover[data-side="top"] .arrow{bottom:-6px;border-bottom:1px solid var(--_line);border-right:1px solid var(--_line);border-bottom-right-radius:2px}.popover[data-side="right"] .arrow{left:-6px;border-bottom:1px solid var(--_line);border-left:1px solid var(--_line);border-bottom-left-radius:2px}.popover[data-side="left"] .arrow{right:-6px;border-top:1px solid var(--_line);border-right:1px solid var(--_line);border-top-right-radius:2px}.popover[data-side="center"] .arrow,.popover[data-side="sheet"] .arrow{display:none}.header{display:flex;align-items:flex-start;gap:12px}.title{flex:1;min-width:0;margin:0;font-size:18px;font-weight:600;line-height:1.3;letter-spacing:-0.012em;color:var(--docent-fg);text-wrap:balance}.close{flex:none;display:grid;place-items:center;width:28px;height:28px;margin:-3px -8px -3px 0;padding:0;border:0;border-radius:8px;background:transparent;color:var(--docent-muted);cursor:pointer;transition:background-color 120ms ease-out,color 120ms ease-out}.close svg{width:14px;height:14px}.close:hover{background:var(--_soft);color:var(--docent-fg)}.body{margin-top:6px;color:var(--_body);text-wrap:pretty}.body p{margin:0}.body p + p{margin-top:8px}.body strong{font-weight:600;color:var(--docent-fg)}.body a{color:var(--docent-fg);text-decoration:underline;text-decoration-color:color-mix(in oklch,var(--docent-fg) 32%,transparent);text-decoration-thickness:1px;text-underline-offset:3px;transition:text-decoration-color 120ms ease-out}.body a:hover{text-decoration-color:currentColor}.body code{font-family:ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;font-size:0.88em;padding:1px 5px;border-radius:5px;background:var(--_soft);color:var(--docent-fg)}.media{margin-top:14px}.media img,.media video{display:block;width:100%;border-radius:8px;box-shadow:0 0 0 1px var(--_line)}.footer{display:flex;align-items:center;gap:12px;margin-top:20px}.progress{flex:1;display:flex;align-items:center;gap:8px;min-width:0;color:var(--docent-muted);font-size:12px;font-variant-numeric:tabular-nums;letter-spacing:0.01em;white-space:nowrap}.meter{flex:none;width:28px;height:3px;border-radius:999px;background:linear-gradient(var(--docent-fg),var(--docent-fg)) 0 0 / calc(var(--docent-step) / var(--docent-steps) * 100%) 100% no-repeat,var(--_line)}.buttons{display:flex;align-items:center;gap:6px}.button{appearance:none;display:inline-flex;align-items:center;justify-content:center;height:32px;padding:0 12px;border:0;border-radius:8px;background:transparent;color:var(--docent-fg);font:inherit;font-size:13px;font-weight:500;line-height:1;letter-spacing:-0.003em;white-space:nowrap;cursor:pointer;transition:background-color 120ms ease-out,color 120ms ease-out,scale 80ms ease-out}.button:hover{background:var(--_soft)}.button:active{scale:0.97}[part~="button-skip"]{color:var(--docent-muted);padding:0 8px}[part~="button-skip"]:hover{color:var(--docent-fg);background:transparent}.button.primary{padding:0 14px;background:var(--docent-accent);color:var(--docent-accent-fg);font-weight:600;box-shadow:inset 0 1px 0 color-mix(in oklch,var(--docent-accent-fg) 14%,transparent)}.button.primary .icon{width:12px;height:12px;margin:0 -2px 0 6px;transition:translate 160ms var(--docent-easing)}.button.primary:hover .icon{translate:2px 0}.button.primary:hover{background:color-mix(in oklch,var(--docent-accent) 86%,var(--docent-accent-fg))}.button:focus-visible,.close:focus-visible{outline:2px solid var(--docent-accent);outline-offset:2px}.popover.sheet{max-width:none;padding:20px 20px max(16px,env(safe-area-inset-bottom));border-radius:var(--docent-radius) var(--docent-radius) 0 0;box-shadow:0 0 0 1px var(--_line),0 -12px 40px -12px oklch(23% 0.02 285 / 0.28)}@media (pointer:coarse){:host{font-size:15px}.button{min-height:44px;padding:0 16px;font-size:14px}.close{width:40px;height:40px;margin:-9px -12px -9px 0}}@media (prefers-reduced-motion:reduce){.overlay,.popover,.ring{transition:none}.ring::after{animation:none !important}.popover[data-moving]>*{animation:none}}`;
 //#endregion
 //#region src/target.ts
 /** Attribute that `{ name }` targets resolve through. */
@@ -706,7 +673,9 @@ const THEME_VARS = {
 	overlay: "overlay",
 	overlayOpacity: "overlay-opacity",
 	duration: "duration",
-	zIndex: "z"
+	zIndex: "z",
+	connector: "connector",
+	ring: "ring"
 };
 /** Write theme tokens as inline custom properties on an element. Clears unset ones. */
 function applyTheme(el, theme) {
@@ -722,6 +691,11 @@ function mergeThemes(...themes) {
 }
 //#endregion
 //#region src/renderer.ts
+const DEFAULT_LOOK = {
+	arrow: "caret",
+	spotlight: {},
+	overlay: {}
+};
 const FOCUSABLE = "a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex=\"-1\"])";
 var DomRenderer = class {
 	doc;
@@ -740,6 +714,17 @@ var DomRenderer = class {
 	previousFocus = null;
 	/** Set once per step after the sheet has scrolled the target clear. */
 	sheetAdjusted = false;
+	connector;
+	/** Loaded on first use: connector styles cost nothing for tours that never use them. */
+	connectorModule;
+	connectorLoading;
+	/** Arrow, spotlight and overlay settings for the current step. */
+	look = DEFAULT_LOOK;
+	/** Until then the step's own transition runs; scroll updates may animate. */
+	settleUntil = 0;
+	/** Play the connector draw-in on its next render. */
+	drawConnector = false;
+	trackingFrame;
 	constructor(options = {}) {
 		this.options = options;
 		this.doc = options.document ?? document;
@@ -767,6 +752,9 @@ var DomRenderer = class {
 		const template = this.template(ctx);
 		applyTheme(host, mergeThemes(this.options.theme, template?.theme, ctx.tour.options?.theme));
 		this.setTemplateCss(template?.css);
+		this.applyLook(host, this.resolveLook(ctx, template));
+		this.settleUntil = performance.now() + this.duration(host) * 1.5;
+		this.drawConnector = true;
 		const initialFocus = this.options.headless ? this.buildHeadless(ctx, host, this.options.headless) : this.buildDefault(ctx, host, template);
 		if (this.popover && from) {
 			this.popover.style.transform = from;
@@ -797,31 +785,34 @@ var DomRenderer = class {
 			this.host = void 0;
 			this.shadow = void 0;
 			this.overlay = void 0;
+			this.connector = 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() {
+	/**
+	* Re-measure and re-position everything. Safe to call often. `tracking`
+	* marks updates caused by scroll or resize: once the step's own transition
+	* has finished, those follow the target instantly instead of trailing it.
+	*/
+	update(tracking = false) {
 		const ctx = this.ctx;
 		const overlay = this.overlay;
 		const popover = this.popover;
 		const win = this.doc.defaultView;
 		if (!ctx || !overlay || !popover || !win) return;
+		if (tracking && performance.now() > this.settleUntil) this.markTracking();
 		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 spotlight = this.look.spotlight;
+		const padding = spotlight.padding ?? 8;
+		const radius = spotlight.radius ?? 10;
+		const shape = spotlight.shape ?? "rounded";
 		const external = this.headlessContainer;
 		const sheet = this.isSheet(viewport);
 		popover.classList.toggle("sheet", sheet);
@@ -835,8 +826,10 @@ var DomRenderer = class {
 			overlay.update(overlaySize, {
 				target: rect,
 				padding,
-				radius
+				radius,
+				shape
 			}, this.blocksInteraction(ctx.step));
+			this.connector?.clear();
 			const vx = viewport.x ?? 0;
 			const top = (viewport.y ?? 0) + viewport.height - floating.height;
 			popover.style.transform = `translate(${vx}px, ${top}px)`;
@@ -851,6 +844,7 @@ var DomRenderer = class {
 				padding,
 				radius
 			}, false);
+			this.connector?.clear();
 			const { x, y } = centerPosition(floating, viewport);
 			popover.style.transform = `translate(${x}px, ${y}px)`;
 			popover.setAttribute("data-side", "center");
@@ -861,14 +855,16 @@ var DomRenderer = class {
 		overlay.update(overlaySize, {
 			target: rect,
 			padding,
-			radius
+			radius,
+			shape
 		}, this.blocksInteraction(ctx.step));
+		const hole = overlay.hole ?? rect;
 		const pos = computePosition({
-			anchor: clipToViewport(overlay.hole ?? rect, viewport),
+			anchor: clipToViewport(hole, viewport),
 			floating,
 			viewport,
 			placement: ctx.step.placement ?? "auto",
-			gap: this.options.gap ?? 12
+			gap: this.options.gap ?? arrowGap(this.look.arrow)
 		});
 		popover.style.transform = `translate(${pos.x}px, ${pos.y}px)`;
 		popover.setAttribute("data-side", pos.side);
@@ -881,6 +877,142 @@ var DomRenderer = class {
 			external.setAttribute("data-side", pos.side);
 			external.style.setProperty("--docent-arrow", `${pos.arrow}px`);
 		}
+		this.renderConnector(pos, floating, hole);
+	}
+	/** Draw the connector for connector arrow styles; clear it otherwise. */
+	renderConnector(pos, floating, hole) {
+		const style = this.look.arrow;
+		if (!isConnector(style)) {
+			this.connector?.clear();
+			return;
+		}
+		const mod = this.connectorModule;
+		const connector = this.connector;
+		if (!mod || !connector) {
+			this.loadConnector();
+			return;
+		}
+		const inset = 6;
+		const clampX = (x) => Math.min(Math.max(x, hole.x + 10), hole.x + hole.width - 10);
+		const clampY = (y) => Math.min(Math.max(y, hole.y + 10), hole.y + hole.height - 10);
+		const cx = hole.x + hole.width / 2;
+		const cy = hole.y + hole.height / 2;
+		const alongX = pos.x + floating.width * (cx < pos.x + floating.width / 2 ? .3 : .7);
+		const alongY = pos.y + floating.height * (cy < pos.y + floating.height / 2 ? .3 : .7);
+		let from;
+		let to;
+		switch (pos.side) {
+			case "bottom":
+				from = {
+					x: alongX,
+					y: pos.y
+				};
+				to = {
+					x: clampX(cx),
+					y: hole.y + hole.height + inset
+				};
+				break;
+			case "top":
+				from = {
+					x: alongX,
+					y: pos.y + floating.height
+				};
+				to = {
+					x: clampX(cx),
+					y: hole.y - inset
+				};
+				break;
+			case "right":
+				from = {
+					x: pos.x,
+					y: alongY
+				};
+				to = {
+					x: hole.x + hole.width + inset,
+					y: clampY(cy)
+				};
+				break;
+			default:
+				from = {
+					x: pos.x + floating.width,
+					y: alongY
+				};
+				to = {
+					x: hole.x - inset,
+					y: clampY(cy)
+				};
+		}
+		const bend = pos.side === "top" || pos.side === "bottom" ? to.x < from.x ? 1 : -1 : to.y < from.y ? -1 : 1;
+		connector.render(mod.connectorShape(style, from, to, pos.side === "top" || pos.side === "left" ? -bend : bend), this.drawConnector);
+		this.drawConnector = false;
+	}
+	/** Fetch the connector module once, then draw with it. */
+	loadConnector() {
+		this.connectorLoading ??= import("./connector-CzqD6NJY.js").then((mod) => {
+			this.connectorModule = mod;
+			if (this.shadow) this.attachConnector(this.shadow, mod);
+			this.update();
+		});
+	}
+	/** Add the connector layer and its styles, beneath any popover. */
+	attachConnector(shadow, mod) {
+		if (this.connector) return;
+		const style = this.doc.createElement("style");
+		style.textContent = mod.CONNECTOR_STYLES_CSS;
+		this.connector = new mod.Connector(this.doc);
+		const before = this.popover ?? null;
+		shadow.insertBefore(style, before);
+		shadow.insertBefore(this.connector.el, before);
+	}
+	resolveLook(ctx, template) {
+		const tour = ctx.tour.options ?? {};
+		const step = ctx.step;
+		return {
+			arrow: step.arrow ?? tour.arrow ?? template?.arrow ?? this.options.arrow ?? "caret",
+			spotlight: {
+				...this.options.spotlight,
+				...template?.spotlight,
+				...tour.spotlight,
+				...step.spotlight
+			},
+			overlay: {
+				...this.options.overlay,
+				...template?.overlay,
+				...tour.overlay,
+				...step.overlay
+			}
+		};
+	}
+	/** Expose the look to the stylesheet as host attributes and variables. */
+	applyLook(host, look) {
+		this.look = look;
+		host.setAttribute("data-arrow", look.arrow);
+		host.setAttribute("data-ring", look.spotlight.ring ?? "hairline");
+		host.setAttribute("data-shape", look.spotlight.shape ?? "rounded");
+		host.setAttribute("data-overlay", look.overlay.style ?? "dim");
+		const { color, opacity, blur } = look.overlay;
+		if (color !== void 0) host.style.setProperty("--docent-overlay", color);
+		if (opacity !== void 0) host.style.setProperty("--docent-overlay-opacity", String(opacity));
+		if (blur !== void 0) host.style.setProperty("--docent-blur", `${blur}px`);
+		else host.style.removeProperty("--docent-blur");
+	}
+	/** The current transition duration in ms, from the --docent-duration token. */
+	duration(host) {
+		const raw = this.doc.defaultView?.getComputedStyle(host).getPropertyValue("--docent-duration").trim() ?? "";
+		const n = Number.parseFloat(raw);
+		if (Number.isNaN(n)) return 220;
+		return raw.endsWith("ms") ? n : n * 1e3;
+	}
+	/** Disable transitions for this frame so scroll-driven moves stay glued to the target. */
+	markTracking() {
+		const host = this.host;
+		if (!host) return;
+		host.setAttribute("data-tracking", "");
+		if (this.trackingFrame !== void 0) cancelAnimationFrame(this.trackingFrame);
+		this.trackingFrame = requestAnimationFrame(() => {
+			this.trackingFrame = void 0;
+			host.removeAttribute("data-tracking");
+		});
 	}
 	/**
 	* The visible area in layout-viewport coordinates. Uses the visual viewport
@@ -1017,7 +1149,9 @@ var DomRenderer = class {
 		shadow.appendChild(style);
 		const overlay = new Overlay(this.doc);
 		shadow.appendChild(overlay.el);
+		shadow.appendChild(overlay.ring);
 		shadow.appendChild(overlay.blocker);
+		if (this.connectorModule) this.attachConnector(shadow, this.connectorModule);
 		this.doc.body.appendChild(host);
 		this.host = host;
 		this.shadow = shadow;
@@ -1031,6 +1165,7 @@ var DomRenderer = class {
 		this.frame = void 0;
 		this.popover?.remove();
 		this.popover = void 0;
+		this.connector?.clear();
 		this.arrow = void 0;
 		this.ctx = void 0;
 		this.target = null;
@@ -1074,7 +1209,7 @@ var DomRenderer = class {
 		if (this.frame !== void 0) return;
 		this.frame = requestAnimationFrame(() => {
 			this.frame = void 0;
-			this.update();
+			this.update(true);
 		});
 	};
 	listen() {
@@ -1345,6 +1480,6 @@ function createDocent(options = {}) {
 	});
 }
 //#endregion
-export { DEFAULT_LABELS, DomRenderer, DomTourController, NAME_ATTRIBUTE, Overlay, THEME_VARS, applyTheme, availableSpace, buildHeadlessShell, buildPopover, candidateSelectors, centerPosition, computePosition, createDocent, createDomEnvironment, createLocalStorage, createTour, defineTour, findOccluder, formatProgress, holePath, inflate, isSafeUrl, mergeThemes, parsePlacement, queryAllDeep, renderBody, renderMedia, resolveSlots, resolveTarget, toSpec, uncover, waitForTarget };
+export { CONNECTOR_STYLES, DEFAULT_LABELS, DomRenderer, DomTourController, NAME_ATTRIBUTE, Overlay, THEME_VARS, applyTheme, arrowGap, availableSpace, buildHeadlessShell, buildPopover, candidateSelectors, centerPosition, computePosition, createDocent, createDomEnvironment, createLocalStorage, createTour, defineTour, findOccluder, formatProgress, holePath, inflate, isConnector, isSafeUrl, mergeThemes, parsePlacement, queryAllDeep, renderBody, renderMedia, resolveSlots, resolveTarget, toSpec, uncover, waitForTarget };
 
 //# sourceMappingURL=index.js.map