stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/pagination_controller.js

@@ -20,6 +20,39 @@ function canTakeFocus(element) {
   return !inheritsFieldsetDisabled(element);
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
 // src/utils/before_cache_reset.ts
 var BeforeCacheReset = class _BeforeCacheReset {
   /** Every subscribed instance, iterated by the one shared document listener. */
@@ -81,53 +114,57 @@ var TabindexLoan = class {
 };
 
 // src/controllers/pagination_controller.ts
-var PaginationController = class _PaginationController extends Controller {
+var PaginationController = class extends Controller {
   static targets = ["page", "prev", "next"];
   static values = {
     page: { type: Number, default: 1 },
     total: { type: Number, default: 1 }
   };
   static actions = ["next", "prev", "select"];
-  static events = ["change"];
-  /** Marks a `disabled` this controller applied at a boundary (ownership flag). */
-  static #BOUNDARY_ATTR = "data-stimeo--pagination-boundary-disabled";
-  #isConnected = false;
+  static events = ["change", "reconcile"];
+  /** Marks a `disabled` this controller applied at a boundary, in its own namespace. */
+  get #boundaryAttribute() {
+    return `data-${this.identifier}-boundary-disabled`;
+  }
   /** The `tabindex` this instance lends the root for the focus fallback. */
   #tabindex = new TabindexLoan();
-  /** Normalizes out-of-range initial values and renders the initial state. */
+  /**
+   * Collapses the Value and target callbacks of one mutation into one pass, and
+   * refuses the ones Stimulus delivers before `connect()`, which renders itself.
+   */
+  #repaint = new MicrotaskCoalescer(() => this.#reconcilePage());
+  /** The page shown last, which the next move of the current page is measured from. */
+  #shown = 1;
+  /** Renders the initial state from the clamped `page` and `total`. */
   connect() {
-    this.#isConnected = true;
-    this.#normalizeAndRender();
+    this.#repaint.activate();
+    this.#shown = this.#page;
+    this.#render();
   }
-  /** Reverts the one attribute the controller adds outside its state hooks. */
+  /** Drops a pending pass and reverts the one attribute added outside the state hooks. */
   disconnect() {
-    this.#isConnected = false;
+    this.#repaint.cancel();
     this.#tabindex.returnAll();
   }
   /** Re-renders when application code (or a Turbo morph) changes `page` at runtime. */
   pageValueChanged() {
-    if (!this.#isConnected) return;
-    this.#normalizeAndRender();
+    this.#repaint.schedule();
   }
   /** Re-renders when application code (or a Turbo morph) changes `total` at runtime. */
   totalValueChanged() {
-    if (!this.#isConnected) return;
-    this.#normalizeAndRender();
+    this.#repaint.schedule();
   }
   /** Syncs a page button appended/replaced at runtime (the consumer owns the list). */
   pageTargetConnected() {
-    if (!this.#isConnected) return;
-    this.#render();
+    this.#repaint.schedule();
   }
   /** Syncs a `prev` button appended/replaced at runtime. */
   prevTargetConnected() {
-    if (!this.#isConnected) return;
-    this.#render();
+    this.#repaint.schedule();
   }
   /** Syncs a `next` button appended/replaced at runtime. */
   nextTargetConnected() {
-    if (!this.#isConnected) return;
-    this.#render();
+    this.#repaint.schedule();
   }
   /** Makes the clicked page button (its `data-page`) current. */
   select(event) {
@@ -153,22 +190,31 @@ var PaginationController = class _PaginationController extends Controller {
     const target = this.#clamp(page);
     if (target === previous) return;
     this.pageValue = target;
+    this.#shown = target;
     this.#render();
     this.dispatch("change", {
       detail: { page: target, total: this.#total, previous }
     });
   }
-  /** Writes the normalized Values back (only when they differ) and renders. */
-  #normalizeAndRender() {
-    const total = this.#total;
-    if (!Object.is(total, this.totalValue)) this.totalValue = total;
+  /**
+   * Renders one settled batch of Value and target changes, and reports a current
+   * page that moved from the one shown before as `reconcile`.
+   */
+  #reconcilePage() {
+    const previous = this.#shown;
     const page = this.#page;
-    if (!Object.is(page, this.pageValue)) this.pageValue = page;
+    this.#shown = page;
     this.#render();
+    if (page !== previous) {
+      this.dispatch("reconcile", { detail: { page, total: this.#total, previous } });
+    }
   }
   /**
    * Syncs `aria-current` on the page buttons and the prev/next `disabled` state.
    *
+   * It reads `page` and `total` through their clamps and never writes either Value,
+   * so a declaration outside the range stays in the attributes as the page wrote it.
+   *
    * @stimeoRenderRoot
    */
   #render() {
@@ -201,7 +247,7 @@ var PaginationController = class _PaginationController extends Controller {
   #release(button, atBoundary) {
     if (!button || atBoundary || !this.#owns(button)) return;
     button.disabled = false;
-    button.removeAttribute(_PaginationController.#BOUNDARY_ATTR);
+    button.removeAttribute(this.#boundaryAttribute);
   }
   /**
    * Disables a boundary button, first moving focus off it when it is the active
@@ -212,7 +258,7 @@ var PaginationController = class _PaginationController extends Controller {
     if (button.disabled && !this.#owns(button)) return;
     if (button === document.activeElement) this.#moveFocusAwayFrom(opposite);
     button.disabled = true;
-    button.setAttribute(_PaginationController.#BOUNDARY_ATTR, "");
+    button.setAttribute(this.#boundaryAttribute, "");
   }
   /**
    * Moves focus to `opposite` (already resolved to `null` when it will stay
@@ -249,7 +295,7 @@ var PaginationController = class _PaginationController extends Controller {
   }
   /** Whether the button's current `disabled` was applied by boundary control. */
   #owns(button) {
-    return button.hasAttribute(_PaginationController.#BOUNDARY_ATTR);
+    return button.hasAttribute(this.#boundaryAttribute);
   }
 };
 

data/dist/controllers/password_reveal_controller.js

@@ -84,10 +84,51 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/state_regions.ts
+var StateRegions = class {
+  #whenTrue;
+  #whenFalse;
+  #taken = /* @__PURE__ */ new WeakSet();
+  constructor(options) {
+    this.#whenTrue = options.whenTrue;
+    this.#whenFalse = options.whenFalse ?? null;
+  }
+  /** Shows the regions inside `host` that belong to `isTrue` and hides the others. */
+  reflect(host, isTrue) {
+    const shown = this.#inside(host, this.#whenTrue());
+    if (!this.#whenFalse) {
+      for (const region of shown) this.#write(region, !isTrue);
+      return;
+    }
+    const hiddenSide = this.#inside(host, this.#whenFalse());
+    if (shown.length === 0 || hiddenSide.length === 0) {
+      for (const region of shown) this.#give(region);
+      for (const region of hiddenSide) this.#give(region);
+      return;
+    }
+    for (const region of shown) this.#write(region, !isTrue);
+    for (const region of hiddenSide) this.#write(region, isTrue);
+  }
+  /** Writes `hidden` where it moves, noting which regions it takes out of view. */
+  #write(region, hidden) {
+    if (hidden) this.#taken.add(region);
+    else this.#taken.delete(region);
+    if (region.hidden !== hidden) region.hidden = hidden;
+  }
+  /** Returns a region this instance hid; one it never hid keeps what it carries. */
+  #give(region) {
+    if (this.#taken.delete(region)) region.hidden = false;
+  }
+  /** The declared regions that sit within `host`, which may be the host itself. */
+  #inside(host, regions) {
+    return regions.filter((region) => host.contains(region));
+  }
+};
+
 // src/controllers/password_reveal_controller.ts
 var MAX_DELAY = 2 ** 31 - 1;
 var PasswordRevealController = class extends Controller {
-  static targets = ["input", "toggle"];
+  static targets = ["input", "toggle", "onLabel", "offLabel"];
   static values = {
     autoHide: { type: Number, default: 0 }
   };
@@ -105,6 +146,11 @@ var PasswordRevealController = class extends Controller {
    * document does not answer this — unloading the controller leaves it there.
    */
   #connected = false;
+  /** Owns `hidden` on the label pair the toggle button carries. */
+  #labels = new StateRegions({
+    whenTrue: () => this.onLabelTargets,
+    whenFalse: () => this.offLabelTargets
+  });
   /** Masks the field before Turbo copies the page into its snapshot. */
   #beforeCache = new BeforeCacheReset(() => this.#rewindToMasked());
   connect() {
@@ -144,6 +190,14 @@ var PasswordRevealController = class extends Controller {
   toggleTargetConnected() {
     this.#reflect(this.#isVisible);
   }
+  /** Describes the state to a revealed-side label that arrives after connect. */
+  onLabelTargetConnected() {
+    this.#reflect(this.#isVisible);
+  }
+  /** Describes the state to a masked-side label that arrives after connect. */
+  offLabelTargetConnected() {
+    this.#reflect(this.#isVisible);
+  }
   /** Toggles the input between masked and revealed. Bound via `data-action`. */
   toggle() {
     this.#setVisible(!this.#isVisible);
@@ -187,6 +241,8 @@ var PasswordRevealController = class extends Controller {
    * the opposite of what the declaration asked for. A value that is no delay at
    * all stays out of the positive range {@link PasswordRevealController.#arm}
    * requires, so it schedules nothing.
+   *
+   * @stimeoRuntimeOnly `autoHide` is the delay of the one re-masking timer it arms.
    */
   get #autoHideDelay() {
     return Math.min(this.autoHideValue, MAX_DELAY);
@@ -202,10 +258,11 @@ var PasswordRevealController = class extends Controller {
     this.inputTarget.type = "password";
     this.#reflect(false);
   }
-  /** Reflects the visible state onto `aria-pressed` and `data-state`. */
+  /** Reflects the visible state onto `aria-pressed`, `data-state` and the labels. */
   #reflect(visible) {
     if (this.hasToggleTarget) {
       this.toggleTarget.setAttribute("aria-pressed", visible ? "true" : "false");
+      this.#labels.reflect(this.toggleTarget, visible);
     }
     this.element.setAttribute("data-state", visible ? "visible" : "hidden");
   }

data/dist/controllers/persist_controller.js

@@ -127,7 +127,20 @@ function parseStringList(raw, fallback = []) {
   return parsed.filter((entry) => typeof entry === "string");
 }
 
+// src/utils/transient_hooks.ts
+var TransientHooks = class {
+  #attributes;
+  constructor(options) {
+    this.#attributes = options.attributes;
+  }
+  /** Drops the declared hooks from `element`; what it carries besides stays. */
+  reset(element) {
+    for (const attribute of this.#attributes) element.removeAttribute(attribute);
+  }
+};
+
 // src/controllers/persist_controller.ts
+var TRANSIENT = new TransientHooks({ attributes: ["data-persist-restored"] });
 var NON_VALUE_TYPES = /* @__PURE__ */ new Set(["file", "submit", "reset", "button", "image"]);
 var SENSITIVE_TYPES = /* @__PURE__ */ new Set(["password"]);
 var DEFAULT_EXCLUDE = ["authenticity_token", "_method", "utf8"];
@@ -197,7 +210,6 @@ var PersistController = class extends Controller {
     this.#excluded = parseStringList(this.excludeValue, DEFAULT_EXCLUDE);
     this.#knownFields = /* @__PURE__ */ new WeakSet();
     this.#forcedRestore.clear();
-    this.element.removeAttribute("data-persist-restored");
     this.element.addEventListener("input", this.#onInput);
     this.element.addEventListener("change", this.#onInput);
     this.#syncClearOn();
@@ -207,7 +219,7 @@ var PersistController = class extends Controller {
       attributeFilter: [
         "checked",
         "data-controller",
-        "data-stimeo--persist-target",
+        `data-${this.identifier}-target`,
         "id",
         "multiple",
         "name",
@@ -230,7 +242,7 @@ var PersistController = class extends Controller {
     this.#restoreDynamic.cancel();
     this.#forcedRestore.clear();
     this.#timeouts.clearAll();
-    this.element.removeAttribute("data-persist-restored");
+    TRANSIENT.reset(this.element);
     this.#payload = null;
   }
   /** Drops the active draft after storage confirms the removal. */
@@ -329,7 +341,7 @@ var PersistController = class extends Controller {
   }
   /** Reads, validates, and restores the active namespace. */
   #loadActiveDraft() {
-    this.element.removeAttribute("data-persist-restored");
+    TRANSIENT.reset(this.element);
     this.#payload = null;
     this.#knownFields = /* @__PURE__ */ new WeakSet();
     this.#forcedRestore.clear();
@@ -481,7 +493,7 @@ var PersistController = class extends Controller {
   }
   /** Whether this instance, rather than a nested Persist host, owns a field. */
   #ownsField(field) {
-    return field.closest('[data-controller~="stimeo--persist"]') === this.element;
+    return field.closest(`[data-controller~="${this.identifier}"]`) === this.element;
   }
   /** Marks all currently eligible fields without applying a payload. */
   #markCurrentFieldsKnown() {
@@ -515,7 +527,12 @@ var PersistController = class extends Controller {
     const name = value.trim();
     return name.length > 0 && !/\s/.test(name) ? name : null;
   }
-  /** Collects dynamic controls and select-option changes into one restore pass. */
+  /**
+   * Collects dynamic controls and select-option changes into one restore pass.
+   *
+   * @stimeoRuntimeOnly `key` decides whether an id change moves the storage namespace; it decides
+   *   nothing shown.
+   */
   #onMutations(records) {
     let rootIdChanged = false;
     for (const record of records) {
@@ -563,7 +580,12 @@ var PersistController = class extends Controller {
       this.#forcedRestore.add(field);
     }
   }
-  /** Resolves the logical key from the Value, falling back to the host id. */
+  /**
+   * Resolves the logical key from the Value, falling back to the host id.
+   *
+   * @stimeoRuntimeOnly `key` names the storage namespace; the restored fields come from what is
+   *   stored there.
+   */
   #resolveLogicalKey() {
     const key = this.keyValue || this.element.id;
     return key.length > 0 ? key : null;
@@ -572,7 +594,7 @@ var PersistController = class extends Controller {
   #storageKey(logicalKey) {
     return `${STORAGE_PREFIX}${logicalKey}`;
   }
-  /** Normalizes invalid debounce Values to the documented default. */
+  /** Normalizes an invalid `debounce` Value to the `debounce` default. */
   get #debounceDelay() {
     const value = this.debounceValue;
     return Number.isFinite(value) && value >= 0 ? value : DEFAULT_DEBOUNCE;

data/dist/controllers/pointer_drag_controller.js

@@ -72,7 +72,66 @@ function ownerOf(candidates, node) {
   return candidates[ownerIndex(candidates, node)] ?? null;
 }
 
+// src/utils/owned_pointer_session.ts
+var OwnedPointerSession = class {
+  #pointerId;
+  #owner;
+  #handlers;
+  #abort = new AbortController();
+  #active = true;
+  constructor(start, owner, handlers) {
+    this.#pointerId = start.pointerId;
+    this.#owner = owner;
+    this.#handlers = handlers;
+    const { signal } = this.#abort;
+    owner.ownerDocument.addEventListener("pointermove", this.#onMove, { signal });
+    owner.ownerDocument.addEventListener("pointerup", this.#onEndEvent, { signal });
+    owner.ownerDocument.addEventListener("pointercancel", this.#onEndEvent, { signal });
+    try {
+      owner.setPointerCapture?.(this.#pointerId);
+    } catch {
+    }
+  }
+  /** Releases capture and listeners, then reports the end exactly once. */
+  end() {
+    this.#finish("teardown");
+  }
+  #finish(kind) {
+    if (!this.#active) return;
+    this.#active = false;
+    this.#abort.abort();
+    try {
+      this.#owner.releasePointerCapture?.(this.#pointerId);
+    } catch {
+    }
+    this.#handlers.end?.(kind);
+  }
+  #owns(event) {
+    return this.#active && event.pointerId === this.#pointerId;
+  }
+  #onMove = (event) => {
+    if (this.#owns(event)) this.#handlers.move(event);
+  };
+  #onEndEvent = (event) => {
+    if (this.#owns(event)) this.#finish(event.type === "pointerup" ? "up" : "cancel");
+  };
+};
+
+// src/utils/transient_hooks.ts
+var TransientHooks = class {
+  #attributes;
+  constructor(options) {
+    this.#attributes = options.attributes;
+  }
+  /** Drops the declared hooks from `element`; what it carries besides stays. */
+  reset(element) {
+    for (const attribute of this.#attributes) element.removeAttribute(attribute);
+  }
+};
+
 // src/controllers/pointer_drag_controller.ts
+var TRANSIENT_DRAG = new TransientHooks({ attributes: ["data-dragging"] });
+var TRANSIENT_GRAB = new TransientHooks({ attributes: ["data-grabbed"] });
 var NATIVE_KEY_OWNERS = "input, textarea, select, button, a[href], summary, [contenteditable]";
 var PointerDragController = class _PointerDragController extends Controller {
   static targets = ["handle"];
@@ -93,14 +152,12 @@ var PointerDragController = class _PointerDragController extends Controller {
   #keyboard = null;
   /** Committed follow offset from past drops; a new drag's deltas add onto it. */
   #followBase = { x: 0, y: 0 };
-  /** Aborts in-progress pointer-drag listeners on drag end / teardown. */
-  #dragAbort = null;
   /** Decides whether a mid-session disconnect() is an in-page move or a detach. */
   #gate = new DetachGate();
   connect() {
     this.#gate.cancel();
-    if (!this.#pointer) this.element.removeAttribute("data-dragging");
-    if (!this.#keyboard) this.element.removeAttribute("data-grabbed");
+    if (!this.#pointer) TRANSIENT_DRAG.reset(this.element);
+    if (!this.#keyboard) TRANSIENT_GRAB.reset(this.element);
     if (this.followValue && !this.#pointer && !this.#keyboard) {
       this.#followBase = this.#parseFollowBase();
     }
@@ -170,15 +227,19 @@ var PointerDragController = class _PointerDragController extends Controller {
     }
     this.#teardownSessions();
   }
-  /** Arms a pointer drag on a handle; `start` waits for the threshold. */
+  /**
+   * Arms a pointer drag on a handle; `start` waits for the threshold.
+   *
+   * @stimeoRuntimeOnly `disabled` decides whether this one pointer press starts a gesture.
+   */
   #onPointerDown = (event) => {
     if (this.disabledValue || this.#pointer || this.#keyboard || event.button !== 0) return;
     const handle = this.#handleFor(event.target);
     if (!handle) return;
     event.preventDefault();
     handle.focus();
-    this.#pointer = {
-      pointerId: event.pointerId,
+    const session = {
+      pointer: null,
       handle,
       originX: event.clientX,
       originY: event.clientY,
@@ -187,17 +248,18 @@ var PointerDragController = class _PointerDragController extends Controller {
       dy: 0,
       pointerType: this.#pointerTypeOf(event)
     };
-    handle.setPointerCapture(event.pointerId);
-    this.#dragAbort?.abort();
-    const abort = new AbortController();
-    this.#dragAbort = abort;
-    document.addEventListener("pointermove", this.#onPointerMove, { signal: abort.signal });
-    document.addEventListener("pointerup", this.#onPointerUp, { signal: abort.signal });
-    document.addEventListener("pointercancel", this.#onPointerCancel, { signal: abort.signal });
+    session.pointer = new OwnedPointerSession(event, handle, {
+      move: (move) => this.#trackMove(session, move),
+      end: (kind) => this.#finishPointer(session, kind)
+    });
+    this.#pointer = session;
   };
-  #onPointerMove = (event) => {
-    const session = this.#pointer;
-    if (!session || event.pointerId !== session.pointerId) return;
+  /**
+   * Applies one tracked move: threshold, hooks, follow offset, events.
+   *
+   * @stimeoRuntimeOnly `threshold` decides when this one pointer move starts the drag.
+   */
+  #trackMove(session, event) {
     const [dx, dy] = this.#filterAxis(
       event.clientX - session.originX,
       event.clientY - session.originY
@@ -216,25 +278,32 @@ var PointerDragController = class _PointerDragController extends Controller {
     this.dispatch("move", {
       detail: { dx, dy, x: event.clientX, y: event.clientY, pointerType: session.pointerType }
     });
-  };
-  #onPointerUp = (event) => {
-    const session = this.#pointer;
-    if (!session || event.pointerId !== session.pointerId) return;
+  }
+  /**
+   * Closes the session and reports only the outcome the caller does not own.
+   *
+   * A teardown (detach, Escape, mid-drag disable, `reset`) is announced by the
+   * path that asked for it, so this one stays silent; `pointerup` below the
+   * threshold was a plain click, and `pointercancel` is an OS gesture takeover.
+   */
+  #finishPointer(session, kind) {
     const { started, dx, dy, pointerType } = session;
-    this.#endPointerSession();
-    if (!started) return;
-    this.#followCommit(dx, dy);
-    this.dispatch("end", { detail: { dx, dy, pointerType } });
-  };
-  /** OS gesture / scroll takeover interrupted the drag: cancel, don't drop. */
-  #onPointerCancel = (event) => {
-    const session = this.#pointer;
-    if (!session || event.pointerId !== session.pointerId) return;
-    const { started, pointerType } = session;
-    this.#endPointerSession();
-    if (started) this.#dispatchCancel(pointerType);
-  };
-  /** Keyboard alternative: Space/Enter grab & drop, arrows move, Escape cancels. */
+    this.#pointer = null;
+    this.element.removeAttribute("data-dragging");
+    if (kind === "teardown" || !started) return;
+    if (kind === "up") {
+      this.#followCommit(dx, dy);
+      this.dispatch("end", { detail: { dx, dy, pointerType } });
+      return;
+    }
+    this.#dispatchCancel(pointerType);
+  }
+  /**
+   * Keyboard alternative: Space/Enter grab & drop, arrows move, Escape cancels.
+   *
+   * @stimeoRuntimeOnly `disabled` decides whether this one key is taken and `keyboardStep` is the
+   *   distance of one keyboard move.
+   */
   #onKeydown = (event) => {
     if (this.disabledValue) return;
     const handle = this.#handleFor(event.target);
@@ -316,26 +385,19 @@ var PointerDragController = class _PointerDragController extends Controller {
         return null;
     }
   }
-  /** Zeroes the delta on the locked axis (`axis` = x | y | both). */
+  /**
+   * Zeroes the delta on the locked axis (`axis` = x | y | both).
+   *
+   * @stimeoRuntimeOnly `axis` filters the offset of one move to the allowed direction.
+   */
   #filterAxis(dx, dy) {
     if (this.axisValue === "x") return [dx, 0];
     if (this.axisValue === "y") return [0, dy];
     return [dx, dy];
   }
-  /** Releases capture + listeners and clears the pointer session and its hook. */
+  /** Silently closes a live pointer session; the caller announces the outcome. */
   #endPointerSession() {
-    this.#releasePointerCapture();
-    this.#pointer = null;
-    this.#dragAbort?.abort();
-    this.#dragAbort = null;
-    this.element.removeAttribute("data-dragging");
-  }
-  /** Releases the pointer capture the active session set (idempotent, safe). */
-  #releasePointerCapture() {
-    const session = this.#pointer;
-    if (session?.handle.hasPointerCapture(session.pointerId)) {
-      session.handle.releasePointerCapture(session.pointerId);
-    }
+    this.#pointer?.pointer?.end();
   }
   #clearKeyboardSession() {
     this.#keyboard?.handle.removeAttribute("data-grabbed");
@@ -372,18 +434,33 @@ var PointerDragController = class _PointerDragController extends Controller {
     this.#followReset();
     this.dispatch("cancel", { detail: { pointerType } });
   }
-  /** Applies the in-flight offset to the element's `translate` (follow only). */
+  /**
+   * Applies the in-flight offset to the element's `translate` (follow only).
+   *
+   * @stimeoRuntimeOnly `follow` decides whether this one move writes the offset as a translate; the
+   *   offset itself comes from the gesture.
+   */
   #followMove(dx, dy) {
     if (!this.followValue) return;
     this.#applyFollow(this.#followBase.x + dx, this.#followBase.y + dy);
   }
-  /** Folds a drop's deltas into the committed base offset (follow only). */
+  /**
+   * Folds a drop's deltas into the committed base offset (follow only).
+   *
+   * @stimeoRuntimeOnly `follow` decides whether the end of this one gesture keeps the offset as a
+   *   translate.
+   */
   #followCommit(dx, dy) {
     if (!this.followValue) return;
     this.#followBase = { x: this.#followBase.x + dx, y: this.#followBase.y + dy };
     this.#applyFollow(this.#followBase.x, this.#followBase.y);
   }
-  /** Snaps back to the committed position (follow only) — the cancel contract. */
+  /**
+   * Snaps back to the committed position (follow only) — the cancel contract.
+   *
+   * @stimeoRuntimeOnly `follow` decides whether cancelling this one gesture clears the translate it
+   *   wrote.
+   */
   #followReset() {
     if (!this.followValue) return;
     this.#applyFollow(this.#followBase.x, this.#followBase.y);
@@ -438,6 +515,8 @@ var PointerDragController = class _PointerDragController extends Controller {
    * idempotent) and focusability for the keyboard path (`tabindex="0"` only when
    * the author supplied none — prefer a real `<button>` handle). Both additions
    * are marker-owned so `#restoreHandle` reverts them symmetrically on teardown.
+   *
+   * @stimeoRenderRoot
    */
   #prepareHandle(handle) {
     const lent = this.#touchActionForAxis();