@barefootjs/client 0.34.0 → 0.35.1

package/dist/runtime/map-array.d.ts

@@ -17,6 +17,16 @@
  * extras...) triple — moves, mounts, and unmounts as a single unit.
  * Single-root loops continue to flow through the legacy path verbatim.
  */
+/**
+ * Shape `renderItem` callbacks are compiled to. `index` mirrors `item`:
+ * an accessor, not a plain number, so a row body's reference to the raw
+ * `.map()` index parameter — rewritten to a call by
+ * `wrapLoopParamAsAccessor` — reads the row's CURRENT position instead of
+ * the value captured when the row was first created (#2859). `existing`
+ * stays optional/untyped-per-call-site since `mapArray` and
+ * `mapArrayAnchored` return different element shapes.
+ */
+export type RenderItem<T, E, R> = (item: () => T, index: () => number, existing?: E) => R;
 /**
  * Find loop boundary comment markers in a container.
  *
@@ -73,7 +83,7 @@ export declare function longestIncreasingSubsequenceIndices(arr: number[]): numb
  *                     replaced a hardcoded constant instead of just fixing
  *                     the value).
  */
-export declare function mapArray<T>(accessor: () => T[], container: HTMLElement | null, getKey: ((item: T, index: number) => string) | null, renderItem: (item: () => T, index: number, existing?: HTMLElement) => HTMLElement, markerId?: string, bfId?: string, keyAttrName?: string): void;
+export declare function mapArray<T>(accessor: () => T[], container: HTMLElement | null, getKey: ((item: T, index: number) => string) | null, renderItem: RenderItem<T, HTMLElement, HTMLElement>, markerId?: string, bfId?: string, keyAttrName?: string): void;
 /**
  * Per-item scoped list rendering for whole-item conditionals (#1665).
  *
@@ -82,5 +92,5 @@ export declare function mapArray<T>(accessor: () => T[], container: HTMLElement
  * (hydration). Items may render zero elements; the anchor is the stable
  * identity and position.
  */
-export declare function mapArrayAnchored<T>(accessor: () => T[], container: HTMLElement | null, getKey: ((item: T, index: number) => string) | null, renderItem: (item: () => T, index: number, existing?: Comment) => DocumentFragment | Comment, markerId?: string, bfId?: string): void;
+export declare function mapArrayAnchored<T>(accessor: () => T[], container: HTMLElement | null, getKey: ((item: T, index: number) => string) | null, renderItem: RenderItem<T, Comment, DocumentFragment | Comment>, markerId?: string, bfId?: string): void;
 //# sourceMappingURL=map-array.d.ts.map

