@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/core/recommenders.ts

@@ -0,0 +1,166 @@
+// Recommenders' triggers and placement: an inline one is a placement rule
+// (a placeholder until it is near the viewport), a popup one opens on "added
+// to cart". In lbx-place with the reconciler, not in the entry: the entry
+// (main.ts) loads it on a page an inline recommender's urlMatch / active()
+// accepts, and at boot where a popup recommender is configured (its trigger
+// may fire on any page).
+
+import { mark, reportError } from './health';
+import { recallWidgetHeight } from './hold';
+import { addRule } from './reconciler';
+import { onFlush, schedule, scheduleIn } from './scheduler';
+import type { RecommenderConfigType } from '../types';
+import type { WidgetContext } from '../main';
+
+type Loaded = { mod: any; ctx: WidgetContext };
+type Run = (where: string, p: Promise<Loaded>, f: (m: Loaded) => unknown, onFail?: () => void) => unknown;
+export interface Reco {
+  id: string;
+  rc: RecommenderConfigType;
+  get: () => Promise<Loaded>;
+}
+
+const toArray = <X>(v: X | X[] | undefined): X[] => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+/** Each recommender's trigger; `setUp`: if one throws, the others still start. */
+export const startRecommenders = (recos: Reco[], run: Run, setUp: <X>(where: string, f: () => X) => X | null) => {
+  for (const { id, rc, get } of recos) {
+    if (rc.confirm) setUp(id, () => popupTrigger(rc, get, run));
+    else setUp(id, () => inlineRecommender(id, rc, get, run));
+  }
+  schedule();
+};
+
+/**
+ * Inline recommender: placed by a rule like everything else, but only a
+ * placeholder (reserved height) until it is two screens from the viewport.
+ * Then the chunk is loaded, the request made, and it renders into it. One
+ * screen was not enough: scrolling at ~2000 px/s (4x CPU, a 500 ms answer)
+ * it stood empty in view for ~230 ms; at two it is ready ~400 ms before
+ * (2026-10-11).
+ */
+function inlineRecommender(id: string, rc: RecommenderConfigType, get: () => Promise<Loaded>, run: Run) {
+  const re = rc.urlMatch ? new RegExp(rc.urlMatch) : null;
+  const page = rc.active ?? ((u: URL) => !re || re.test(u.pathname));
+  const io = new IntersectionObserver(
+    (entries) => {
+      for (const e of entries) {
+        if (!e.isIntersecting) continue;
+        io.unobserve(e.target);
+        const el = e.target as HTMLElement;
+        // Failed to load: no reserved gap, and not "ours present" for style-host.css.
+        const go = () =>
+          run(id, get(), ({ mod, ctx }) => mod.attach(ctx, el), () => {
+            el.style.minHeight = '';
+            el.dataset.state = 'empty';
+          });
+        // Within two screens while the page still loads (a short product page
+        // on a phone): after its load event, not competing with it.
+        if (document.readyState === 'complete') go();
+        else addEventListener('load', go, { once: true });
+      }
+    },
+    { rootMargin: '0px 0px 200% 0px' },
+  );
+  const items = () => {
+    try {
+      return rc.items!();
+    } catch (e) {
+      reportError(`${id} items`, e);
+      return [];
+    }
+  };
+  // Nothing to recommend for (yet) on a page of its URL: looked at again for
+  // a while. The host may fill in what items() reads after it inserts the
+  // node (Angular sets bound attributes in its update pass; a task of ours
+  // can run in between), and sensing sees nodes, not attributes.
+  let emptyOn = '';
+  let emptySince = 0;
+  addRule({
+    id,
+    // Level-triggered: an input widget with nothing to recommend for is not on the page.
+    active: (u) => {
+      if (!page(u)) return false;
+      if (!rc.items || items().length > 0) return true;
+      const now = performance.now();
+      if (emptyOn !== u.href) (emptyOn = u.href), (emptySince = now);
+      if (now - emptySince < 3000) scheduleIn(100);
+      return false;
+    },
+    anchors: toArray(rc.anchor),
+    position: rc.position ?? 'after',
+    settleMs: rc.settleMs,
+    create: () => {
+      const el = document.createElement('lbx-reco');
+      if (rc.rootClass) el.className = rc.rootClass;
+      el.dataset.state = 'idle';
+      // Block before its chunk (and CSS) exists, so the reserved height applies.
+      el.style.display = 'block';
+      const h = recallWidgetHeight(id) || rc.reserve || 0;
+      if (h) el.style.minHeight = `${h}px`;
+      io.observe(el);
+      return el;
+    },
+  });
+}
+
+/**
+ * Popup recommender opened by "added to cart", which the host only signals
+ * from the outside: a click on an add-to-cart control is the intent (which
+ * item), the host's own success notice appearing within windowMs is the
+ * confirmation. Neither alone opens it. The click already starts loading the
+ * chunk and asking for the item's recommendations, so both are there (or on
+ * their way) when the notice appears.
+ */
+function popupTrigger(rc: RecommenderConfigType, get: () => Promise<Loaded>, run: Run) {
+  if (!rc.intent) return reportError('reco popup', new Error('a popup recommender needs intent() in its _init.ts'));
+  let intent: { item: string; t: number } | null = null;
+  // Sensing sees nodes come and go, not attributes: a notice the host shows by
+  // a class (or style, hidden, open) on a node that stays is watched for while
+  // an intent waits, at most windowMs.
+  let watch: MutationObserver | null = null;
+  let unwatch = 0;
+  const watchNotice = () => {
+    watch ??= new MutationObserver(schedule);
+    watch.observe(document.documentElement, { attributes: true, subtree: true, attributeFilter: ['class', 'style', 'hidden', 'open', 'aria-hidden'] });
+    clearTimeout(unwatch);
+    unwatch = window.setTimeout(() => watch!.disconnect(), rc.windowMs ?? 10000);
+  };
+  addEventListener(
+    'click',
+    (e) => {
+      const t = e.target as Element | null;
+      if (!t || t.nodeType !== 1 || t.closest('[data-lbx]')) return;
+      let item: string | null = null;
+      try {
+        item = rc.intent!(t);
+      } catch (err) {
+        reportError('reco popup intent', err);
+      }
+      if (!item) return;
+      intent = { item, t: performance.now() };
+      watchNotice();
+      // The chunk and the request now: the notice confirms it a moment later (their cart request).
+      run('reco popup prefetch', get(), ({ mod, ctx }) => mod.prefetchPopup(ctx, item));
+    },
+    true,
+  );
+  // A notice counts when it appears: a node the host adds, or one it keeps and
+  // shows again (a class toggled back on) after it stopped matching.
+  let shown = new Set(document.querySelectorAll(rc.confirm!));
+  onFlush(() => {
+    const now = new Set(document.querySelectorAll(rc.confirm!));
+    if (!now.size && !shown.size) return;
+    const appeared = [...now].filter((n) => !shown.has(n));
+    shown = now;
+    for (const n of appeared) {
+      if (!intent || performance.now() - intent.t > (rc.windowMs ?? 10000)) continue;
+      const { item } = intent;
+      intent = null;
+      watch?.disconnect();
+      const rect = n.getBoundingClientRect();
+      mark(`reco popup trigger ${item}`);
+      run(`reco popup`, get(), ({ mod, ctx }) => mod.openPopup(ctx, item, rect, n));
+    }
+  });
+}

