@docentjs/dom 0.4.0 → 0.5.1

package/dist/index.d.cts

@@ -1,4 +1,11 @@
-import { Alignment, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, Placement, RenderContext, Renderer, Side, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+import { Alignment, ArrowStyle, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, OverlayOptions, Placement, RenderContext, Renderer, Side, SpotlightOptions, SpotlightShape, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+//#region src/arrows.d.ts
+export declare const CONNECTOR_STYLES: readonly ["line", "dashed", "dotted", "curve", "curve-dashed", "squiggle", "loop", "elbow", "sketch", "pin"];
+type ConnectorStyle = (typeof CONNECTOR_STYLES)[number];
+export declare function isConnector(style: ArrowStyle): style is ConnectorStyle;
+/** Space between target and popover for a style: connectors need room to be seen. */
+export declare function arrowGap(style: ArrowStyle): number;
+//#endregion
 //#region src/content.d.ts
 export declare function isSafeUrl(url: string): boolean;
 export declare function renderBody(doc: Document, body: string, format?: 'text' | 'markdown'): DocumentFragment;
@@ -34,6 +41,10 @@ type PopoverSlots = Partial<Record<SlotName, SlotRenderer>>;
 interface PopoverTemplate {
   theme?: Theme;
   slots?: PopoverSlots;
+  /** Arrow style for tours using this template. */
+  arrow?: ArrowStyle;
+  spotlight?: SpotlightOptions;
+  overlay?: OverlayOptions;
   /** Extra CSS injected into the shadow root while this template is active. */
   css?: string;
 }
@@ -55,11 +66,12 @@ interface DomRendererOptions {
   labels?: Labels;
   /** Distance between target and popover, in px. */
   gap?: number;
-  /** Spotlight defaults when a tour sets none. */
-  spotlight?: {
-    padding?: number;
-    radius?: number;
-  };
+  /** Spotlight defaults when a tour sets none: padding, radius, shape, ring. */
+  spotlight?: SpotlightOptions;
+  /** Arrow style when a tour sets none. Default `caret`. */
+  arrow?: ArrowStyle;
+  /** Overlay defaults when a tour sets none: style, color, opacity, blur. */
+  overlay?: OverlayOptions;
   /** Base theme tokens. Tours and templates layer on top. */
   theme?: Theme;
   /** Replace regions of the built-in popover. */
@@ -97,14 +109,42 @@ export declare class DomRenderer implements Renderer {
   private previousFocus;
   /** Set once per step after the sheet has scrolled the target clear. */
   private sheetAdjusted;
+  private connector;
+  /** Loaded on first use: connector styles cost nothing for tours that never use them. */
+  private connectorModule;
+  private connectorLoading;
+  /** Arrow, spotlight and overlay settings for the current step. */
+  private look;
+  /** Until then the step's own transition runs; scroll updates may animate. */
+  private settleUntil;
+  /** Play the connector draw-in on its next render. */
+  private drawConnector;
+  private trackingFrame;
   constructor(options?: DomRendererOptions);
   hasTarget(target: Target): boolean;
   waitForTarget(target: Target, timeoutMs: number, signal: AbortSignal): Promise<boolean>;
   currentRoute(): string;
   show(ctx: RenderContext): void;
   hide(): void;
-  /** Re-measure and re-position everything. Safe to call often. */
-  update(): void;
+  /**
+   * 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?: boolean): void;
+  /** Draw the connector for connector arrow styles; clear it otherwise. */
+  private renderConnector;
+  /** Fetch the connector module once, then draw with it. */
+  private loadConnector;
+  /** Add the connector layer and its styles, beneath any popover. */
+  private attachConnector;
+  private resolveLook;
+  /** Expose the look to the stylesheet as host attributes and variables. */
+  private applyLook;
+  /** The current transition duration in ms, from the --docent-duration token. */
+  private duration;
+  /** Disable transitions for this frame so scroll-driven moves stay glued to the target. */
+  private markTracking;
   /**
    * The visible area in layout-viewport coordinates. Uses the visual viewport
    * so pinch zoom, the on-screen keyboard and pages that overflow on mobile
@@ -263,6 +303,7 @@ interface OverlayUpdate {
   target: Rect | null;
   padding: number;
   radius: number;
+  shape?: SpotlightShape;
 }
 export declare class Overlay {
   readonly el: HTMLDivElement;
@@ -275,7 +316,9 @@ export declare class Overlay {
   private placeRing;
   /** Current hole, padded, in viewport coordinates. */
   get hole(): Rect | null;
-  update(viewport: Size, { target, padding, radius }: OverlayUpdate, block: boolean): void;
+  update(viewport: Size, { target, padding, radius, shape }: OverlayUpdate, block: boolean): void;
+  /** Exposed for the vignette style, which is centred on the cutout. */
+  private setCentre;
 }
 //#endregion
 //#region src/popover.d.ts
@@ -324,5 +367,5 @@ export declare function resolveTarget(target: Target, root?: QueryRoot): Element
  */
 export declare function waitForTarget(target: Target, timeoutMs: number, signal?: AbortSignal, root?: QueryRoot): Promise<Element | null>;
 //#endregion
-export { type CreateDocentOptions, type CreateTourOptions, type DomRendererOptions, type HeadlessPopover, type Occluder, type PopoverSlots, type PopoverTemplate, type PositionInput, type PositionResult, type QueryRoot, type Rect, type Size, type SlotContent, type SlotName, type SlotRenderer, defineTour };
+export { type ConnectorStyle, type CreateDocentOptions, type CreateTourOptions, type DomRendererOptions, type HeadlessPopover, type Occluder, type PopoverSlots, type PopoverTemplate, type PositionInput, type PositionResult, type QueryRoot, type Rect, type Size, type SlotContent, type SlotName, type SlotRenderer, defineTour };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,4 +1,11 @@
-import { Alignment, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, Placement, RenderContext, Renderer, Side, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+import { Alignment, ArrowStyle, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, OverlayOptions, Placement, RenderContext, Renderer, Side, SpotlightOptions, SpotlightShape, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+//#region src/arrows.d.ts
+export declare const CONNECTOR_STYLES: readonly ["line", "dashed", "dotted", "curve", "curve-dashed", "squiggle", "loop", "elbow", "sketch", "pin"];
+type ConnectorStyle = (typeof CONNECTOR_STYLES)[number];
+export declare function isConnector(style: ArrowStyle): style is ConnectorStyle;
+/** Space between target and popover for a style: connectors need room to be seen. */
+export declare function arrowGap(style: ArrowStyle): number;
+//#endregion
 //#region src/content.d.ts
 export declare function isSafeUrl(url: string): boolean;
 export declare function renderBody(doc: Document, body: string, format?: 'text' | 'markdown'): DocumentFragment;
@@ -34,6 +41,10 @@ type PopoverSlots = Partial<Record<SlotName, SlotRenderer>>;
 interface PopoverTemplate {
   theme?: Theme;
   slots?: PopoverSlots;
+  /** Arrow style for tours using this template. */
+  arrow?: ArrowStyle;
+  spotlight?: SpotlightOptions;
+  overlay?: OverlayOptions;
   /** Extra CSS injected into the shadow root while this template is active. */
   css?: string;
 }
@@ -55,11 +66,12 @@ interface DomRendererOptions {
   labels?: Labels;
   /** Distance between target and popover, in px. */
   gap?: number;
-  /** Spotlight defaults when a tour sets none. */
-  spotlight?: {
-    padding?: number;
-    radius?: number;
-  };
+  /** Spotlight defaults when a tour sets none: padding, radius, shape, ring. */
+  spotlight?: SpotlightOptions;
+  /** Arrow style when a tour sets none. Default `caret`. */
+  arrow?: ArrowStyle;
+  /** Overlay defaults when a tour sets none: style, color, opacity, blur. */
+  overlay?: OverlayOptions;
   /** Base theme tokens. Tours and templates layer on top. */
   theme?: Theme;
   /** Replace regions of the built-in popover. */
@@ -97,14 +109,42 @@ export declare class DomRenderer implements Renderer {
   private previousFocus;
   /** Set once per step after the sheet has scrolled the target clear. */
   private sheetAdjusted;
+  private connector;
+  /** Loaded on first use: connector styles cost nothing for tours that never use them. */
+  private connectorModule;
+  private connectorLoading;
+  /** Arrow, spotlight and overlay settings for the current step. */
+  private look;
+  /** Until then the step's own transition runs; scroll updates may animate. */
+  private settleUntil;
+  /** Play the connector draw-in on its next render. */
+  private drawConnector;
+  private trackingFrame;
   constructor(options?: DomRendererOptions);
   hasTarget(target: Target): boolean;
   waitForTarget(target: Target, timeoutMs: number, signal: AbortSignal): Promise<boolean>;
   currentRoute(): string;
   show(ctx: RenderContext): void;
   hide(): void;
-  /** Re-measure and re-position everything. Safe to call often. */
-  update(): void;
+  /**
+   * 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?: boolean): void;
+  /** Draw the connector for connector arrow styles; clear it otherwise. */
+  private renderConnector;
+  /** Fetch the connector module once, then draw with it. */
+  private loadConnector;
+  /** Add the connector layer and its styles, beneath any popover. */
+  private attachConnector;
+  private resolveLook;
+  /** Expose the look to the stylesheet as host attributes and variables. */
+  private applyLook;
+  /** The current transition duration in ms, from the --docent-duration token. */
+  private duration;
+  /** Disable transitions for this frame so scroll-driven moves stay glued to the target. */
+  private markTracking;
   /**
    * The visible area in layout-viewport coordinates. Uses the visual viewport
    * so pinch zoom, the on-screen keyboard and pages that overflow on mobile
@@ -263,6 +303,7 @@ interface OverlayUpdate {
   target: Rect | null;
   padding: number;
   radius: number;
+  shape?: SpotlightShape;
 }
 export declare class Overlay {
   readonly el: HTMLDivElement;
@@ -275,7 +316,9 @@ export declare class Overlay {
   private placeRing;
   /** Current hole, padded, in viewport coordinates. */
   get hole(): Rect | null;
-  update(viewport: Size, { target, padding, radius }: OverlayUpdate, block: boolean): void;
+  update(viewport: Size, { target, padding, radius, shape }: OverlayUpdate, block: boolean): void;
+  /** Exposed for the vignette style, which is centred on the cutout. */
+  private setCentre;
 }
 //#endregion
 //#region src/popover.d.ts
@@ -324,5 +367,5 @@ export declare function resolveTarget(target: Target, root?: QueryRoot): Element
  */
 export declare function waitForTarget(target: Target, timeoutMs: number, signal?: AbortSignal, root?: QueryRoot): Promise<Element | null>;
 //#endregion
-export { type CreateDocentOptions, type CreateTourOptions, type DomRendererOptions, type HeadlessPopover, type Occluder, type PopoverSlots, type PopoverTemplate, type PositionInput, type PositionResult, type QueryRoot, type Rect, type Size, type SlotContent, type SlotName, type SlotRenderer, defineTour };
+export { type ConnectorStyle, type CreateDocentOptions, type CreateTourOptions, type DomRendererOptions, type HeadlessPopover, type Occluder, type PopoverSlots, type PopoverTemplate, type PositionInput, type PositionResult, type QueryRoot, type Rect, type Size, type SlotContent, type SlotName, type SlotRenderer, defineTour };
 //# sourceMappingURL=index.d.ts.map

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,16 +267,41 @@ 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;
@@ -308,13 +334,13 @@ var Overlay = class {
 	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,
@@ -330,9 +356,11 @@ var Overlay = class {
 			this.blocker.hidden = true;
 			return;
 		}
-		const hole = this.lastHole;
-		this.el.style.clipPath = holePath(viewport, hole, radius);
-		this.placeRing(hole, Math.max(0, Math.min(radius, hole.width / 2, hole.height / 2)), true);
+		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)`;
@@ -340,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
@@ -539,7 +572,7 @@ function buildHeadlessShell(doc) {
 * 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{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}.ring{position:absolute;left:0;top:0;pointer-events:none;box-shadow:0 0 0 1px oklch(98% 0.004 285 / 0.58),0 0 0 6px oklch(98% 0.004 285 / 0.08);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)}.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}.popover[data-moving]>*{animation:none}}`;
+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. */
@@ -640,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) {
@@ -656,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;
@@ -674,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;
@@ -701,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;
@@ -731,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 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);
@@ -769,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)`;
@@ -785,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");
@@ -795,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);
@@ -815,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
@@ -953,6 +1151,7 @@ var DomRenderer = class {
 		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;
@@ -966,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;
@@ -1009,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() {
@@ -1280,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