package/dist/runtime/map-array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map-array.d.ts","sourceRoot":"","sources":["../../src/runtime/map-array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,WAAW,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CA+BhD;AAyHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA2B3E;AA4GD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,KAAK,WAAW,EACjF,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,EACb,WAAW,GAAE,MAAe,GAC3B,IAAI,CAsUN;AAqHD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,gBAAgB,GAAG,OAAO,EAC5F,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CA+FN"}
+{"version":3,"file":"map-array.d.ts","sourceRoot":"","sources":["../../src/runtime/map-array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA6EH;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;AAEzF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,WAAW,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CA+BhD;AAyHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA2B3E;AA+GD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,UAAU,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,EACnD,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,EACb,WAAW,GAAE,MAAe,GAC3B,IAAI,CA4UN;AA0HD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,EAC9D,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAoGN"}

package/dist/runtime/portal.d.ts

@@ -92,5 +92,49 @@ export declare function isSSRPortal(element: HTMLElement): boolean;
  */
 export declare function findSiblingSlot(el: HTMLElement, slotSelector: string): HTMLElement | null;
 export declare function cleanupPortalPlaceholder(portalId: string): void;
+/**
+ * Insertion rule (#2717): the portal's content is appended to `container`
+ * synchronously, at call time, and — when the component it belongs to is
+ * not yet in the document — re-appended once that component connects,
+ * which moves it to the container's end.
+ *
+ * - Owner already connected (hydration: SSR markup is in the document
+ *   before `init` runs), or nothing to wait for: a single append, at the
+ *   container's end — unchanged behaviour.
+ * - Owner not yet connected (a client-side mount: `materializeComponent`
+ *   runs `init` — and so the `ref` callbacks that call this — BEFORE the
+ *   bare-`createComponent` caller connects the root): the element is
+ *   appended now all the same, and a reorder is queued; once the owner
+ *   connects, pending portals are re-appended in creation order.
+ *
+ * Without the reorder the two construction paths disagree on
+ * `document.body`'s child order: hydration yields `[root, …portals]`
+ * while a CSR mount yields `[…portals, root]`, because the root is
+ * appended AFTER its portals were. Child order is user-visible (paint
+ * order between equal-`z-index` overlays, focus traversal, `querySelector`
+ * results), so both paths converge on the hydration answer.
+ *
+ * The append itself is never deferred: the element is connected to the
+ * document at every point in time, only its position among the
+ * container's children settles asynchronously (as a microtask, before the
+ * next paint). Portal consumers measure layout synchronously in the same
+ * tick as their `ref` callback — `createEffect`'s first run is synchronous,
+ * and the floating-position components (popover, dropdown-menu, context-
+ * menu, …) read `offsetWidth`/`offsetHeight` of the portaled element there,
+ * gated only on their open signal — so a portal that was briefly absent
+ * from the document would hand them zero-sized boxes with nothing to
+ * re-trigger the measurement once it landed.
+ *
+ * The subject whose connection is awaited is the `ownerScope` when given
+ * and it lies outside the element; otherwise the element's former parent.
+ * The self-owner shape (`ownerScope === element`: a child component whose
+ * own root carries `bf-s`, e.g. DialogOverlay/DialogContent) needs that
+ * fallback, since the immediate append connects the element — and so the
+ * owner — right away, while the component under construction is the tree
+ * it was taken from. An element in a detached tree with no owner (a
+ * fragment-root component, whose scope lives on a comment) is the same
+ * case. A bare element with neither has nothing that will ever connect
+ * it, so there is nothing to wait for.
+ */
 export declare function createPortal(children: PortalChildren, container?: HTMLElement, options?: PortalOptions): Portal;
 //# sourceMappingURL=portal.d.ts.map

package/dist/runtime/portal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../src/runtime/portal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,MAAM,MAAM,GAAG;IACnB,0BAA0B;IAC1B,OAAO,EAAE,WAAW,CAAA;IACpB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,IAAI,MAAM,CAAA;CAAE,CAAA;AAE/C,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAiBzF;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAK/D;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,SAAS,GAAE,WAA2B,EACtC,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CAyCR"}
+{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../src/runtime/portal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,MAAM,MAAM,GAAG;IACnB,0BAA0B;IAC1B,OAAO,EAAE,WAAW,CAAA;IACpB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,IAAI,MAAM,CAAA;CAAE,CAAA;AAE/C,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAiBzF;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAK/D;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,SAAS,GAAE,WAA2B,EACtC,OAAO,CAAC,EAAE,aAAa,GACtB,MAAM,CA0DR"}

package/dist/runtime/standalone.js

@@ -2020,6 +2020,11 @@ function escapeText(value) {
     return "";
   return escapeAttr(value);
 }
+function escapeCommentText(value) {
+  if (value == null)
+    return "";
+  return String(value).replace(/-/g, "‐");
+}
 var BF_MARKUP_BRAND = "__bfMarkup";
 function bfMarkup(html) {
   return { [BF_MARKUP_BRAND]: html };
@@ -2153,6 +2158,46 @@ function cleanupPortalPlaceholder(portalId) {
   const placeholder = document.querySelector(`template[${BF_PORTAL_PLACEHOLDER}="${portalId}"]`);
   placeholder?.remove();
 }
+var pendingPortals = [];
+var pendingObserver = null;
+function moveToContainerEnd(container, element) {
+  const moveBefore = container.moveBefore;
+  if (typeof moveBefore === "function") {
+    moveBefore.call(container, element, null);
+  } else {
+    container.appendChild(element);
+  }
+}
+function flushPendingPortals() {
+  for (const pending of pendingPortals.slice()) {
+    if (!pending.subject.isConnected)
+      continue;
+    pendingPortals.splice(pendingPortals.indexOf(pending), 1);
+    if (pending.element.parentNode === pending.container) {
+      moveToContainerEnd(pending.container, pending.element);
+    }
+  }
+  if (pendingPortals.length === 0 && pendingObserver) {
+    pendingObserver.disconnect();
+    pendingObserver = null;
+  }
+}
+function enqueuePendingPortal(pending) {
+  pendingPortals.push(pending);
+  if (!pendingObserver) {
+    pendingObserver = new MutationObserver(flushPendingPortals);
+    pendingObserver.observe(document, { childList: true, subtree: true });
+  }
+}
+function cancelPendingPortal(element) {
+  const idx = pendingPortals.findIndex((p) => p.element === element);
+  if (idx >= 0)
+    pendingPortals.splice(idx, 1);
+  if (pendingPortals.length === 0 && pendingObserver) {
+    pendingObserver.disconnect();
+    pendingObserver = null;
+  }
+}
 function createPortal(children, container = document.body, options) {
   let element;
   if (children instanceof HTMLElement) {
@@ -2174,16 +2219,35 @@ function createPortal(children, container = document.body, options) {
       element.setAttribute(BF_PORTAL_OWNER, scopeId);
     }
   }
+  const owner = options?.ownerScope;
+  const formerParent = children instanceof HTMLElement ? children.parentNode : null;
+  const subject = owner && !element.contains(owner) ? owner : formerParent instanceof Element ? formerParent : null;
   container.appendChild(element);
+  if (subject && !subject.isConnected && typeof MutationObserver !== "undefined") {
+    enqueuePendingPortal({ element, container, subject });
+  }
   return {
     element,
     unmount() {
+      cancelPendingPortal(element);
       if (element.parentNode) {
         element.parentNode.removeChild(element);
       }
     }
   };
 }
+// src/runtime/track-position.ts
+function trackPosition(update) {
+  update();
+  const onChange = () => update();
+  window.addEventListener("scroll", onChange, true);
+  window.addEventListener("resize", onChange);
+  return () => {
+    window.removeEventListener("scroll", onChange, true);
+    window.removeEventListener("resize", onChange);
+    update();
+  };
+}
 // src/runtime/loop-markers.ts
 function findLoopMarkers(container, markerId) {
   let startMarker = null;
@@ -2454,17 +2518,20 @@ function createItemScope(item, index, renderItem, existingPrimary, existingExtra
   let primaryEl;
   let dispose;
   let setItem;
+  let setIndex;
   let extras = [];
   let startMarker = null;
   let scopeComments = null;
   createRoot((d) => {
     dispose = d;
     const [itemAccessor, itemSetter] = createSignal(item);
+    const [indexAccessor, indexSetter] = createSignal(index);
     setItem = itemSetter;
+    setIndex = indexSetter;
     const ownsRowMount = !existingPrimary && !!rowMount;
     const prevRowMount = ownsRowMount ? setRowMountPoint(rowMount) : null;
     try {
-      primaryEl = renderItem(itemAccessor, index, existingPrimary);
+      primaryEl = renderItem(itemAccessor, indexAccessor, existingPrimary);
     } catch (err) {
       const parked = rowMount?.mounted;
       if (parked?.parentNode)
@@ -2497,7 +2564,7 @@ function createItemScope(item, index, renderItem, existingPrimary, existingExtra
   if (rowMount && !existingPrimary && extras.length > 0 && primaryEl.parentNode) {
     primaryEl.remove();
   }
-  return { startMarker, primaryEl, extras, scopeComments, dispose, setItem };
+  return { startMarker, primaryEl, extras, scopeComments, dispose, setItem, setIndex };
 }
 function mapArray(accessor, container, getKey, renderItem, markerId, bfId, keyAttrName2 = BF_KEY) {
   if (!container)
@@ -2575,7 +2642,8 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId, keyAt
             extras: range.extras,
             scopeComments: range.scopeComments,
             dispose: () => {},
-            setItem: () => {}
+            setItem: () => {},
+            setIndex: () => {}
           });
         }
       }
@@ -2621,7 +2689,10 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId, keyAt
       newKeys.add(key);
       const existing = scopes.get(key);
       if (existing) {
-        existing.setItem(item);
+        batch(() => {
+          existing.setItem(item);
+          existing.setIndex(i2);
+        });
         desiredOrder.push(existing);
       } else {
         const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, undefined, { container, anchor });
@@ -2719,23 +2790,26 @@ function removeAnchorScope(scope, end) {
 function createAnchorScope(item, index, key, renderItem, existingAnchor) {
   let dispose;
   let setItem;
+  let setIndex;
   let returned;
   createRoot((d) => {
     dispose = d;
     const [itemAccessor, itemSetter] = createSignal(item);
+    const [indexAccessor, indexSetter] = createSignal(index);
     setItem = itemSetter;
-    returned = renderItem(itemAccessor, index, existingAnchor);
+    setIndex = indexSetter;
+    returned = renderItem(itemAccessor, indexAccessor, existingAnchor);
     return;
   });
   if (existingAnchor) {
-    return { anchor: existingAnchor, pending: null, dispose, setItem };
+    return { anchor: existingAnchor, pending: null, dispose, setItem, setIndex };
   }
   const frag = returned;
   const anchor = frag.firstChild;
   if (anchor && !anchor.nodeValue?.startsWith(ITEM_PREFIX)) {
     anchor.nodeValue = loopItemMarker(key);
   }
-  return { anchor, pending: frag, dispose, setItem };
+  return { anchor, pending: frag, dispose, setItem, setIndex };
 }
 function mapArrayAnchored(accessor, container, getKey, renderItem, markerId, bfId) {
   if (!container)
@@ -2786,7 +2860,10 @@ function mapArrayAnchored(accessor, container, getKey, renderItem, markerId, bfI
       newKeys.add(key);
       const existing = scopes.get(key);
       if (existing) {
-        existing.setItem(item);
+        batch(() => {
+          existing.setItem(item);
+          existing.setIndex(i);
+        });
         desiredOrder.push(existing);
       } else {
         const scope = createAnchorScope(item, i, key, renderItem);
@@ -2856,6 +2933,7 @@ function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId, keyAttr
       key,
       primaryEl: undefined,
       item,
+      index,
       refs: null,
       last: null
     };
@@ -2885,7 +2963,7 @@ function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId, keyAttr
           const el = doms[i2];
           const ssrKey = el.getAttribute(keyAttrName2);
           const key = ssrKey !== null ? ssrKey : getKey ? getKey(items[i2], i2) : String(i2);
-          const entry = { key, primaryEl: el, item: items[i2], refs: null, last: null };
+          const entry = { key, primaryEl: el, item: items[i2], index: i2, refs: null, last: null };
           entries.set(key, entry);
           list.push(entry);
         }
@@ -2940,11 +3018,19 @@ function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId, keyAttr
       newKeys.add(key);
       const existing = entries.get(key);
       if (existing) {
-        if (!Object.is(existing.item, item)) {
+        const itemChanged = !Object.is(existing.item, item);
+        const indexChanged = plan.indexDriven === true && existing.index !== i2;
+        if (itemChanged) {
           const prevItem = existing.item;
           existing.item = item;
+          existing.index = i2;
           untrack(() => plan.applyItem(existing, prevItem));
           markStranded();
+        } else if (indexChanged) {
+          existing.index = i2;
+          untrack(() => plan.applyItem(existing, item));
+        } else {
+          existing.index = i2;
         }
         desiredOrder.push(existing);
       } else {
@@ -3801,6 +3887,7 @@ export {
   upsertChild,
   unwrap,
   untrack,
+  trackPosition,
   textOrNode,
   textNodeAfterComment as tAfter,
   styleToCss,
@@ -3854,6 +3941,7 @@ export {
   escapeTextOrNode,
   escapeTextOrMarkup,
   escapeText,
+  escapeCommentText,
   escapeAttr,
   endTurn,
   disposeScope,

package/dist/runtime/track-position.d.ts

@@ -0,0 +1,37 @@
+/**
+ * BarefootJS - Floating-element position tracking
+ *
+ * Keeps a `position: fixed` overlay (menu, popover, listbox, hover card)
+ * anchored to its trigger for as long as it is open. Shared by every
+ * site/ui overlay that positions itself from `getBoundingClientRect()`
+ * so the decision below is made in one place (#2848).
+ */
+/**
+ * Run `update` now, re-run it on every scroll (capture phase, so a
+ * nested scroll container counts too) and on resize, and return the
+ * dispose that detaches both listeners.
+ *
+ * The dispose re-runs `update` ONCE, synchronously, before detaching —
+ * that final sample is the whole point of this helper. `scroll` events
+ * are coalesced per rendering frame and report the scroll position at
+ * dispatch time, not at scroll time. A programmatic scroll that landed
+ * in the current frame (a `focus()` on an offscreen item, a
+ * `scrollIntoView()`) has therefore not dispatched yet when a close
+ * runs in the same frame; the listener is gone by the time the event
+ * fires, and whatever position the listener would have written is lost.
+ * Without the final sample the closed element's inline position depends
+ * on whether a frame boundary happened to fall between that scroll and
+ * the close — measured as the `dropdown-menu` idempotence oracle
+ * landing on `top: -580px` / `-606px` / `33px` for the same action
+ * sequence. Sampling once at dispose makes the closed position a
+ * function of the geometry at close time only.
+ *
+ * (An `overflow: hidden` scroll lock does not narrow this window: it
+ * blocks user gestures, never programmatic scrolling, on `html` and
+ * `body` alike — verified in Chromium against the fixture-hydrate host.)
+ *
+ * @param update - Positions the element from current geometry.
+ * @returns Dispose: re-runs `update` once, then detaches the listeners.
+ */
+export declare function trackPosition(update: () => void): () => void;
+//# sourceMappingURL=track-position.d.ts.map

package/dist/runtime/track-position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-position.d.ts","sourceRoot":"","sources":["../../src/runtime/track-position.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAU5D"}

package/dist/shims.d.ts

@@ -18,4 +18,5 @@ export declare function createPortal(_children: PortalChildren, _container?: Ele
 export declare function isSSRPortal(_element: HTMLElement): boolean;
 export declare function findSiblingSlot(_el: HTMLElement, _slotSelector: string): HTMLElement | null;
 export declare function cleanupPortalPlaceholder(_portalId: string): void;
+export declare function trackPosition(_update: () => void): () => void;
 //# sourceMappingURL=shims.d.ts.map

package/dist/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../src/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEhF,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAS5F,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAErD;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAEvE;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,UAAU,CAAC,EAAE,OAAO,EACpB,QAAQ,CAAC,EAAE,aAAa,GACvB,MAAM,CAER;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAE1D;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,WAAW,EAChB,aAAa,EAAE,MAAM,GACpB,WAAW,GAAG,IAAI,CAEpB;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEhE"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../src/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEhF,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAS5F,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAErD;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAEvE;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,UAAU,CAAC,EAAE,OAAO,EACpB,QAAQ,CAAC,EAAE,aAAa,GACvB,MAAM,CAER;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAE1D;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,WAAW,EAChB,aAAa,EAAE,MAAM,GACpB,WAAW,GAAG,IAAI,CAEpB;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEhE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAE7D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/client",
-  "version": "0.34.0",
+  "version": "0.35.1",
   "description": "BarefootJS client package: reactive primitives (SSR-safe) plus browser runtime under the `/runtime` subpath (compiler target)",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,7 +55,7 @@
     "directory": "packages/client"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.34.0"
+    "@barefootjs/shared": "0.35.1"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"

package/src/index.ts

@@ -60,6 +60,7 @@ export {
   isSSRPortal,
   findSiblingSlot,
   cleanupPortalPlaceholder,
+  trackPosition,
   type Portal,
   type PortalChildren,
   type PortalOptions,

package/src/runtime/component.ts

@@ -951,6 +951,33 @@ export function escapeText(value: unknown): string {
   return escapeAttr(value)
 }
 
+/**
+ * Neutralize a value for splicing into an HTML COMMENT (`<!--...-->`), the
+ * whole-item loop conditional's `bf-loop-i:<key>` anchor (#1665,
+ * `itemAnchorTemplate` in `ir-to-client-js/html-template.ts`) being the one
+ * caller today. Standard HTML escaping (`escapeAttr`/`escapeText`) does
+ * NOT help here: `-`, `<`, `>` are not special in comment content the way
+ * `& < > " '` are in text/attributes — the only thing that terminates a
+ * comment early is the literal three-character sequence `-->`, which
+ * `escapeAttr` never touches.
+ *
+ * The key's exact text does not need to round-trip: nothing reads it back
+ * out of the DOM (`mapArrayAnchored` matches items positionally on first
+ * hydration and by its own JS-computed key afterward, never by re-parsing
+ * `Comment.nodeValue`, `map-array.ts`'s `isItemAnchor`/`findItemAnchors`).
+ * So replacing every ASCII hyphen with the visually-similar U+2010 HYPHEN
+ * is sufficient and simpler than a reversible escape: it makes `-->`
+ * unconstructible from the result (a hyphen adjacent to the template's own
+ * literal `-->` can no longer complete the sequence), and — because it is
+ * a different Unicode character rather than an HTML entity — needs no
+ * decoding: HTML comments do not interpret character references at all,
+ * so `&#45;` would appear as literal text `&#45;`, not `-`.
+ */
+export function escapeCommentText(value: unknown): string {
+  if (value == null) return ''
+  return String(value).replace(/-/g, '‐')
+}
+
 /**
  * Brand carried by `bfMarkup()` — see that function's docstring. A string
  * key (not a `Symbol`) because the brand must survive `structuredClone`
@@ -977,7 +1004,7 @@ export interface BfMarkup {
  * itself assembled from a JSX element passed at a non-`children` component
  * prop position (`header={<strong>Title</strong>}`) — every text segment
  * inside that assembly was already escaped node-by-node during the
- * assembly (the same `escapeHtml` / `escapeTextSlotExpr` calls
+ * assembly (the same `escapeHtml` calls / `spliceChildValue` door
  * `html-template.ts` uses for ordinary element children), so the
  * concatenated result is exactly as safe as any other compiler-emitted
  * template fragment.
@@ -1009,8 +1036,8 @@ export function isBfMarkup(value: unknown): value is BfMarkup {
 /**
  * `escapeText`'s counterpart for a claim-plan slot the compiler has
  * classified `kind: 'markup'` at STATIC/initial-render time
- * (`html-template.ts`'s `escapeTextSlotExpr`, gated on the same
- * `ctx.dynamicElements` membership `emit-reactive.ts` reads to pick the
+ * (`html-template.ts`'s `spliceChildValue` door, `safe-html.ts`, gated on
+ * the same `ctx.dynamicElements` membership `emit-reactive.ts` reads to pick the
  * writer kind for the REACTIVE side, below) — #2651. A `bfMarkup()`-branded
  * value is compiler-built HTML the compiler already escaped piecewise
  * while assembling it, and must reach the template raw, unescaped a second
@@ -1027,9 +1054,8 @@ export function escapeTextOrMarkup(value: unknown): string {
 
 /**
  * Nullish guard for a bare `${children}` passthrough splice
- * (`ir-to-client-js/html-template.ts`'s no-`slotId` `'expression'` branches
- * — the "bare `${...}` interpolations" the docstring above `escapeTextSlotExpr`
- * describes) — #2775. The value here is ALREADY-STRINGIFIED MARKUP, not an
+ * (`ir-to-client-js/safe-html.ts`'s `spliceChildValue` door, no-`slotId`
+ * `'expression'` branches) — #2775. The value here is ALREADY-STRINGIFIED MARKUP, not an
  * arbitrary prop: `materializeComponent` (this file, "Template functions
  * expect children as an HTML string, not an array") joins a component's
  * `children` into an HTML string before the template lambda ever runs, so by
@@ -1063,7 +1089,7 @@ export function markupOrEmpty(value: unknown): string {
  * interpret HTML, so a raw un-escaped string is an injection/corruption
  * risk exactly where the initial SSR/CSR TEMPLATE already calls
  * `escapeText` on the same expression (`html-template.ts`'s
- * `escapeTextSlotExpr`). A live `Node`, by contrast, must pass through
+ * `spliceChildValue` door, `safe-html.ts`). A live `Node`, by contrast, must pass through
  * untouched — `escapeText(node)` would stringify it to garbage, and
  * `writeMarkup`'s own `instanceof Node` check needs the real object to
  * splice in by identity. This is the single call every "dynamic JSX/text

package/src/runtime/index.ts

@@ -77,6 +77,9 @@ export {
   type PortalChildren,
 } from './portal.ts'
 
+// Floating-element positioning (#2848)
+export { trackPosition } from './track-position.ts'
+
 // Loop boundary marker lookup (used by mapArray/mapArrayAnchored consumers
 // and compiler-generated clearing code — see ./loop-markers.ts docstring)
 export { getLoopChildren, getLoopNodes } from './loop-markers.ts'
@@ -105,6 +108,7 @@ export {
   parseHTML,
   escapeAttr,
   escapeText,
+  escapeCommentText,
   escapeTextOrNode,
   // JSX-element-as-prop markup brand (#2651) — compiler-emitted code only.
   // NOT re-exported from the public `@barefootjs/client` top-level entry;

package/src/runtime/map-array-lazy.ts

@@ -65,6 +65,18 @@
  *   (a misclassification must be harmless, not silently wrong) and for the
  *   three stranding sequences it prevents, each reproduced before it existed.
  *
+ * **Index-driven bindings (#2859 follow-up).** A row's position is tracked
+ * on `entry.index`, updated on every reconcile whether or not any binding
+ * reads it. A plan that sets `indexDriven: true` (emitted when
+ * `LazyRowPlanData.readsIndex`) is telling the runtime that some binding of
+ * `applyItem` reads `entry.index` — so the reconciler also calls
+ * `applyItem` on a pure reorder (item unchanged, position changed), not only
+ * on an item change. This mirrors the eager `mapArray` runtime's per-row
+ * index SIGNAL (`ItemScope.setIndex`) with no per-row reactive resource: the
+ * reconciler already knows a row's position changed the same way it already
+ * knows its item changed, so re-delivering that fact through a signal would
+ * be exactly the redundant machinery this design exists to avoid.
+ *
  * **Plan (compiler-emitted) obligations:**
  * - `createRow` MUST write ALL bindings — item-driven AND outer-involving —
  *   with current values (it is CSR creation; it computes everything anyway)
@@ -126,6 +138,13 @@ export interface LazyRowEntry<T> {
   key: string
   primaryEl: HTMLElement
   item: T
+  /**
+   * The row's current position in the reconciled list (#2859 follow-up).
+   * Kept current on EVERY reconcile, whether or not the plan reads it —
+   * cheap bookkeeping, and it is what makes a bare reorder (no item change)
+   * detectable for `plan.indexDriven` loops.
+   */
+  index: number
   /** plan-owned: claimed DOM refs, null until the row's first item-driven write */
   refs: unknown | null
   /** plan-owned: per-binding last-value dedup state */
@@ -155,6 +174,16 @@ export interface LazyRowPlan<T> {
    *  nodeValue) to initialize its dedup value and write only where the
    *  computed value differs (read-compare-write, spec §9.3(1)). */
   applyOuter?(entries: ReadonlyArray<LazyRowEntry<T>>, seed: boolean): void
+  /**
+   * True when some binding, condition, or preamble-substituted dependency of
+   * this row reads the loop's INDEX (#2859 follow-up,
+   * `LazyRowPlanData.readsIndex`). Such a binding is always `readsItem`
+   * (compiler-side), so the runtime must also call `applyItem` when a row's
+   * POSITION changes with no item change — a plain reorder — not only when
+   * `!Object.is(oldItem, newItem)`. Absent/false for every other loop, which
+   * keeps a bare reorder exactly as cheap as before this widening.
+   */
+  indexDriven?: boolean
 }
 
 /**
@@ -268,6 +297,7 @@ export function mapArrayLazy<T>(
       // element and must not read primaryEl.
       primaryEl: undefined as unknown as HTMLElement,
       item,
+      index,
       refs: null,
       last: null,
     }
@@ -307,7 +337,7 @@ export function mapArrayLazy<T>(
           // rows carry a depth-suffixed name (#2753 Shape B).
           const ssrKey = el.getAttribute(keyAttrName)
           const key = ssrKey !== null ? ssrKey : getKey ? getKey(items[i], i) : String(i)
-          const entry: LazyRowEntry<T> = { key, primaryEl: el, item: items[i], refs: null, last: null }
+          const entry: LazyRowEntry<T> = { key, primaryEl: el, item: items[i], index: i, refs: null, last: null }
           entries.set(key, entry)
           list.push(entry)
         }
@@ -383,11 +413,24 @@ export function mapArrayLazy<T>(
         // setItem. `applyItem` runs after `entry.item` is updated, receives
         // the previous item, and is untracked (mixed bindings may read
         // outer signals; the applyOuter effect owns the reactive side).
-        if (!Object.is(existing.item, item)) {
+        const itemChanged = !Object.is(existing.item, item)
+        // A pure reorder (#2859 follow-up): the item is unchanged but the
+        // row's POSITION is, and `plan.indexDriven` says some binding reads
+        // it. `entry.index` is bookkept below regardless — only the
+        // `applyItem` call (and the stranding it implies) is conditional.
+        const indexChanged = plan.indexDriven === true && existing.index !== i
+        if (itemChanged) {
           const prevItem = existing.item
           existing.item = item
+          existing.index = i
           untrack(() => plan.applyItem(existing, prevItem))
           markStranded()
+        } else if (indexChanged) {
+          existing.index = i
+          // prevItem === item here: nothing but the position moved.
+          untrack(() => plan.applyItem(existing, item))
+        } else {
+          existing.index = i
         }
         desiredOrder.push(existing)
       } else {