package/src/core/reconciler.ts

@@ -0,0 +1,397 @@
+// Level-triggered placement engine. Each rule is a pure description of
+// "when X, our element should sit at anchor Y". reconcile() converges the page
+// to that description and is safe to run at any time, any number of times.
+
+// Booting after `load` (script injected late by the host app): the framework has hydrated already, so anchors that exist on our first pass
+// are stable and need no settle wait. Read at the entry's boot (this module arrives later, in lbx-place).
+import { lateBoot } from './boot-state';
+import { documentMayHydrate, hasFiber, OWN_ATTR, watchOwnRemovals, wholeDocument } from './own';
+import { onFlush, scheduleIn, scheduleNow } from './scheduler';
+import { bump, health, mark, reportError } from './health';
+
+export type Position = 'prepend' | 'append' | 'before' | 'after';
+
+export interface Rule {
+  id: string;
+  /** Is the rule applicable to the current page? Pure, cheap. */
+  active: (url: URL) => boolean;
+  /** Anchor candidates, most specific first. */
+  anchors: string[];
+  position: Position;
+  /**
+   * The anchor node must exist unchanged (same identity) for this long before
+   * we insert. Protects against frameworks that re-create or wipe the DOM
+   * right after we land (Angular destructive re-render, React hydration).
+   */
+  settleMs?: number;
+  create: () => HTMLElement;
+}
+
+const rules: Rule[] = [];
+// Rules whose element we placed and then lost to a host re-render. The anchor
+// that replaces the lost one is the framework's client render: no settle wait
+// (otherwise every re-render shows a blank gap for settleMs).
+const lost = new Set<string>();
+const placedOn = new Map<string, Element>();
+// Our element per rule. When the host removes it (re-render, hydration) we put
+// the same instance back: its DOM state and any in-flight user action survive
+// (a click between our first render and their hydration is not lost).
+const instances = new Map<string, HTMLElement>();
+const firstSeen = new WeakMap<Element, number>();
+const insertLog = new Map<string, number[]>();
+const pausedUntil = new Map<string, number>();
+
+// Server-rendered framework roots. Until the framework has hydrated the markup
+// around an anchor, a node of ours there is a hydration mismatch: React
+// re-renders the root on the client (a full-page flash), Vue drops our node,
+// Angular reports NG0500. The host CSS hold covers the wait. Any other React
+// root is known by its container key once createRoot/hydrateRoot has run
+// (reactContainer(), below).
+const REACT_ROOTS = '#__next, #___gatsby, [data-reactroot]';
+const VUE_ROOTS = '#__nuxt, [data-server-rendered]';
+// Astro removes `ssr` once an island has hydrated.
+const SSR_ROOTS = `${REACT_ROOTS}, ${VUE_ROOTS}, [ng-server-context], astro-island[ssr]`;
+const keyOf = (n: object, prefix: string) => Object.keys(n).find((k) => k.startsWith(prefix));
+
+const CONTAINER = '__reactContainer$';
+/**
+ * The React root around `el`: the element createRoot / hydrateRoot was given
+ * (React sets its container key on it), whatever its selector (a plain `#root`
+ * is as common as `#__next`), or the document React hydrates as a whole.
+ */
+const reactContainer = (el: Element): Element | Document | null => {
+  for (let a: Element | null = el; a; a = a.parentElement) if (keyOf(a, CONTAINER)) return a;
+  return wholeDocument() ? document : null;
+};
+/**
+ * React's root has yet to commit its hydration (React 18 and 19; no such flag
+ * before). Fibers on the anchor do not say so: a render React suspends and
+ * restarts leaves those of the render it threw away (a production storefront, 2026-10-02:
+ * ours in that markup was React error #418, the root rendered anew).
+ */
+const reactDehydrated = (c: Element | Document | null) => {
+  const k = c && keyOf(c, CONTAINER);
+  return !!k && (c as any)[k]?.stateNode?.current?.memoizedState?.isDehydrated === true;
+};
+// A wait for the parse to end (hydrated(), below) needs a reconcile when it does.
+if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', () => scheduleIn(0), { once: true });
+// Turbo Drive caches a snapshot a tick after turbo:before-cache (Turbo 7.3+
+// has removed our data-turbo-temporary nodes by then; for older Turbo and
+// Turbolinks we remove them): nothing goes back in between. Our listener runs
+// before Turbo sets its tick, so two nested ticks land after the snapshot.
+// Or until Turbo has rendered the next page (turbo:render), if that is
+// sooner: the snapshot holds the body it replaced (detached, ours not in it
+// once placed in the new one), and a page that stays (a morphing refresh) is
+// the next page itself. Without that, ours was missing for a frame or two
+// after every Turbo render between our pages (found by Luma's Turbo
+// tests).
+let snapshotting = false;
+const endSnapshot = () => {
+  if (!snapshotting) return;
+  snapshotting = false;
+  scheduleNow();
+};
+const beforeCache = () => {
+  snapshotting = true;
+  for (const el of document.querySelectorAll(`[${OWN_ATTR}][data-turbo-temporary]`)) el.remove();
+  // (Turbolinks snapshots in a setTimeout of 1 ms: a few ms more covers it.)
+  setTimeout(() => setTimeout(endSnapshot, 5));
+};
+addEventListener('turbo:before-cache', beforeCache);
+addEventListener('turbolinks:before-cache', beforeCache);
+addEventListener('turbo:render', endSnapshot);
+addEventListener('turbolinks:render', endSnapshot);
+const sinceLoad = () => {
+  const end = (performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming | undefined)?.loadEventEnd;
+  return end ? performance.now() - end : -1;
+};
+/** The longest we wait: below the takeover's hold timeout, or the listing would never show. */
+const MAX_HYDRATION_WAIT = 3000;
+
+/**
+ * React has hydrated the markup at `node`: claimed it, or `node` is markup React
+ * does not own (HTML it set as a whole, a tag manager's) inside an element it
+ * has claimed, whose subtree it has therefore finished.
+ */
+const reactHydrated = (node: Element): boolean => {
+  if (hasFiber(node)) return true;
+  // A root container gets no fiber of its own (its key is set before hydration): its content's.
+  if (keyOf(node, CONTAINER)) return !!node.firstElementChild && reactHydrated(node.firstElementChild);
+  for (let c: Element = node, a = node.parentElement; a; c = a, a = a.parentElement) {
+    if (hasFiber(a)) return !inDehydratedSuspense(c);
+    if (keyOf(a, CONTAINER)) return false; // up to the root: nothing claimed yet
+  }
+  return false;
+};
+
+/** In a boundary React has not hydrated yet, at any level above `el`. */
+const inAnyDehydratedBoundary = (el: Element) => {
+  for (let c: Element | null = el; c && c !== document.body; c = c.parentElement) if (inDehydratedSuspense(c)) return true;
+  return false;
+};
+
+/**
+ * Inside a Suspense boundary (between React's `<!--$-->` … `<!--/$-->`
+ * markers) whose content React has not claimed yet: selective hydration does
+ * the shell first, so the parent's fiber says nothing about the boundary.
+ */
+const inDehydratedSuspense = (el: Element): boolean => {
+  // React 19.2 streaming: content waits in a hidden <div id="S:…"> until it is revealed into its boundary.
+  const staged = el.closest('div[hidden][id^="S:"]');
+  if (staged && !hasFiber(staged)) return true;
+  // Suspense ($ $? $! $~) and Activity (&) boundaries hydrate on their own.
+  const open = (d: string) => d === '$' || d === '$?' || d === '$!' || d === '$~' || d === '&';
+  const close = (d: string) => d === '/$' || d === '/&';
+  let depth = 0;
+  for (let n = el.previousSibling; n; n = n.previousSibling) {
+    if (n.nodeType !== 8) continue;
+    const d = (n as Comment).data;
+    if (close(d)) depth++;
+    else if (open(d) && depth-- === 0) {
+      // Our boundary: hydrated once React has claimed its last element (it
+      // claims siblings in order, yielding in between: an earlier one says
+      // nothing about the rest).
+      let last: Element | null = null;
+      for (let m = n.nextSibling, level = 0; m; m = m.nextSibling) {
+        // Not ours: a node we placed `after` the boundary's last element is not React's.
+        if (m.nodeType === 1 && level === 0 && !(m as Element).hasAttribute(OWN_ATTR)) last = m as Element;
+        if (m.nodeType !== 8) continue;
+        const e = (m as Comment).data;
+        if (open(e)) level++;
+        else if (close(e) && level-- === 0) break;
+      }
+      return !(last && hasFiber(last));
+    }
+  }
+  return false;
+};
+
+/**
+ * React is hydrating the root around the anchor (hydrateRoot has been called:
+ * the container carries React's key): past the cap we keep waiting, because
+ * inserting would make React re-render the whole root. The hold may time out
+ * meanwhile (their listing shows); ours is placed once React is done.
+ */
+const reactHydrating = (anchor: Element, age: number) => {
+  return age <= MAX_REACT_WAIT && reactDehydrated(reactContainer(anchor));
+};
+/** However long React takes, not longer than this. */
+const MAX_REACT_WAIT = 15_000;
+
+/**
+ * Angular will hydrate the server's markup around the anchor (a component
+ * there still has its hydration key): past the cap we keep waiting, as for
+ * React. A node of ours in it is NG0500 in a development build, and in
+ * production Angular binds the server's next node to the wrong element.
+ */
+const ngHydrating = (anchor: Element, pos: Position, age: number) => {
+  if (age > MAX_REACT_WAIT) return false;
+  const node = pos === 'before' || pos === 'after' ? anchor.parentElement ?? anchor : anchor;
+  return !!node.closest('[ng-server-context][ngh], [ng-server-context] [ngh]');
+};
+
+/**
+ * SvelteKit: the root is the element holding its boot script
+ * (`kit.start(app, element, …)`, at the end of the body), and Svelte 5
+ * hydrates it as a whole: a node of ours anywhere in it before then fails the
+ * hydration, and Svelte renders the whole page anew on the client (a flash,
+ * the header's state lost). Its router starts once hydration is done and sets
+ * `history.scrollRestoration = 'manual'` then (back to 'auto' on beforeunload:
+ * remembered). Until the boot script is parsed, its preloaded entry in <head> says so.
+ */
+// undefined: not looked for yet, or the document is still parsing (its boot script may come).
+let svelteKit: Element | null | undefined;
+let svelteKitStarted = false;
+const svelteKitRoot = (anchor: Element) => {
+  if (svelteKit === undefined) {
+    const boot = [...document.scripts].find((s) => !s.src && s.text.includes('__sveltekit_') && s.text.includes('.start('));
+    if (boot || document.readyState !== 'loading') svelteKit = boot?.parentElement ?? null;
+  }
+  return svelteKit?.contains(anchor) ? svelteKit : null;
+};
+const svelteKitParsing = () => svelteKit === undefined && !!document.querySelector('link[href*="/immutable/entry/start."]');
+
+const hydrated = (anchor: Element, pos: Position) => {
+  if (svelteKitRoot(anchor)) return (svelteKitStarted ||= history.scrollRestoration === 'manual');
+  // Any React root (its container key), and not before it has committed its hydration.
+  const react = reactContainer(anchor);
+  if (reactDehydrated(react)) return false;
+  const root = anchor.closest(SSR_ROOTS) ?? (react !== document ? (react as Element | null) : null) ?? (wholeDocument() ? document.body : null);
+  // Still parsing a Next.js page (its whole-document flag comes at the end of
+  // <body>, its assets are visible before) or a SvelteKit page (its boot
+  // script is at the end of <body>): wait for the parse. Any other page is
+  // placed at once (before first paint, as the hold intends).
+  if (!root) return !documentMayHydrate() && !svelteKitParsing();
+  // For a sibling insert, the parent's state is what counts (all of its children claimed).
+  const node = pos === 'before' || pos === 'after' ? anchor.parentElement ?? anchor : anchor;
+  // Frameworks with a signal: wait for it (the cap bounds the wait).
+  // For a sibling insert, the anchor's own place counts too: its parent may be
+  // claimed while the anchor sits in a boundary React has not hydrated yet.
+  if (root === document.body || root === react || root.matches(REACT_ROOTS)) {
+    // Next.js pages router: its hydration measure (it stays; the marks it is
+    // made of do not) says the shell is done, not the Suspense boundaries.
+    const shell = performance.getEntriesByName('Next.js-hydration', 'measure').length ? !inAnyDehydratedBoundary(node) : reactHydrated(node);
+    return shell && (node === anchor || !inDehydratedSuspense(anchor));
+  }
+  if (root.matches(VUE_ROOTS)) {
+    const vue = (root as any).__vue_app__;
+    const nuxt = vue?.config?.globalProperties?.$nuxt;
+    if (nuxt) return nuxt.isHydrating === false; // Nuxt 3 hydrates async parts after mount
+    return !!(vue || (root as any).__vue__); // Vue 3 / Vue 2: mounted
+  }
+  // Angular: the root component exists (its first tick hydrates the shell in
+  // that task), and no component around the anchor still has its hydration
+  // key (`ngh`, removed once Angular has read it): a lazy route's page
+  // hydrates later than the shell, when its chunk has arrived.
+  if ('__ngContext__' in root) {
+    const waiting = node.closest('[ngh]');
+    return !waiting || waiting === root || !root.contains(waiting);
+  }
+  if (root.localName === 'astro-island') return false; // it drops `ssr` when hydrated (the cap bounds the wait)
+  // No signal (a framework we cannot see): after load and a moment.
+  return lateBoot || sinceLoad() > 1000;
+};
+
+export const addRule = (r: Rule) => rules.push(r);
+
+/** The element (the server's, adopted) is this rule's instance: it stays where it is. */
+export const claim = (id: string, el: HTMLElement) => void instances.set(id, el);
+
+const isPlaced = (el: Element, anchor: Element, pos: Position) => {
+  switch (pos) {
+    case 'prepend':
+    case 'append':
+      return el.parentElement === anchor;
+    case 'before':
+      return el.nextElementSibling === anchor;
+    case 'after':
+      return el.previousElementSibling === anchor;
+  }
+};
+
+const place = (el: Element, anchor: Element, pos: Position) => {
+  if (pos === 'prepend') anchor.prepend(el);
+  else if (pos === 'append') anchor.append(el);
+  else if (pos === 'before') anchor.before(el);
+  else anchor.after(el);
+};
+
+/** Detect a fight with the host (it keeps removing us) and back off. */
+const allowInsert = (id: string, now: number) => {
+  if ((pausedUntil.get(id) || 0) > now) return false;
+  const log = (insertLog.get(id) || []).filter((t) => now - t < 3000);
+  log.push(now);
+  insertLog.set(id, log);
+  if (log.length > 5) {
+    bump(health.fights, id);
+    const backoff = 500 * 2 ** Math.min(health.fights[id], 5);
+    pausedUntil.set(id, now + backoff);
+    insertLog.set(id, []);
+    scheduleIn(backoff + 10);
+    return false;
+  }
+  return true;
+};
+
+/**
+ * Not yet: the framework around the anchor has yet to hydrate it (bounded;
+ * never for a re-insert, except inside an Astro island: its `ssr` is exact,
+ * and Astro's ClientRouter brings a swapped-in page's anchor back as server
+ * markup in an island that hydrates after the swap; ours in it then fails
+ * that hydration and the island renders anew).
+ */
+const mustWait = (r: Rule, anchor: Element, age: number) =>
+  (!lost.has(r.id) || !!anchor.closest('astro-island[ssr]')) && !hydrated(anchor, r.position) && (age < MAX_HYDRATION_WAIT || reactHydrating(anchor, age) || ngHydrating(anchor, r.position, age));
+
+const reconcileRule = (r: Rule, url: URL, now: number) => {
+  const mine = [...document.querySelectorAll(`[${OWN_ATTR}="${r.id}"]`)];
+  if (!r.active(url)) {
+    instances.delete(r.id); // leaving the route: a fresh element next time
+    placedOn.delete(r.id); // and no reference to the old page's nodes
+    mine.forEach((el) => el.remove());
+    if (mine.length) mark(`remove ${r.id}`);
+    return;
+  }
+  let anchor: Element | null = null;
+  for (const sel of r.anchors) if ((anchor = document.querySelector(sel))) break;
+  if (!anchor) {
+    bump(health.anchorMisses, r.id);
+    return;
+  }
+  // A server-rendered element (server-side rendering) is the page's own: it wins over one we
+  // placed. Otherwise only our own instance counts: a copy of it (a Turbo
+  // snapshot restored) is not live, it goes.
+  const keep =
+    mine.find((el) => el.hasAttribute('data-lbx-ssr') && isPlaced(el, anchor!, r.position)) ??
+    mine.find((el) => el === instances.get(r.id) && isPlaced(el, anchor!, r.position));
+  if (!keep && placedOn.has(r.id) && placedOn.get(r.id) !== anchor) lost.add(r.id);
+  mine.filter((el) => el !== keep).forEach((el) => el.remove());
+  if (keep) {
+    // The server's element becomes ours (it drops its marker once hydrated).
+    instances.set(r.id, keep as HTMLElement);
+    if (!keep.hasAttribute('data-turbo-temporary')) keep.setAttribute('data-turbo-temporary', '');
+    // Placed while parsing, before the page said React hydrates it as a whole
+    // (Remix, React Router 7 and Hydrogen say so at the end of <body>): out
+    // again until React has it, or React re-renders the document. Their
+    // scripts run after the parse, so it is gone before hydration starts.
+    // Within the same limits as the wait before an insert (React never hydrating must not keep ours out).
+    if (!firstSeen.has(anchor)) firstSeen.set(anchor, now);
+    if (!keep.hasAttribute('data-lbx-ssr') && wholeDocument() && mustWait(r, anchor, now - (firstSeen.get(anchor) ?? now))) {
+      keep.remove();
+      scheduleIn(200);
+    }
+    return;
+  }
+
+  if (!firstSeen.has(anchor)) firstSeen.set(anchor, now);
+  const age = now - firstSeen.get(anchor)!;
+  // No settle wait on our first pass after load, or for a node the host just re-rendered away.
+  const settle = (lateBoot && health.reconciles === 0) || lost.has(r.id) ? 0 : r.settleMs ?? 0;
+  if (age < settle) {
+    scheduleIn(settle - age + 5);
+    return;
+  }
+  if (mustWait(r, anchor, age)) {
+    scheduleIn(200);
+    return;
+  }
+  if (snapshotting || !allowInsert(r.id, now)) return;
+  const prev = instances.get(r.id);
+  const el = prev && !prev.isConnected ? prev : r.create();
+  instances.set(r.id, el);
+  el.setAttribute(OWN_ATTR, r.id);
+  // Turbo Drive: not in its page snapshots (a restored copy would sit next to ours).
+  el.setAttribute('data-turbo-temporary', '');
+  place(el, anchor, r.position);
+  placedOn.set(r.id, anchor);
+  lost.delete(r.id);
+  bump(health.inserts, r.id);
+  mark(`insert ${r.id}`);
+};
+
+// Inserts are counted per URL: on an SPA (or htmx, Turbo) host every
+// navigation re-renders the area, and a shopper going back three times in a
+// few seconds is not a host fighting us. A host that does fight us keeps
+// removing ours on the same URL.
+let countedFor = location.href;
+
+export const reconcile = () => {
+  const t0 = performance.now();
+  if (location.href !== countedFor) {
+    countedFor = location.href;
+    insertLog.clear();
+  }
+  const url = new URL(location.href);
+  for (const r of rules) {
+    try {
+      reconcileRule(r, url, t0);
+    } catch (e) {
+      reportError(`rule ${r.id}`, e);
+    }
+  }
+  health.reconciles++;
+};
+
+onFlush(reconcile);
+// A node of ours the host removes goes back before the next paint (core/sense.ts).
+watchOwnRemovals();

