@peekling/runtime 0.1.0 → 0.1.2

package/dist/peekling.js

@@ -1,4 +1,4 @@
-/*! @peekling/runtime 0.1.0 | Copyright 2026 Prajwal S. Venkateshmurthy | Apache-2.0 */
+/*! @peekling/runtime 0.1.2 | Copyright 2026 Prajwal S. Venkateshmurthy | Apache-2.0 */
 "use strict";
 (() => {
   // packages/runtime/src/runtime-diagnostics.ts
@@ -748,6 +748,8 @@
     #name;
     #nameSelection;
     #nameItem;
+    #userHidden = false;
+    #hasVisibleSurface = false;
     #destroyed = false;
     constructor(document, options = {}) {
       this.#document = document;
@@ -819,6 +821,16 @@
         if (surface.seen !== generation) this.#removeSurface(surface);
         if (this.#destroyed) return;
       }
+      let visible = false;
+      for (const surface of this.#surfaces.values()) {
+        if (!surface.host.hidden) {
+          visible = true;
+          break;
+        }
+      }
+      this.#hasVisibleSurface = visible;
+      const hidden = this.#userHidden || !visible;
+      if (this.#host.hidden !== hidden) this.#host.hidden = hidden;
       const viewportChanged = viewport.width !== this.#viewportWidth || viewport.height !== this.#viewportHeight;
       const placementChanged = viewportChanged || position.x !== this.#positionX || position.y !== this.#positionY || character.width !== this.#characterWidth || character.height !== this.#characterHeight;
       this.#positionX = position.x;
@@ -900,14 +912,26 @@
         }
         this.#placementDirty = false;
       }
-      let visible = false;
-      for (const surface of this.#surfaces.values()) {
-        if (!surface.host.hidden) {
-          visible = true;
-          break;
+    }
+    setUserHidden(hidden) {
+      if (this.#destroyed) return false;
+      const wasHidden = this.#userHidden;
+      this.#userHidden = hidden;
+      this.#host.hidden = hidden || !this.#hasVisibleSurface;
+      if (wasHidden && !hidden && !this.#host.hidden) {
+        for (const surface of this.#surfaces.values()) {
+          if (!surface.host.hidden) surface.measureDirty = true;
         }
+        this.#placementDirty = true;
+        this.#wake();
       }
-      if (this.#host.hidden === visible) this.#host.hidden = !visible;
+      return !this.#userHidden;
+    }
+    toggleUserHidden() {
+      return this.setUserHidden(!this.#userHidden);
+    }
+    get userHidden() {
+      return this.#userHidden;
     }
     #select(selection, item, generation) {
       for (const region of CONTENT_REGIONS) {
@@ -1460,11 +1484,10 @@
           true
         );
       } else if (event === "window.scroll") {
-        listen(
-          this.#window,
-          "scroll",
-          (input) => this.#captureObserved("window.scroll", input)
-        );
+        listen(this.#window, "scroll", (input) => {
+          this.#clearPointer();
+          this.#captureObserved("window.scroll", input);
+        });
       } else if (event === "window.focus") {
         listen(
           this.#window,
@@ -1531,6 +1554,208 @@
     return incoming[policy.sessionField] === prior[policy.sessionField] && Number.isSafeInteger(incoming[policy.revisionField]) && Number.isSafeInteger(prior[policy.revisionField]) && incoming[policy.revisionField] > prior[policy.revisionField];
   }
 
+  // packages/runtime/src/interaction.ts
+  var CharacterInteractionController = class {
+    ready;
+    #document;
+    #host;
+    #root;
+    #button;
+    #badge;
+    #styles;
+    #options;
+    #buttonRule;
+    #badgeRule;
+    #indicator;
+    #label;
+    #position = { x: 0, y: 0 };
+    #pointerId;
+    #startPointer = { x: 0, y: 0 };
+    #lastPointer = { x: 0, y: 0 };
+    #startPosition = { x: 0, y: 0 };
+    #velocity = { x: 0, y: 0 };
+    #lastTime = 0;
+    #moved = false;
+    #suppressClick = false;
+    #destroyed = false;
+    constructor(options) {
+      this.#options = options;
+      this.#document = options.document;
+      this.#label = options.label;
+      this.#host = options.document.createElement("div");
+      this.#host.setAttribute("data-peekling-interaction", "");
+      this.#root = this.#host.attachShadow({ mode: "closed" });
+      this.#styles = new ShadowStyleSheet(
+        options.document,
+        this.#root,
+        options.styles
+      );
+      this.#button = options.document.createElement("button");
+      this.#button.type = "button";
+      this.#button.className = "peekling-character-hit";
+      this.#button.setAttribute("aria-label", options.label);
+      if (options.expanded !== void 0) {
+        this.#button.setAttribute("aria-expanded", String(options.expanded));
+      }
+      this.#button.toggleAttribute("data-peekling-draggable", options.draggable);
+      this.#badge = options.document.createElement("span");
+      this.#badge.className = "peekling-character-indicator";
+      this.#badge.setAttribute("aria-hidden", "true");
+      this.#button.append(this.#badge);
+      this.#root.append(this.#button);
+      this.ready = this.#styles.ready.then(() => {
+        if (this.#destroyed) return;
+        this.#buttonRule = this.#styles.addRule(".peekling-character-hit");
+        this.#badgeRule = this.#styles.addRule(".peekling-character-indicator");
+        this.#syncIndicatorColor();
+      });
+      void this.ready.catch(() => {
+      });
+      this.#button.addEventListener("click", this.#click);
+      if (options.draggable) {
+        this.#button.addEventListener("pointerdown", this.#pointerDown);
+        this.#button.addEventListener("pointermove", this.#pointerMove);
+        this.#button.addEventListener("pointerup", this.#pointerUp);
+        this.#button.addEventListener("pointercancel", this.#pointerCancel);
+      }
+      this.updateIndicator(options.indicator);
+      this.#repair();
+    }
+    render(position, character, lift = 0) {
+      if (this.#destroyed) return;
+      this.#repair();
+      this.#position = { x: position.x, y: position.y - lift };
+      const rule = this.#buttonRule;
+      if (!rule) return;
+      const left = position.x - character.width / 2;
+      const top = position.y - character.height / 2 - lift;
+      rule.width = `${character.width}px`;
+      rule.height = `${character.height}px`;
+      rule.transform = `translate3d(${left}px,${top}px,0)`;
+    }
+    setHidden(hidden) {
+      if (!this.#destroyed) this.#host.toggleAttribute("hidden", hidden);
+    }
+    setExpanded(expanded) {
+      if (!this.#destroyed && this.#button.hasAttribute("aria-expanded")) {
+        this.#button.setAttribute("aria-expanded", String(expanded));
+      }
+    }
+    updateIndicator(indicator) {
+      if (this.#destroyed) return;
+      this.#indicator = indicator ?? void 0;
+      this.#syncIndicatorColor();
+      const visible = Boolean(
+        indicator && indicator.visible !== false && (indicator.kind !== "count" || (indicator.count ?? 0) > 0)
+      );
+      this.#badge.hidden = !visible;
+      if (!visible || !indicator) {
+        this.#badge.textContent = "";
+        this.#button.setAttribute("aria-label", this.#label);
+        return;
+      }
+      const kind = indicator.kind ?? "dot";
+      this.#badge.dataset.kind = kind;
+      this.#badge.textContent = kind === "count" ? String(Math.min(99, indicator.count ?? 0)) : "";
+      this.#button.setAttribute(
+        "aria-label",
+        `${this.#label}. ${indicator.label}`
+      );
+    }
+    #syncIndicatorColor() {
+      if (this.#badgeRule) {
+        this.#badgeRule.backgroundColor = this.#indicator?.color ?? "";
+      }
+    }
+    destroy() {
+      if (this.#destroyed) return;
+      this.#destroyed = true;
+      this.#styles.destroy();
+      this.#host.remove();
+    }
+    #click = () => {
+      if (this.#suppressClick) {
+        this.#suppressClick = false;
+        return;
+      }
+      this.#options.onPress();
+    };
+    #pointerDown = (event) => {
+      if (this.#destroyed || this.#pointerId !== void 0 || !event.isPrimary && event.pointerType !== "mouse" || event.pointerType === "mouse" && event.button !== 0) {
+        return;
+      }
+      this.#pointerId = event.pointerId;
+      this.#startPointer = { x: event.clientX, y: event.clientY };
+      this.#lastPointer = { ...this.#startPointer };
+      this.#startPosition = { ...this.#position };
+      this.#velocity = { x: 0, y: 0 };
+      this.#lastTime = event.timeStamp;
+      this.#moved = false;
+      try {
+        this.#button.setPointerCapture(event.pointerId);
+      } catch {
+      }
+      this.#options.onDragStart();
+    };
+    #pointerMove = (event) => {
+      if (event.pointerId !== this.#pointerId) return;
+      const dx = event.clientX - this.#startPointer.x;
+      const dy = event.clientY - this.#startPointer.y;
+      if (!this.#moved && Math.hypot(dx, dy) >= 4) this.#moved = true;
+      const elapsed = Math.max(
+        8,
+        Math.min(100, event.timeStamp - this.#lastTime)
+      );
+      const sampleX = (event.clientX - this.#lastPointer.x) * 1e3 / elapsed;
+      const sampleY = (event.clientY - this.#lastPointer.y) * 1e3 / elapsed;
+      this.#velocity = {
+        x: sampleX * 0.65 + this.#velocity.x * 0.35,
+        y: sampleY * 0.65 + this.#velocity.y * 0.35
+      };
+      this.#lastPointer = { x: event.clientX, y: event.clientY };
+      this.#lastTime = event.timeStamp;
+      this.#options.onDragMove(
+        {
+          x: this.#startPosition.x + dx,
+          y: this.#startPosition.y + dy
+        },
+        this.#velocity
+      );
+    };
+    #pointerUp = (event) => {
+      if (event.pointerId !== this.#pointerId) return;
+      this.#finishPointer(event, this.#moved, this.#velocity);
+    };
+    #pointerCancel = (event) => {
+      if (event.pointerId !== this.#pointerId) return;
+      this.#finishPointer(event, this.#moved, { x: 0, y: 0 }, this.#lastPointer);
+    };
+    #finishPointer(event, moved, velocity, pointer = { x: event.clientX, y: event.clientY }) {
+      const pointerId = this.#pointerId;
+      this.#pointerId = void 0;
+      if (pointerId !== void 0) {
+        try {
+          this.#button.releasePointerCapture(pointerId);
+        } catch {
+        }
+      }
+      this.#suppressClick = moved;
+      this.#options.onDragEnd(velocity, moved, pointer);
+    }
+    #repair() {
+      if (this.#destroyed) return;
+      connectRuntimeHost(this.#host, this.#document, "data-peekling-interaction");
+      if (this.#root.host !== this.#host || this.#button.getRootNode() !== this.#root) {
+        throw new Error(
+          runtimeMessage(
+            "interaction.root",
+            "Peekling interaction root structure was changed"
+          )
+        );
+      }
+    }
+  };
+
   // packages/runtime/src/direction.ts
   var OCTANTS = ["E", "SE", "S", "SW", "W", "NW", "N", "NE"];
   function directionTo(from, to) {
@@ -2949,8 +3174,8 @@
   }
 
   // packages/runtime/src/registry.ts
-  var PEEK_REFERENCE_URL = true ? "https://cdn.jsdelivr.net/npm/@peekling/pack-peek@0.1.0/character.json" : "https://cdn.jsdelivr.net/npm/@peekling/pack-peek@0.1.0/character.json";
-  var PEEK_REFERENCE_SHA256 = true ? "bc01840e84f72edca4b0421dca4d07623b38d971d851bfc647e1cada03e1cbcc" : "bc01840e84f72edca4b0421dca4d07623b38d971d851bfc647e1cada03e1cbcc";
+  var PEEK_REFERENCE_URL = true ? "https://cdn.jsdelivr.net/npm/@peekling/pack-peek@0.1.1/character.json" : "https://cdn.jsdelivr.net/npm/@peekling/pack-peek@0.1.1/character.json";
+  var PEEK_REFERENCE_SHA256 = true ? "9a2e2a41e85f7c4b8d3487a3655db40872675bd9c0780e139a946eabdf71d75f" : "9a2e2a41e85f7c4b8d3487a3655db40872675bd9c0780e139a946eabdf71d75f";
   var REGISTRY = {
     peek: Object.freeze({
       url: PEEK_REFERENCE_URL,
@@ -3840,7 +4065,7 @@
       );
     }
     const state = input.state === void 0 ? void 0 : compileState(input.state, `${path}.state`, context);
-    const motion = input.motion === void 0 ? void 0 : compileMotion(input.motion, `${path}.motion`);
+    const motion = input.motion === void 0 ? void 0 : compileMotion(input.motion, `${path}.motion`, context);
     const surfaces = input.surfaces === void 0 ? [] : input.surfaces;
     if (!Array.isArray(surfaces) || surfaces.length > SURFACE_LIMIT) {
       fail(
@@ -4010,19 +4235,81 @@
     }
     return freeze({ kind: "capability", name: input.capability });
   }
-  function compileMotion(input, path) {
+  function compileMotion(input, path, context) {
     object(input, path);
-    closed3(input, ["type", "speed", "arrivalRadius"], path);
-    if (input.type !== "follow-pointer") {
-      fail("invalid-motion", `${path}.type`, "must be follow-pointer");
+    switch (input.type) {
+      case "follow-pointer":
+        closed3(input, ["type", "speed", "arrivalRadius"], path);
+        bounded(input.speed, `${path}.speed`, 1, 1e3);
+        bounded(input.arrivalRadius, `${path}.arrivalRadius`, 0, 1e3);
+        break;
+      case "horizontal-patrol":
+        closed3(input, ["type", "speed", "edgeInset"], path);
+        bounded(input.speed, `${path}.speed`, 1, 1e3);
+        bounded(input.edgeInset, `${path}.edgeInset`, 0, 1e3);
+        break;
+      case "viewport-traverse":
+        closed3(input, ["type", "speed", "edgeInset", "clockwise"], path);
+        bounded(input.speed, `${path}.speed`, 1, 1e3);
+        bounded(input.edgeInset, `${path}.edgeInset`, 0, 1e3);
+        if (input.clockwise !== void 0 && typeof input.clockwise !== "boolean") {
+          fail("invalid-motion", `${path}.clockwise`, "must be boolean");
+        }
+        break;
+      case "move-to":
+        closed3(input, ["type", "x", "y", "speed", "arrivalRadius"], path);
+        bounded(input.x, `${path}.x`, -1e5, 1e5);
+        bounded(input.y, `${path}.y`, -1e5, 1e5);
+        bounded(input.speed, `${path}.speed`, 1, 1e3);
+        bounded(input.arrivalRadius, `${path}.arrivalRadius`, 0, 1e3);
+        break;
+      case "move-to-target":
+        closed3(
+          input,
+          ["type", "target", "anchor", "speed", "arrivalRadius"],
+          path
+        );
+        id(input.target, `${path}.target`, "Target");
+        if (context.targets && !context.targets.has(input.target)) {
+          fail(
+            "unknown-target",
+            `${path}.target`,
+            `references unknown target ${input.target}`
+          );
+        }
+        if (input.anchor !== void 0 && !["center", "top", "right", "bottom", "left"].includes(input.anchor)) {
+          fail("invalid-motion", `${path}.anchor`, "is not supported");
+        }
+        bounded(input.speed, `${path}.speed`, 1, 1e3);
+        bounded(input.arrivalRadius, `${path}.arrivalRadius`, 0, 1e3);
+        break;
+      case "jump-to":
+        closed3(input, ["type", "x", "y", "duration", "height"], path);
+        bounded(input.x, `${path}.x`, -1e5, 1e5);
+        bounded(input.y, `${path}.y`, -1e5, 1e5);
+        bounded(input.duration, `${path}.duration`, 100, 1e4);
+        bounded(input.height, `${path}.height`, 0, 2e3);
+        break;
+      case "svg-path": {
+        closed3(input, ["type", "path", "duration", "loop", "relative"], path);
+        if (typeof input.path !== "string" || input.path.length < 1 || input.path.length > 4096 || /[\0\r\n]/.test(input.path)) {
+          fail("invalid-path", `${path}.path`, "must be bounded SVG path data");
+        }
+        if (context.validatePath && !context.validatePath(input.path)) {
+          fail("invalid-path", `${path}.path`, "must be valid SVG path data");
+        }
+        bounded(input.duration, `${path}.duration`, 100, 6e4);
+        for (const field of ["loop", "relative"]) {
+          if (input[field] !== void 0 && typeof input[field] !== "boolean") {
+            fail("invalid-motion", `${path}.${field}`, "must be boolean");
+          }
+        }
+        break;
+      }
+      default:
+        fail("invalid-motion", `${path}.type`, "is not a supported motion type");
     }
-    bounded(input.speed, `${path}.speed`, 1, 1e3);
-    bounded(input.arrivalRadius, `${path}.arrivalRadius`, 0, 1e3);
-    return freeze({
-      type: "follow-pointer",
-      ...input.speed === void 0 ? {} : { speed: input.speed },
-      ...input.arrivalRadius === void 0 ? {} : { arrivalRadius: input.arrivalRadius }
-    });
+    return freeze({ ...input });
   }
   function compileSurface(input, path, context, allowPayload) {
     object(input, path);
@@ -4363,7 +4650,25 @@
       thresholds: [...thresholds].sort((left, right) => left - right)
     };
   }
-  function createDefaultPlan(locomotion) {
+  function createPresetPlan(preset, locomotion) {
+    const state = locomotion ? { capability: "locomotion" } : { state: "idle" };
+    if (preset === "still") {
+      return {
+        baseline: {
+          channels: ["state"],
+          state: { state: "idle" }
+        }
+      };
+    }
+    if (preset === "bottom-patrol" || preset === "viewport-roam") {
+      return {
+        baseline: {
+          channels: ["motion", "state"],
+          state,
+          motion: preset === "bottom-patrol" ? { type: "horizontal-patrol", speed: DEFAULT_SPEED } : { type: "viewport-traverse", speed: DEFAULT_SPEED }
+        }
+      };
+    }
     return {
       baseline: {
         channels: ["state"],
@@ -4389,6 +4694,12 @@
     #eventState = createPlanEventState();
     #activeChannels = /* @__PURE__ */ new Map();
     #activeSurfaces = /* @__PURE__ */ new Map();
+    #patrolDirections = /* @__PURE__ */ new WeakMap();
+    #traversePhases = /* @__PURE__ */ new WeakMap();
+    #jumpOwner;
+    #jumpState;
+    #pathOwner;
+    #pathState;
     #activeInterrupts = [];
     #surfaceVersion = 0;
     #lastEventStatus;
@@ -4476,24 +4787,81 @@
       if (state?.kind === "capability") {
         output.capability = state.name;
       }
-      const motion = channels.get("motion")?.motion;
-      if (motion && world.pointer) {
-        const dx = world.pointer.x - world.position.x;
-        const dy = world.pointer.y - world.position.y;
-        const distance = Math.hypot(dx, dy);
-        const arrivalRadius = motion.arrivalRadius ?? 0;
-        if (distance > arrivalRadius) {
-          output.motion = {
-            x: dx / distance,
-            y: dy / distance,
-            speed: motion.speed ?? DEFAULT_SPEED,
-            maxDistance: distance - arrivalRadius
-          };
-        } else if (channels.get("motion") === channels.get("state")) {
-          delete output.capability;
-          const baseline = this.#baselineState();
-          if (!output.state && baseline) output.state = baseline;
-        }
+      const motionOwner = channels.get("motion");
+      const motion = motionOwner?.motion;
+      const settleCapability = () => {
+        if (output.capability !== "locomotion") return;
+        delete output.capability;
+        const baseline = this.#baselineState();
+        if (!output.state && baseline) output.state = baseline;
+      };
+      if (motion?.type !== "jump-to") {
+        this.#jumpOwner = void 0;
+        this.#jumpState = void 0;
+      }
+      if (motion?.type !== "svg-path") {
+        this.#pathOwner = void 0;
+        this.#pathState = void 0;
+      }
+      if (motion?.type === "horizontal-patrol" && world.characterSize) {
+        const [direction, request] = evaluateHorizontalPatrol(
+          motion,
+          world,
+          this.#patrolDirections.get(motionOwner) ?? true
+        );
+        this.#patrolDirections.set(motionOwner, direction);
+        if (request) output.motion = request;
+      } else if (motion?.type === "viewport-traverse" && world.characterSize) {
+        const [phase, request] = evaluateViewportTraverse(
+          motion,
+          world,
+          this.#traversePhases.get(motionOwner)
+        );
+        this.#traversePhases.set(motionOwner, phase);
+        if (request) output.motion = request;
+      } else if (motion?.type === "follow-pointer") {
+        const request = world.pointer ? motionToward(
+          motion,
+          world.position,
+          world.pointer.x,
+          world.pointer.y,
+          motion.arrivalRadius,
+          world
+        ) : void 0;
+        if (request) output.motion = request;
+        else settleCapability();
+      } else if (motion?.type === "move-to") {
+        const request = motionToward(
+          motion,
+          world.position,
+          motion.x,
+          motion.y,
+          motion.arrivalRadius,
+          world
+        );
+        if (request) output.motion = request;
+        else settleCapability();
+      } else if (motion?.type === "move-to-target") {
+        const target = world.targets?.[motion.target];
+        const point = target && world.characterSize ? targetPoint(target, motion.anchor, world.characterSize) : void 0;
+        const request = point ? motionToward(
+          motion,
+          world.position,
+          point.x,
+          point.y,
+          motion.arrivalRadius,
+          world
+        ) : void 0;
+        if (request) output.motion = { ...request, trackTarget: true };
+        else settleCapability();
+      } else if (motion?.type === "jump-to") {
+        const request = this.#evaluateJump(motionOwner, motion, world);
+        if (request) output.motion = request;
+        else settleCapability();
+      } else if (motion?.type === "svg-path") {
+        const request = this.#evaluatePath(motionOwner, motion, world);
+        if (request) output.motion = request;
+        else settleCapability();
       }
       const selected = /* @__PURE__ */ new Map();
       for (const surface of this.#plan.baseline.surfaces) {
@@ -4532,6 +4900,12 @@
       this.#activeChannels.clear();
       this.#activeSurfaces.clear();
       this.#activeInterrupts = [];
+      this.#patrolDirections = /* @__PURE__ */ new WeakMap();
+      this.#traversePhases = /* @__PURE__ */ new WeakMap();
+      this.#jumpOwner = void 0;
+      this.#jumpState = void 0;
+      this.#pathOwner = void 0;
+      this.#pathState = void 0;
       this.#eventState.ordering.clear();
       this.#eventState.sessions.clear();
       this.#lastEventStatus = void 0;
@@ -4557,17 +4931,75 @@
       const state = this.#plan.baseline.state;
       return state?.kind === "state" ? state.name : void 0;
     }
+    #evaluateJump(owner, effect, world) {
+      if (this.#jumpOwner !== owner || !this.#jumpState) {
+        this.#jumpOwner = owner;
+        this.#jumpState = {
+          startedAt: world.now,
+          from: { ...world.position }
+        };
+      }
+      const duration = effect.duration ?? 800;
+      const progress = Math.max(
+        0,
+        Math.min(1, (world.now - this.#jumpState.startedAt) / duration)
+      );
+      const target = boundedPoint(effect, world);
+      const desired = {
+        x: this.#jumpState.from.x + (target.x - this.#jumpState.from.x) * progress,
+        y: this.#jumpState.from.y + (target.y - this.#jumpState.from.y) * progress
+      };
+      const lift = progress === 0 || progress === 1 ? 0 : Math.sin(Math.PI * progress) * (effect.height ?? world.characterSize?.height ?? 32);
+      const request = directMotion(world.position, desired, lift);
+      if (progress < 1 || request.maxDistance) return request;
+      return;
+    }
+    #evaluatePath(owner, effect, world) {
+      const sample = world.samplePath;
+      if (!sample) return;
+      const first = sample(effect.path, 0);
+      if (!first) return;
+      if (this.#pathOwner !== owner || !this.#pathState) {
+        this.#pathOwner = owner;
+        this.#pathState = {
+          startedAt: world.now,
+          offset: effect.relative === false ? { x: 0, y: 0 } : {
+            x: world.position.x - first.x,
+            y: world.position.y - first.y
+          }
+        };
+      }
+      const duration = effect.duration ?? 4e3;
+      const elapsed = Math.max(0, world.now - this.#pathState.startedAt);
+      const complete = effect.loop !== true && elapsed >= duration;
+      const progress = effect.loop ? elapsed % duration / duration : Math.min(1, elapsed / duration);
+      const point = sample(effect.path, progress);
+      if (!point) return;
+      const desired = {
+        x: point.x + this.#pathState.offset.x,
+        y: point.y + this.#pathState.offset.y
+      };
+      const request = directMotion(world.position, boundedPoint(desired, world));
+      if (!complete || request.maxDistance) return request;
+      return;
+    }
     #isContinuous(rule, world) {
       const condition = rule.when;
       if (condition.source !== "browser") return false;
       if (condition.event === "pointer.move") {
         if (!world.pointer) return false;
         const motion = rule.effect.motion;
-        if (!motion) return true;
-        return Math.hypot(
-          world.pointer.x - world.position.x,
-          world.pointer.y - world.position.y
-        ) > (motion.arrivalRadius ?? 0);
+        if (!motion || motion.type !== "follow-pointer") return true;
+        return Boolean(
+          motionToward(
+            motion,
+            world.position,
+            world.pointer.x,
+            world.pointer.y,
+            motion.arrivalRadius,
+            world
+          )
+        );
       }
       if (condition.event !== "section.visibility") return false;
       const section = world.sections?.[condition.selector];
@@ -4610,6 +5042,128 @@
   function completionSource(name) {
     return browserCompletionEvent(name) ? "browser" : "application";
   }
+  function evaluateHorizontalPatrol(effect, world, direction) {
+    const halfWidth = world.characterSize.width / 2;
+    const inset = effect.edgeInset ?? 0;
+    const left = Math.min(world.viewport.width / 2, halfWidth + inset);
+    const right = world.viewport.width - left;
+    const halfHeight = world.characterSize.height / 2;
+    const y = Math.max(halfHeight, world.viewport.height - halfHeight);
+    let request = motionToward(
+      effect,
+      world.position,
+      direction ? right : left,
+      y
+    );
+    if (!request) {
+      direction = !direction;
+      request = motionToward(effect, world.position, direction ? right : left, y);
+    }
+    return [direction, request];
+  }
+  function evaluateViewportTraverse(effect, world, phase) {
+    const inset = effect.edgeInset ?? 0;
+    const halfWidth = world.characterSize.width / 2;
+    const halfHeight = world.characterSize.height / 2;
+    const left = Math.min(world.viewport.width / 2, halfWidth + inset);
+    const right = Math.max(left, world.viewport.width - left);
+    const top = Math.min(world.viewport.height / 2, halfHeight + inset);
+    const bottom = Math.max(top, world.viewport.height - halfHeight - inset);
+    const points = [
+      { x: left, y: bottom },
+      { x: right, y: bottom },
+      { x: right, y: top },
+      { x: left, y: top }
+    ];
+    if (phase === void 0) {
+      phase = points.reduce(
+        (nearest, point, index) => Math.hypot(point.x - world.position.x, point.y - world.position.y) < Math.hypot(
+          points[nearest].x - world.position.x,
+          points[nearest].y - world.position.y
+        ) ? index : nearest,
+        0
+      );
+    }
+    let target = points[phase];
+    let request = motionToward(effect, world.position, target.x, target.y);
+    if (!request) {
+      const direction = effect.clockwise === false ? -1 : 1;
+      phase = (phase + direction + points.length) % points.length;
+      target = points[phase];
+      request = motionToward(effect, world.position, target.x, target.y);
+    }
+    return [phase, request];
+  }
+  function targetPoint(target, anchor = "center", character) {
+    const center = {
+      x: target.left + target.width / 2,
+      y: target.top + target.height / 2
+    };
+    switch (anchor) {
+      case "top":
+        return { x: center.x, y: target.top - character.height / 2 };
+      case "right":
+        return { x: target.right + character.width / 2, y: center.y };
+      case "bottom":
+        return { x: center.x, y: target.bottom + character.height / 2 };
+      case "left":
+        return { x: target.left - character.width / 2, y: center.y };
+      default:
+        return center;
+    }
+  }
+  function boundedPoint(point, world) {
+    const size = world.characterSize;
+    if (!size) return { x: point.x, y: point.y };
+    return {
+      x: Math.max(
+        size.width / 2,
+        Math.min(world.viewport.width - size.width / 2, point.x)
+      ),
+      y: Math.max(
+        size.height / 2,
+        Math.min(world.viewport.height - size.height / 2, point.y)
+      )
+    };
+  }
+  function directMotion(position, target, lift = 0) {
+    const dx = target.x - position.x;
+    const dy = target.y - position.y;
+    const distance = Math.hypot(dx, dy);
+    return {
+      x: distance ? dx / distance : 0,
+      y: distance ? dy / distance : 0,
+      speed: 0,
+      maxDistance: distance,
+      lift,
+      direct: true
+    };
+  }
+  function motionToward(effect, position, x, y, arrivalRadius = 0, bounds) {
+    const size = bounds?.characterSize;
+    const viewport = bounds?.viewport;
+    if (size && viewport) {
+      const pointerX = x;
+      const pointerY = y;
+      x = Math.max(size.width / 2, Math.min(viewport.width - size.width / 2, x));
+      y = Math.max(
+        size.height / 2,
+        Math.min(viewport.height - size.height / 2, y)
+      );
+      if (x !== pointerX || y !== pointerY) arrivalRadius = 0;
+    }
+    const dx = x - position.x;
+    const dy = y - position.y;
+    const distance = Math.hypot(dx, dy);
+    const maxDistance = distance - arrivalRadius;
+    if (maxDistance <= 4) return;
+    return {
+      x: dx / distance,
+      y: dy / distance,
+      speed: effect.speed ?? DEFAULT_SPEED,
+      maxDistance
+    };
+  }
 
   // packages/runtime/src/configuration-validation.ts
   var collectConfigurationFaults = !compactRuntimeDiagnostics;
@@ -4621,6 +5175,10 @@
     "atlasUrl",
     "styles",
     "plan",
+    "preset",
+    "targets",
+    "interaction",
+    "indicator",
     "content",
     "bindings",
     "theme",
@@ -4652,6 +5210,14 @@
     if (options.format !== void 0 && options.format !== 1) {
       reportConfigurationFault("unsupported-format", "$.format", fault);
     }
+    if (options.plan !== void 0 && options.preset !== void 0) {
+      reportConfigurationFault("incompatible-behavior", "$.preset", fault);
+    }
+    if (options.preset !== void 0 && !["companion", "still", "bottom-patrol", "viewport-roam"].includes(
+      options.preset
+    )) {
+      reportConfigurationFault("invalid-preset", "$.preset", fault);
+    }
     if (options.character !== void 0) {
       if (typeof options.character !== "string" || !NAME_PATTERN.test(options.character)) {
         reportConfigurationFault("invalid-character", "$.character", fault);
@@ -4737,6 +5303,12 @@
       if (collectConfigurationFaults) content = {};
     }
     validateBindings(options.bindings, content, fault);
+    validateTargets(options.targets, fault);
+    validateInteraction(options.interaction, options.targets, fault);
+    validateIndicator(options.indicator, fault);
+    if (options.interaction === false && options.indicator !== void 0) {
+      reportConfigurationFault("incompatible-indicator", "$.indicator", fault);
+    }
     validateTheme(options.theme, fault);
     validateDiagnostics(options.diagnostics, fault);
     validateAccessibility(options.accessibility, fault);
@@ -4747,6 +5319,201 @@
     }
     return content;
   }
+  function validateInteraction(interaction, targets, fault) {
+    if (interaction === void 0 || interaction === false) return;
+    const checked = shape(
+      interaction,
+      "invalid-interaction",
+      "$.interaction",
+      [
+        "press",
+        "pressEvent",
+        "drag",
+        "throw",
+        "dragState",
+        "riseState",
+        "fallState",
+        "landState",
+        "gravity",
+        "maxThrowSpeed",
+        "bounce",
+        "floorInset",
+        "label",
+        "contentInitiallyHidden",
+        "clearIndicatorOnPress",
+        "catchTarget",
+        "catchAnchor",
+        "catchMargin",
+        "catchEvent"
+      ],
+      fault
+    );
+    if (collectConfigurationFaults && !checked) return;
+    const value = checked;
+    if (value.press !== void 0 && ![
+      "toggle-content",
+      "show-content",
+      "hide-content",
+      "emit",
+      "none"
+    ].includes(value.press)) {
+      reportConfigurationFault(
+        "invalid-interaction",
+        "$.interaction.press",
+        fault
+      );
+    }
+    if (value.pressEvent !== void 0 && (typeof value.pressEvent !== "string" || !EVENT_NAME_PATTERN.test(value.pressEvent))) {
+      reportConfigurationFault(
+        "invalid-interaction-event",
+        "$.interaction.pressEvent",
+        fault
+      );
+    }
+    if (value.press === "emit" && value.pressEvent === void 0) {
+      reportConfigurationFault(
+        "missing-interaction-event",
+        "$.interaction.pressEvent",
+        fault
+      );
+    }
+    if (value.pressEvent !== void 0 && value.press !== void 0 && value.press !== "emit") {
+      reportConfigurationFault(
+        "incompatible-interaction-event",
+        "$.interaction.pressEvent",
+        fault
+      );
+    }
+    for (const field of [
+      "drag",
+      "throw",
+      "contentInitiallyHidden",
+      "clearIndicatorOnPress"
+    ]) {
+      if (value[field] !== void 0 && typeof value[field] !== "boolean") {
+        reportConfigurationFault(
+          "invalid-interaction",
+          `$.interaction.${field}`,
+          fault
+        );
+      }
+    }
+    for (const field of [
+      "dragState",
+      "riseState",
+      "fallState",
+      "landState"
+    ]) {
+      if (value[field] !== void 0 && (typeof value[field] !== "string" || !STATE_NAME_PATTERN.test(value[field]))) {
+        reportConfigurationFault(
+          "invalid-interaction-state",
+          `$.interaction.${field}`,
+          fault
+        );
+      }
+    }
+    for (const [field, minimum, maximum] of [
+      ["gravity", 0, 1e4],
+      ["maxThrowSpeed", 0, 1e4],
+      ["bounce", 0, 1],
+      ["floorInset", 0, 1e3],
+      ["catchMargin", 0, 1e3]
+    ]) {
+      const item = value[field];
+      if (item !== void 0 && (typeof item !== "number" || !Number.isFinite(item) || item < minimum || item > maximum)) {
+        reportConfigurationFault(
+          "invalid-interaction-range",
+          `$.interaction.${field}`,
+          fault
+        );
+      }
+    }
+    if (value.label !== void 0 && !text2(value.label, 120)) {
+      reportConfigurationFault(
+        "invalid-interaction-label",
+        "$.interaction.label",
+        fault
+      );
+    }
+    if (value.catchTarget !== void 0 && (typeof value.catchTarget !== "string" || !NAME_PATTERN.test(value.catchTarget) || !Object.hasOwn(targets ?? {}, value.catchTarget))) {
+      reportConfigurationFault(
+        "invalid-catch-target",
+        "$.interaction.catchTarget",
+        fault
+      );
+    }
+    if (value.catchAnchor !== void 0 && !["center", "top", "right", "bottom", "left"].includes(
+      value.catchAnchor
+    )) {
+      reportConfigurationFault(
+        "invalid-catch-anchor",
+        "$.interaction.catchAnchor",
+        fault
+      );
+    }
+    if (value.catchEvent !== void 0 && (typeof value.catchEvent !== "string" || !EVENT_NAME_PATTERN.test(value.catchEvent))) {
+      reportConfigurationFault(
+        "invalid-interaction-event",
+        "$.interaction.catchEvent",
+        fault
+      );
+    }
+  }
+  function validateIndicator(indicator, fault) {
+    if (indicator === void 0) return;
+    const checked = shape(
+      indicator,
+      "invalid-indicator",
+      "$.indicator",
+      ["kind", "count", "label", "color", "visible"],
+      fault
+    );
+    if (collectConfigurationFaults && !checked) return;
+    const value = checked;
+    if (value.kind !== void 0 && value.kind !== "dot" && value.kind !== "count") {
+      reportConfigurationFault("invalid-indicator", "$.indicator.kind", fault);
+    }
+    if (!text2(value.label, 120)) {
+      reportConfigurationFault("invalid-indicator", "$.indicator.label", fault);
+    }
+    if (value.count !== void 0 && (typeof value.count !== "number" || !Number.isInteger(value.count) || value.count < 0 || value.count > 999)) {
+      reportConfigurationFault("invalid-indicator", "$.indicator.count", fault);
+    }
+    if (value.color !== void 0 && !isSurfaceColor(value.color)) {
+      reportConfigurationFault("invalid-indicator", "$.indicator.color", fault);
+    }
+    if (value.visible !== void 0 && typeof value.visible !== "boolean") {
+      reportConfigurationFault("invalid-indicator", "$.indicator.visible", fault);
+    }
+  }
+  function validateTargets(targets, fault) {
+    if (targets === void 0) return;
+    const checked = shape(
+      targets,
+      "invalid-targets",
+      "$.targets",
+      void 0,
+      fault
+    );
+    if (collectConfigurationFaults && !checked) return;
+    const entries = Object.entries(checked);
+    if (entries.length > 16) {
+      reportConfigurationFault("target-limit", "$.targets", fault);
+    }
+    for (const [id2, selector2] of entries) {
+      if (!NAME_PATTERN.test(id2)) {
+        reportConfigurationFault("invalid-target", `$.targets.${id2}`, fault, id2);
+      }
+      if (typeof selector2 !== "string" || selector2.length < 1 || selector2.length > 256 || /[\0\r\n]/.test(selector2)) {
+        reportConfigurationFault(
+          "invalid-target-selector",
+          `$.targets.${id2}`,
+          fault,
+          id2
+        );
+      }
+    }
+  }
   function validRuntimeName(value) {
     return value === void 0 || typeof value === "boolean" || text2(value, 80);
   }
@@ -4975,7 +5742,8 @@
     if (options.plan !== void 0) {
       try {
         compilePlan(options.plan, {
-          contentIds: new Set(Object.keys(content))
+          contentIds: new Set(Object.keys(content)),
+          targets: new Set(Object.keys(options.targets ?? {}))
         });
       } catch (cause) {
         fail2(
@@ -5056,6 +5824,40 @@
         return `${detail ?? field} must be a function`;
       case "invalid-plan":
         return detail ?? "Plan is invalid";
+      case "incompatible-behavior":
+        return "Choose preset or plan, not both";
+      case "invalid-preset":
+        return "preset must be companion, still, bottom-patrol, or viewport-roam";
+      case "invalid-targets":
+        return "targets must be an object of target IDs and CSS selectors";
+      case "target-limit":
+        return "targets supports at most 16 entries";
+      case "invalid-target":
+        return "target IDs must be bounded lowercase IDs";
+      case "invalid-target-selector":
+        return "target selectors must be bounded CSS selector text";
+      case "invalid-interaction":
+        return "interaction contains an unsupported value";
+      case "invalid-interaction-event":
+        return "interaction events must be bounded application Event names";
+      case "missing-interaction-event":
+        return "pressEvent is required when press is emit";
+      case "incompatible-interaction-event":
+        return "pressEvent can be used only with the emit press action";
+      case "invalid-interaction-state":
+        return "interaction states must be valid Pack State names";
+      case "invalid-interaction-range":
+        return "interaction physics value is outside its supported range";
+      case "invalid-interaction-label":
+        return "interaction label must be short plain text";
+      case "invalid-catch-target":
+        return "catchTarget must reference a configured target";
+      case "invalid-catch-anchor":
+        return "catchAnchor is not supported";
+      case "invalid-indicator":
+        return "indicator must include a label and valid dot or count settings";
+      case "incompatible-indicator":
+        return "indicator requires character interaction";
       default:
         return detail ?? code;
     }
@@ -5168,21 +5970,26 @@
           delete output.state;
         }
         const motion = item.effect.motion;
-        if (motion && world.pointer && world.position) {
-          const dx = world.pointer.x - world.position.x;
-          const dy = world.pointer.y - world.position.y;
-          const distance = Math.hypot(dx, dy);
-          const arrivalRadius = motion.arrivalRadius ?? 0;
-          if (distance > arrivalRadius) {
-            output.motion = {
-              x: dx / distance,
-              y: dy / distance,
-              speed: motion.speed ?? DEFAULT_SPEED,
-              maxDistance: distance - arrivalRadius
-            };
-          } else {
-            delete output.motion;
-          }
+        if (motion?.type === "horizontal-patrol") {
+          const [direction, request] = evaluateHorizontalPatrol(
+            motion,
+            world,
+            item.patrolDirection
+          );
+          item.patrolDirection = direction;
+          if (request) output.motion = request;
+          else delete output.motion;
+        } else if (motion?.type === "follow-pointer" && world.pointer && world.position) {
+          const request = motionToward(
+            motion,
+            world.position,
+            world.pointer.x,
+            world.pointer.y,
+            motion.arrivalRadius,
+            world
+          );
+          if (request) output.motion = request;
+          else delete output.motion;
         }
         for (const surface of item.effect.surfaces) {
           surfaces.set(
@@ -5249,6 +6056,7 @@
         startedAt: 0,
         deadline: 0,
         status: "rejected",
+        patrolDirection: true,
         handle,
         finish
       });
@@ -5556,6 +6364,13 @@
         this.host.setAttribute("aria-hidden", "true");
     }
   };
+  var createAtlasRenderer = (options) => new AtlasRenderer(
+    options.document,
+    options.pack,
+    options.atlasUrl,
+    options.scale,
+    options.styles
+  );
 
   // packages/runtime/src/resolver.ts
   var ALIASES = {
@@ -5799,6 +6614,142 @@
     }
   }
 
+  // packages/runtime/src/path-sampler.ts
+  var SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+  var SvgPathSampler = class {
+    #document;
+    #cache = /* @__PURE__ */ new Map();
+    constructor(document) {
+      this.#document = document;
+    }
+    validate(path) {
+      return this.#geometry(path) !== void 0;
+    }
+    sample(path, progress) {
+      const geometry = this.#geometry(path);
+      if (!geometry) return;
+      const bounded2 = Math.max(0, Math.min(1, progress));
+      try {
+        const point = geometry.element.getPointAtLength(
+          geometry.length * bounded2
+        );
+        if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return;
+        return { x: point.x, y: point.y };
+      } catch {
+        return;
+      }
+    }
+    #geometry(path) {
+      const cached = this.#cache.get(path);
+      if (cached) return cached;
+      if (this.#cache.size >= 16) return;
+      const element = this.#document.createElementNS(
+        SVG_NAMESPACE,
+        "path"
+      );
+      element.setAttribute("d", path);
+      try {
+        const length = element.getTotalLength();
+        if (!Number.isFinite(length) || length <= 0) return;
+        const geometry = Object.freeze({ element, length });
+        this.#cache.set(path, geometry);
+        return geometry;
+      } catch {
+        return;
+      }
+    }
+  };
+
+  // packages/runtime/src/targets.ts
+  var TargetTracker = class {
+    #document;
+    #window;
+    #selectors;
+    #elements = /* @__PURE__ */ new Map();
+    #wake;
+    #resizeObserver;
+    #mutationObserver;
+    #snapshot = Object.freeze({});
+    #dirty = true;
+    #destroyed = false;
+    constructor(document, window, selectors, wake) {
+      this.#document = document;
+      this.#window = window;
+      this.#selectors = selectors;
+      this.#wake = wake;
+      const browserWindow = window;
+      this.#resizeObserver = browserWindow.ResizeObserver ? new browserWindow.ResizeObserver(() => this.refresh()) : void 0;
+      this.#mutationObserver = browserWindow.MutationObserver ? new browserWindow.MutationObserver(() => this.refresh()) : void 0;
+      this.#mutationObserver?.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ["class", "id"],
+        childList: true,
+        subtree: true
+      });
+      window.addEventListener("resize", this.#markDirty, { passive: true });
+      window.addEventListener("scroll", this.#markDirty, {
+        capture: true,
+        passive: true
+      });
+    }
+    snapshot(force = false) {
+      if (this.#destroyed) return Object.freeze({});
+      if (force) this.#dirty = true;
+      if (!this.#dirty) return this.#snapshot;
+      const output = /* @__PURE__ */ Object.create(null);
+      for (const [id2, selector2] of Object.entries(this.#selectors)) {
+        let element = this.#elements.get(id2);
+        if (!element?.isConnected) {
+          if (element) this.#resizeObserver?.unobserve(element);
+          element = this.#document.querySelector(selector2);
+          if (element) {
+            this.#elements.set(id2, element);
+            this.#resizeObserver?.observe(element);
+          } else {
+            this.#elements.delete(id2);
+          }
+        }
+        if (!element) continue;
+        const rect = element.getBoundingClientRect();
+        if (!Number.isFinite(rect.left) || !Number.isFinite(rect.top) || !Number.isFinite(rect.width) || !Number.isFinite(rect.height)) {
+          continue;
+        }
+        output[id2] = Object.freeze({
+          left: rect.left,
+          top: rect.top,
+          right: rect.right,
+          bottom: rect.bottom,
+          width: rect.width,
+          height: rect.height
+        });
+      }
+      this.#snapshot = Object.freeze(output);
+      this.#dirty = false;
+      return this.#snapshot;
+    }
+    contains(id2, point, margin = 0) {
+      const target = this.snapshot(true)[id2];
+      return Boolean(
+        target && point.x >= target.left - margin && point.x <= target.right + margin && point.y >= target.top - margin && point.y <= target.bottom + margin
+      );
+    }
+    refresh = () => {
+      if (this.#destroyed) return;
+      this.#dirty = true;
+      this.#wake();
+    };
+    destroy() {
+      if (this.#destroyed) return;
+      this.#destroyed = true;
+      this.#resizeObserver?.disconnect();
+      this.#mutationObserver?.disconnect();
+      this.#window.removeEventListener("resize", this.#markDirty);
+      this.#window.removeEventListener("scroll", this.#markDirty, true);
+      this.#elements.clear();
+    }
+    #markDirty = () => this.refresh();
+  };
+
   // packages/runtime/src/visibility.ts
   var PREFERENCE_KEY = "peekling:site-preference";
   var SESSION_KEY = "peekling:hidden-session";
@@ -6157,6 +7108,10 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
   var SUSPEND_PAGE = 2;
   var SUSPEND_SITE = 4;
   var MAX_TIMER_DELAY = 2147483647;
+  var DEFAULT_GRAVITY = 1800;
+  var DEFAULT_THROW_SPEED = 1800;
+  var DEFAULT_BOUNCE = 0.35;
+  var DEFAULT_FLOOR_INSET = 8;
   var EMPTY_CONTENT_SELECTIONS = Object.freeze([]);
   function browserSelectorIsValid(document, selector2) {
     try {
@@ -6220,10 +7175,21 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
     }
     return input;
   }
+  function checkedIndicator(input) {
+    if (input === null) return;
+    const value = snapshotConfiguration(input);
+    if (!value || typeof value !== "object" || Array.isArray(value) || value.kind !== void 0 && value.kind !== "dot" && value.kind !== "count" || typeof value.label !== "string" || value.label.length < 1 || value.label.length > 120 || /[\u0000-\u001f\u007f]/.test(value.label) || value.count !== void 0 && (!Number.isInteger(value.count) || value.count < 0 || value.count > 999) || value.color !== void 0 && !isSurfaceColor(value.color) || value.visible !== void 0 && typeof value.visible !== "boolean") {
+      throw new TypeError(
+        runtimeMessage("indicator.invalid", "Indicator is invalid")
+      );
+    }
+    return value;
+  }
   var PeeklingRuntime = class _PeeklingRuntime {
-    static hatch(input) {
+    static hatch(input, rendererFactory = createAtlasRenderer) {
       return new _PeeklingRuntime(
-        hatchOptions(input)
+        hatchOptions(input),
+        rendererFactory
       );
     }
     /** Package-internal presentation update used only by the Web Component. */
@@ -6259,7 +7225,9 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
     #loaded;
     #renderer;
     #contentRenderer;
+    #interactionController;
     #sections;
+    #targets;
     #input;
     #raf = 0;
     #planTimer = 0;
@@ -6295,10 +7263,18 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
     #instanceId;
     #diagnostics;
     #styles;
+    #rendererFactory;
     #rejectedOverrideId = 0;
     #reportedNotReadyEvent = false;
     #reportedNotReadyOverride = false;
-    constructor(options = {}) {
+    #trackTargets = false;
+    #pathSampler;
+    #indicator;
+    #dragging = false;
+    #throwing = false;
+    #throwVelocity = { x: 0, y: 0 };
+    #landUntil = 0;
+    constructor(options = {}, rendererFactory = createAtlasRenderer) {
       options = snapshotConfiguration(options);
       const document = options.document ?? globalThis.document;
       const window = options.window ?? globalThis.window;
@@ -6308,7 +7284,10 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
         );
       this.#document = document;
       this.#window = window;
+      this.#pathSampler = new SvgPathSampler(document);
       this.#options = options;
+      this.#indicator = options.indicator;
+      this.#rendererFactory = rendererFactory;
       this.#now = window.performance?.now?.bind(window.performance) ?? Date.now;
       this.#instanceId = `instance:${Math.floor(this.#now())}:${Math.random().toString(36).slice(2, 8)}`;
       this.#diagnostics = new DiagnosticChannel({
@@ -6433,6 +7412,28 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
       this.#setSuspended(SUSPEND_HOST, false);
       this.#notice("lifecycle.resumed", "info", "lifecycle");
     }
+    refreshTargets() {
+      this.#targets?.refresh();
+    }
+    setIndicator(indicator) {
+      if (this.#destroyed) return;
+      this.#indicator = checkedIndicator(indicator);
+      this.#interactionController?.updateIndicator(this.#indicator);
+    }
+    setContentVisible(visible) {
+      if (this.#destroyed || !this.#contentRenderer) return false;
+      const expanded = this.#contentRenderer.setUserHidden(!visible);
+      this.#interactionController?.setExpanded(expanded);
+      this.#wake();
+      return expanded;
+    }
+    toggleContent() {
+      if (this.#destroyed || !this.#contentRenderer) return false;
+      const expanded = this.#contentRenderer.toggleUserHidden();
+      this.#interactionController?.setExpanded(expanded);
+      this.#wake();
+      return expanded;
+    }
     destroy() {
       this.#destroy("destroyed");
     }
@@ -6446,7 +7447,9 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
       this.#input?.destroy();
       this.#plan?.reset();
       this.#sections?.destroy();
+      this.#targets?.destroy();
       this.#contentRenderer?.destroy();
+      this.#interactionController?.destroy();
       this.#renderer?.destroy();
       this.#unregisterVisibility?.();
       this.#unregisterVisibility = void 0;
@@ -6476,10 +7479,20 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
     async #initialize() {
       try {
         const validateSelector = (selector2) => browserSelectorIsValid(this.#document, selector2);
+        const targetIds = new Set(Object.keys(this.#options.targets ?? {}));
+        for (const selector2 of Object.values(this.#options.targets ?? {})) {
+          if (!validateSelector(selector2)) {
+            throw new TypeError(
+              runtimeMessage("target.selector", "Target selector is invalid")
+            );
+          }
+        }
         if (this.#options.plan !== void 0) {
           compilePlan(this.#options.plan, {
             contentIds: new Set(Object.keys(this.#content)),
-            validateSelector
+            targets: targetIds,
+            validateSelector,
+            validatePath: (path) => this.#pathSampler.validate(path)
           });
         }
         const browserWindow = this.#window;
@@ -6547,12 +7560,14 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
           locomotion ? ["locomotion"] : []
         );
         const compiled = compilePlan(
-          this.#options.plan ?? createDefaultPlan(locomotion),
+          this.#options.plan ?? createPresetPlan(this.#options.preset ?? "companion", locomotion),
           {
             states: new Set(Object.keys(loaded.content.states)),
             capabilities,
             contentIds: new Set(Object.keys(this.#content)),
-            validateSelector
+            targets: targetIds,
+            validateSelector,
+            validatePath: (path) => this.#pathSampler.validate(path)
           }
         );
         this.#plan = new PlanRuntime(compiled);
@@ -6560,7 +7575,9 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
           {
             states: new Set(Object.keys(loaded.content.states)),
             capabilities,
-            contentIds: new Set(Object.keys(this.#content))
+            contentIds: new Set(Object.keys(this.#content)),
+            targets: targetIds,
+            validatePath: (path) => this.#pathSampler.validate(path)
           },
           this.#now,
           (message) => this.#diagnose(message, "override.rejected", "warning", "override")
@@ -6588,21 +7605,45 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
           (loaded.content.atlas.logicalWidth ?? loaded.content.atlas.cellWidth) * scale,
           (loaded.content.atlas.logicalHeight ?? loaded.content.atlas.cellHeight) * scale
         );
-        this.#renderer = new AtlasRenderer(
-          this.#document,
-          loaded.content,
-          loaded.atlasObjectUrl,
+        this.#renderer = this.#rendererFactory({
+          document: this.#document,
+          pack: loaded.content,
+          atlasUrl: loaded.atlasObjectUrl,
           scale,
-          this.#styles
-        );
+          styles: this.#styles
+        });
         if (Object.keys(this.#content).length || this.#displayName !== void 0) {
           this.#ensureContentRenderer();
         }
+        if (this.#options.interaction !== false) {
+          const interaction = this.#options.interaction ?? {};
+          const pressAction = interaction.press ?? (interaction.pressEvent ? "emit" : "toggle-content");
+          const controlsContent = Boolean(this.#contentRenderer) && (pressAction === "toggle-content" || pressAction === "show-content" || pressAction === "hide-content");
+          if (interaction.contentInitiallyHidden) {
+            this.#contentRenderer?.setUserHidden(true);
+          }
+          this.#interactionController = new CharacterInteractionController({
+            document: this.#document,
+            styles: this.#styles,
+            label: interaction.label ?? `Interact with ${loaded.content.displayName || "Peekling"}`,
+            draggable: interaction.drag !== false,
+            ...controlsContent ? { expanded: !interaction.contentInitiallyHidden } : {},
+            ...this.#indicator ? { indicator: this.#indicator } : {},
+            onPress: () => this.#handleCharacterPress(),
+            onDragStart: () => this.#startCharacterDrag(),
+            onDragMove: (position, velocity) => this.#moveCharacterDrag(position, velocity),
+            onDragEnd: (velocity, moved, pointer) => this.#endCharacterDrag(velocity, moved, pointer)
+          });
+          if (interaction.contentInitiallyHidden) {
+            this.#interactionController.setExpanded(false);
+          }
+        }
         try {
           await Promise.all([
             this.#visibilityReady,
             this.#renderer.ready,
-            this.#contentRenderer?.ready
+            this.#contentRenderer?.ready,
+            this.#interactionController?.ready
           ]);
         } catch (cause) {
           this.#diagnoseStyleFailure(cause);
@@ -6610,6 +7651,14 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
         }
         const requirements = compiledPlanSectionRequirements(compiled);
         this.#createInput();
+        if (targetIds.size) {
+          this.#targets = new TargetTracker(
+            this.#document,
+            this.#window,
+            this.#options.targets,
+            () => this.#wake()
+          );
+        }
         if (requirements.selectors.length) {
           this.#sections = new SectionTracker(
             this.#document,
@@ -6621,6 +7670,7 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
           );
         }
         this.#renderer.setHidden(this.#siteHidden);
+        this.#interactionController?.setHidden(this.#siteHidden);
         if (this.#suspensions) {
           this.#input?.setSuspended(true);
           this.#sections?.setSuspended(true);
@@ -6684,6 +7734,129 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
       });
       return this.#contentRenderer;
     }
+    #handleCharacterPress() {
+      if (this.#destroyed) return;
+      const interaction = this.#options.interaction || {};
+      if (interaction.clearIndicatorOnPress === true && this.#indicator) {
+        this.setIndicator(null);
+      }
+      const action = interaction.press ?? (interaction.pressEvent ? "emit" : "toggle-content");
+      if (action === "emit") {
+        if (interaction.pressEvent) this.emit(interaction.pressEvent);
+        return;
+      }
+      if (action === "none") return;
+      if (action === "show-content") this.setContentVisible(true);
+      else if (action === "hide-content") this.setContentVisible(false);
+      else this.toggleContent();
+    }
+    #startCharacterDrag() {
+      if (this.#destroyed || this.#siteHidden) return;
+      this.#dragging = true;
+      this.#throwing = false;
+      this.#landUntil = 0;
+      this.#throwVelocity = { x: 0, y: 0 };
+      this.#wake();
+    }
+    #moveCharacterDrag(position, velocity) {
+      if (!this.#dragging || this.#destroyed) return;
+      const size = this.#characterSize();
+      this.#position = size ? clampPosition(
+        position,
+        { width: this.#window.innerWidth, height: this.#window.innerHeight },
+        size.width,
+        size.height
+      ) : { ...position };
+      this.#throwVelocity = { ...velocity };
+      this.#wake();
+    }
+    #endCharacterDrag(velocity, moved, pointer) {
+      if (!this.#dragging || this.#destroyed) return;
+      this.#dragging = false;
+      if (!moved) {
+        this.#throwVelocity = { x: 0, y: 0 };
+        this.#wake();
+        return;
+      }
+      const interaction = this.#options.interaction || {};
+      if (interaction.catchTarget && this.#targets?.contains(
+        interaction.catchTarget,
+        pointer,
+        interaction.catchMargin ?? 24
+      ) && this.#catchCharacter(interaction.catchTarget)) {
+        return;
+      }
+      if (this.#reducedMotion) {
+        this.#landCharacter();
+        return;
+      }
+      if (interaction.throw === false) {
+        this.#throwVelocity = { x: 0, y: 0 };
+        this.#wake();
+        return;
+      }
+      const maximum = interaction.maxThrowSpeed ?? DEFAULT_THROW_SPEED;
+      const magnitude = Math.hypot(velocity.x, velocity.y);
+      const factor = magnitude > maximum && magnitude ? maximum / magnitude : 1;
+      this.#throwVelocity = {
+        x: velocity.x * factor,
+        y: velocity.y * factor
+      };
+      this.#throwing = true;
+      this.#wake();
+    }
+    #characterSize() {
+      const loaded = this.#loaded?.content;
+      if (!loaded) return;
+      const scale = this.#options.scale ?? loaded.defaultScale;
+      return {
+        width: (loaded.atlas.logicalWidth ?? loaded.atlas.cellWidth) * scale,
+        height: (loaded.atlas.logicalHeight ?? loaded.atlas.cellHeight) * scale
+      };
+    }
+    #landCharacter() {
+      const size = this.#characterSize();
+      if (size) {
+        const floorInset = (this.#options.interaction || {}).floorInset ?? DEFAULT_FLOOR_INSET;
+        this.#position = clampPosition(
+          {
+            x: this.#position.x,
+            y: this.#window.innerHeight - size.height / 2 - floorInset
+          },
+          { width: this.#window.innerWidth, height: this.#window.innerHeight },
+          size.width,
+          size.height
+        );
+      }
+      this.#dragging = false;
+      this.#throwing = false;
+      this.#throwVelocity = { x: 0, y: 0 };
+      this.#landUntil = this.#now() + 360;
+      this.#wake();
+    }
+    #catchCharacter(targetId) {
+      const target = this.#targets?.snapshot(true)[targetId];
+      const size = this.#characterSize();
+      if (!target || !size) return false;
+      const interaction = this.#options.interaction || {};
+      const point = characterTargetPoint(
+        target,
+        interaction.catchAnchor ?? "center",
+        size
+      );
+      this.#position = clampPosition(
+        point,
+        { width: this.#window.innerWidth, height: this.#window.innerHeight },
+        size.width,
+        size.height
+      );
+      this.#throwing = false;
+      this.#throwVelocity = { x: 0, y: 0 };
+      this.#landUntil = this.#now() + 360;
+      if (interaction.catchEvent) this.emit(interaction.catchEvent);
+      this.#wake();
+      return true;
+    }
     #diagnose(message, code = "runtime.notice", severity = "warning", phase = "internal", eventId, metadata, cause) {
       this.#diagnostics.emit({
         code,
@@ -6770,6 +7943,7 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
       if (hidden === this.#siteHidden) return;
       this.#siteHidden = hidden;
       this.#renderer?.setHidden(hidden);
+      this.#interactionController?.setHidden(hidden);
       if (this.#destroyed) return;
       if (hidden && this.#contentRenderer) {
         this.#contentRenderer.renderSurfaces(
@@ -6785,6 +7959,9 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
         if (this.#destroyed) return;
       }
       if (hidden) {
+        this.#dragging = false;
+        this.#throwing = false;
+        this.#throwVelocity = { x: 0, y: 0 };
         this.#overrides?.clear("dismissed");
         this.#setSuspended(SUSPEND_SITE, true);
         this.#notice("lifecycle.dismissed", "info", "lifecycle");
@@ -6880,8 +8057,13 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
       const loaded = this.#loaded;
       this.#densityUpgrade = loaded.upgrade(required).then((changed) => {
         if (changed && !this.#destroyed && this.#loaded === loaded) {
-          this.#renderer?.swapAtlas(loaded.content, loaded.atlasObjectUrl);
-          this.#wake();
+          const renderer = this.#renderer;
+          if (!renderer) return;
+          return Promise.resolve(
+            renderer.swapAtlas(loaded.content, loaded.atlasObjectUrl)
+          ).then(() => {
+            if (!this.#destroyed && this.#loaded === loaded) this.#wake();
+          });
         }
       }).catch((error) => {
         if (!this.#destroyed)
@@ -6953,10 +8135,13 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
         pointer: input.pointer,
         position: this.#position,
         viewport,
+        characterSize,
         lastActivityAt: input.lastActivityAt,
         reducedMotion: this.#reducedMotion,
         pageVisible: !this.#document.hidden,
         sections,
+        targets: this.#targets?.snapshot(this.#trackTargets),
+        samplePath: (path, progress) => this.#pathSampler.sample(path, progress),
         reaction
       };
       return {
@@ -6977,11 +8162,26 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
         overrides.observeEvent(reaction.name, reaction.source);
       }
       const request = overrides.compose(ordinary, world);
+      this.#trackTargets = request.motion?.trackTarget === true;
       if (this.#reducedMotion) {
         delete request.motion;
         if (request.capability === "locomotion") delete request.capability;
         if (!request.state) request.state = "idle";
       }
+      const interaction = this.#options.interaction || {};
+      if (this.#dragging) {
+        delete request.motion;
+        delete request.capability;
+        request.state = interaction.dragState ?? "scroll:fly";
+      } else if (this.#throwing) {
+        delete request.motion;
+        delete request.capability;
+        request.state = this.#throwVelocity.y < 0 ? interaction.riseState ?? "scroll:fly" : interaction.fallState ?? "scroll:fall";
+      } else if (this.#landUntil > world.now) {
+        delete request.motion;
+        delete request.capability;
+        request.state = interaction.landState ?? "success";
+      }
       const diagnostics = [];
       if (reaction) {
         this.#seenReaction = reaction.id;
@@ -7040,19 +8240,74 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
       }
       return this.#frameActive(frame);
     }
+    #advanceThrow(snapshot) {
+      if (!this.#throwing) return;
+      const interaction = this.#options.interaction || {};
+      const dt = snapshot.frame.stepMs / 1e3;
+      const bounce = interaction.bounce ?? DEFAULT_BOUNCE;
+      const halfWidth = snapshot.characterSize.width / 2;
+      const halfHeight = snapshot.characterSize.height / 2;
+      const floor = snapshot.world.viewport.height - halfHeight - (interaction.floorInset ?? DEFAULT_FLOOR_INSET);
+      let velocityX = this.#throwVelocity.x;
+      let velocityY = this.#throwVelocity.y + (interaction.gravity ?? DEFAULT_GRAVITY) * dt;
+      let x = this.#position.x + velocityX * dt;
+      let y = this.#position.y + velocityY * dt;
+      const right = snapshot.world.viewport.width - halfWidth;
+      if (x < halfWidth) {
+        x = halfWidth;
+        velocityX = Math.abs(velocityX) * bounce;
+      } else if (x > right) {
+        x = right;
+        velocityX = -Math.abs(velocityX) * bounce;
+      }
+      if (y < halfHeight) {
+        y = halfHeight;
+        velocityY = Math.abs(velocityY) * bounce;
+      }
+      const next = { x, y };
+      if (interaction.catchTarget && this.#targets?.contains(
+        interaction.catchTarget,
+        next,
+        interaction.catchMargin ?? 24
+      ) && this.#catchCharacter(interaction.catchTarget)) {
+        return;
+      }
+      if (y >= floor) {
+        this.#position = { x, y: floor };
+        this.#landCharacter();
+        return;
+      }
+      this.#position = next;
+      this.#throwVelocity = { x: velocityX * 0.995, y: velocityY };
+    }
     #calculatePresentation(snapshot, evaluation) {
       const { frame, characterSize, world } = snapshot;
       const { request } = evaluation;
       const loaded = frame.loaded.content;
       if (!this.#reducedMotion)
         this.#animationClock += Math.max(0, frame.elapsed);
+      this.#advanceThrow(snapshot);
       const requested = request.capability === "locomotion" && request.motion ? loaded.directionalStates?.[directionTo(
         { x: 0, y: 0 },
         { x: request.motion.x, y: request.motion.y }
       )] : resolveCapabilityName(request.state, loaded);
       const resolved = resolveState(requested, loaded.states);
       let lift = 0;
-      if (request.motion) {
+      if (request.motion?.direct) {
+        const distance = request.motion.maxDistance ?? 0;
+        this.#position = clampPosition(
+          {
+            x: this.#position.x + request.motion.x * distance,
+            y: this.#position.y + request.motion.y * distance
+          },
+          world.viewport,
+          characterSize.width,
+          characterSize.height
+        );
+        lift = request.motion.lift ?? 0;
+        this.#locomotionState = "";
+        this.#locomotionElapsed = 0;
+      } else if (request.motion) {
         if (this.#locomotionState !== resolved.name) {
           this.#locomotionState = resolved.name;
           this.#locomotionElapsed = 0;
@@ -7083,7 +8338,7 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
           characterSize.width,
           characterSize.height
         );
-        lift = locomotionSample(loaded.locomotionMotion, nextCycles).lift * characterSize.height;
+        lift = request.motion.lift ?? locomotionSample(loaded.locomotionMotion, nextCycles).lift * characterSize.height;
       } else {
         this.#locomotionState = "";
         this.#locomotionElapsed = 0;
@@ -7117,9 +8372,15 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
         presentation.lift
       );
       if (!this.#frameActive(frame)) return;
+      this.#interactionController?.render(
+        this.#position,
+        snapshot.characterSize,
+        presentation.lift
+      );
+      if (!this.#frameActive(frame)) return;
       this.#lastTick = frame.now;
       this.#schedulePlan(frame);
-      if (this.#frameActive(frame) && (evaluation.request.motion || frame.input.reaction))
+      if (this.#frameActive(frame) && (evaluation.request.motion || frame.input.reaction || this.#throwing || this.#dragging))
         this.#wake();
     }
     #endPage() {
@@ -7202,6 +8463,24 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
       y: Math.max(height / 2, Math.min(viewport.height - height / 2, point.y))
     };
   }
+  function characterTargetPoint(target, anchor, character) {
+    const center = {
+      x: target.left + target.width / 2,
+      y: target.top + target.height / 2
+    };
+    switch (anchor) {
+      case "top":
+        return { x: center.x, y: target.top - character.height / 2 };
+      case "right":
+        return { x: target.right + character.width / 2, y: center.y };
+      case "bottom":
+        return { x: center.x, y: target.bottom + character.height / 2 };
+      case "left":
+        return { x: target.left - character.width / 2, y: center.y };
+      default:
+        return center;
+    }
+  }
 
   // packages/runtime/src/web-component.ts
   var PEEKLING_ELEMENT_TAG = "peekling-character";
@@ -7436,7 +8715,7 @@ ${styles.integrity ?? ""}` === this.#styleKey) return;
   }
 
   // packages/runtime/src/browser.ts
-  var browserCssIntegrity = "sha256-w8BENjaJ/B1wtpk3iuh7jT++FlbT5+fx5BBlvePx1qo=" ? "sha256-w8BENjaJ/B1wtpk3iuh7jT++FlbT5+fx5BBlvePx1qo=" : void 0;
+  var browserCssIntegrity = "sha256-r4PIKebZlQTb2JaHfQibQqQxHaKciwlXtTMDEvDTUPY=" ? "sha256-r4PIKebZlQTb2JaHfQibQqQxHaKciwlXtTMDEvDTUPY=" : void 0;
   var browserScript = globalThis.document?.currentScript;
   if (browserScript?.src) {
     setBrowserStyleAsset({