package/src/core/result.ts

@@ -0,0 +1,73 @@
+// Results as templates see them: `r.a` = the hit's fields (discovery hits are
+// flat: `@id`, `@type`, `@title`, then catalog fields), `r.c` = computed
+// attributes (from `_global.computedAttributes`, set in _init.ts), evaluated
+// on first access.
+
+import type { Hit } from '../api';
+import type { Result } from '../types';
+
+/** First value of a field that may be an array. */
+export const first = (v: unknown): any => (Array.isArray(v) ? v[0] : v);
+
+/**
+ * A catalog URL only if it leads to a web page (http(s), or relative): a
+ * `javascript:` or `data:` value in feed data must never become a link.
+ * Browsers ignore tabs and newlines inside a scheme, so they are too.
+ */
+export const safeUrl = (u: unknown) => {
+  const s = String(first(u) ?? '').trim();
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(s.replace(/[\u0000-\u0020]/g, ''))?.[1].toLowerCase();
+  return !scheme || scheme === 'http' || scheme === 'https' ? s : '';
+};
+
+const DEFAULTS: Record<string, (r: Result) => unknown> = {
+  id: (r) => r.id,
+  title: (r) => first(r.a['@title']) ?? '',
+  url: (r) => r.a.url ?? r.a.web_url,
+  image: (r) => first(r.a['lbx:image'] ?? r.a.image_url ?? r.a.image_link) ?? '',
+  price: (r) => first(r.a['lbx:price'] ?? r.a.price),
+};
+
+export const resultFactory = (computed: Record<string, (r: Result) => unknown> = {}) => {
+  const fns = { ...DEFAULTS, ...computed };
+  return (hit: Hit): Result => {
+    const r = { id: hit['@id'], type: hit['@type'], a: hit } as Result;
+    const c: Record<string, unknown> = {};
+    for (const [k, fn] of Object.entries(fns))
+      Object.defineProperty(c, k, {
+        enumerable: true,
+        configurable: true,
+        get() {
+          // `url` becomes links and navigations, whoever computes it (an integration's own too).
+          const v = k === 'url' ? safeUrl(fn(r)) : fn(r);
+          Object.defineProperty(c, k, { value: v, enumerable: true });
+          return v;
+        },
+      });
+    r.c = c;
+    return r;
+  };
+};
+
+/**
+ * A suggestion that goes somewhere: products always (their tile has actions),
+ * other types (category, brand, ...) only with a URL other than the site's
+ * root. Feeds carry such records (a brand with web_url "/" and no logo):
+ * shown, they send the shopper to the homepage. A query suggestion goes to
+ * the site's search with its text (the API gives it no URL): it needs the text.
+ */
+export const navigable = (r: Result) => {
+  if (r.type === 'product') return true;
+  if (r.type === 'query') return !!plain(r.c.title).trim();
+  const u = String(r.c.url ?? '').trim();
+  if (!u) return false;
+  try {
+    const url = new URL(u, 'https://x.invalid/');
+    return !(url.pathname === '/' && !url.search);
+  } catch {
+    return false;
+  }
+};
+
+/** Text without highlighting markup. */
+export const plain = (s: unknown) => String(first(s) ?? '').replace(/<\/?em>/g, '');