@rangojs/router 0.4.0 → 0.4.2

package/skills/caching/SKILL.md

@@ -267,6 +267,45 @@ const router = createRouter({
 });
 ```
 
+### Search param key filtering (`cache.searchParams`)
+
+By default every non-reserved query param keys the cache, so
+`?utm_source=tw` and `?utm_source=ig` occupy separate slots in every tier.
+The global `searchParams` option controls which params participate in default
+cache-key generation:
+
+```typescript
+import { createRouter, TRACKING_SEARCH_PARAMS } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  cache: {
+    store,
+    // "all" (default) | "none" | { include: string[] } | { exclude: string[] }
+    searchParams: { exclude: TRACKING_SEARCH_PARAMS },
+  },
+});
+```
+
+- **Key-only**: `ctx.searchParams` and the request URL are untouched — handlers
+  and loaders still see the full query string.
+- **Matching**: exact names plus a `*` SUFFIX wildcard (`"utm_*"`). No RegExp.
+- **All tiers**: segment, document, response, PPR shell capture/lookup, the
+  baked-shell manifest gate (a URL whose only params are excluded ones now
+  matches the prerendered shell), and `"use cache"` ctx key normalization.
+- **`cache({ key })` override wins**: a custom key bypasses the filter along
+  with the rest of default key generation.
+- **The footgun**: excluding a param promises the rendered output does not
+  depend on it. If it does, the first variant is cached and served to everyone.
+  That is why the default is `"all"`.
+- `TRACKING_SEARCH_PARAMS` (also exported from `@rangojs/router/cache`) covers
+  `utm_*`, `gclid`, `fbclid`, `msclkid`, `ttclid`, `mc_cid`/`mc_eid`, and the
+  other common click-id params.
+
+Global-only by design — the per-route "this page varies only by `q`" case is
+already expressible with `cache({ key })`.
+
 ## Cache Stores
 
 ### Memory Store

package/skills/cloudflare/SKILL.md

@@ -129,8 +129,10 @@ export const router = createRouter<AppBindings>({
 });
 ```
 
-KV is required for durable PPR shells. `CFCacheStore` without `kv` can still
-cache segment/response entries in the Cache API, but its shell family is inert.
+PPR shells use Cache API as the per-colo L1 and KV as the durable cross-colo
+L2; a KV hit promotes the coupled shell envelope back into L1. KV remains
+required for this family. `CFCacheStore` without `kv` can still cache
+segment/response entries in Cache API, but its shell family is inert.
 
 ## Commands
 

package/skills/comparison/references/framework-comparison.md

@@ -542,7 +542,13 @@ analog but operates on loader/query reload, not RSC-segment render.
 `<Link prefetch="hover|viewport|render|adaptive|none">` (default: the router's
 `defaultPrefetch`, `"none"` in development and `"viewport"` in production), plus
 `prefetchKey` (`":source"` scopes a prefetch to the originating page for routes
-whose response branches on `currentUrl`). The distinguishing part is the stability
+whose response branches on `currentUrl`). Intercepted plain `<a href>` elements
+inside the router basename follow the same default; common static-resource
+extensions are excluded unless `data-prefetch="true"` identifies an application
+route, and `data-prefetch="false"` or `"none"` opts out unsafe GET links. A
+container with `data-prefetch-scope="false"` or `"none"` is a hard subtree boundary for both
+Links and plain anchors, so one annotation suppresses speculative work for a
+whole navigation section. The distinguishing part is the stability
 gating: a queued prefetch (`viewport`/`render`) will not fire until **both** the
 main thread is idle (`requestIdleCallback`, 200ms fallback) **and**
 `waitForViewportImages()` resolves — in-viewport images that are not `.complete`

package/skills/links/SKILL.md

@@ -423,6 +423,30 @@ Don't edit the file by hand — re-run codegen when patterns change.
 }
 ```
 
+## Prefetch boundaries
+
+`Link` follows its `prefetch` prop or the router's `defaultPrefetch`; eligible
+plain anchors follow the router default. When a whole DOM section must never
+speculate, mark its container instead of repeating per-link opt-outs:
+
+```tsx
+<section data-prefetch-scope="none">
+  <Link to="/activity" prefetch="viewport">
+    Activity
+  </Link>
+  <a href="/export">Export</a>
+</section>
+```
+
+The scope is a hard opt-out for every descendant Link and plain anchor; `"false"`
+and `"none"` are equivalent. An explicit `prefetch` prop or
+`data-prefetch="true"` cannot override it, and navigation still works normally.
+Use `data-prefetch="false"` or `"none"` directly on a plain anchor when only that
+anchor is unsafe. Dynamic scope changes re-evaluate only descendant anchors and
+mounted viewport/render Links. Links share one document-level scope observer,
+not one observer per Link or container. Adding a scope cannot recall work already
+queued or in flight; removing it re-arms both Link types.
+
 ## When to use what
 
 | Context          | API                                                | Resolves                                  | Use for                                                          |

package/skills/ppr/SKILL.md

@@ -37,9 +37,9 @@ PPR is a DOCUMENT-level property declared on the page route via the `ppr` path
 option. Serving is **integral to the router** — there is nothing to mount. The
 only prerequisite is an app-level `createRouter({ cache })` store that
 implements the shell family (`getShell`/`putShell`): `MemorySegmentCacheStore`
-(dev/tests), `CFCacheStore` (Cloudflare KV), or `VercelCacheStore` (runtime
-cache). A ppr route on a store without the family stays on axis 1 with a
-once-per-key warning.
+(dev/tests), `CFCacheStore` (Cache API L1 + KV L2), or `VercelCacheStore`
+(runtime cache). A ppr route on a store without the family stays on axis 1 with
+a once-per-key warning.
 
 ```typescript
 import { createRouter, urls } from "@rangojs/router";
@@ -192,8 +192,29 @@ replay its eligible snapshot. In both cases `matchPartial()`:
 This is deliberately invisible to the browser: the response is the same
 `RscPayload` shape as any other partial navigation. Captured item/response values
 and loader-container pins are NOT replayed on this path, so loader reads stay
-live. A route's own `cache()` scope still resolves its normal store, key, TTL,
-SWR, tags, and condition; only the implicit PPR scope sees this behavior.
+live.
+
+A route's own `cache()` scope — including one inherited from an ancestor, the
+common app-wide storefront shape — COMPOSES with replay instead of disabling
+it. The explicit tier stays authoritative: its lookup runs first with its
+normal store, key, TTL, SWR, tags, and condition, and when it supplies the
+match the response reports `BYPASS; reason=explicit-cache-hit` (never a false
+replay `HIT`). Only when the explicit tier misses does the shell snapshot's
+canonical doc segment record supply the match and report `HIT`. To make that
+possible, a capture of such a route records the doc segment record into the
+shell snapshot IN ADDITION to the scope's normal store write; the record rides
+only inside the shell entry, never the real store. Two opt-outs stay absolute:
+`cache(false)` and a `condition()` returning false mean "do not serve this
+request's segments from any cache" — no doc record is captured for them and
+the seeded fallback never rescues a refused read. `cache(false)` is static, so
+replay reports `BYPASS; reason=cache-disabled` before performing a single
+shell read; a `condition()` refusal is request-time state, decided at the
+lookup itself and reported as the same `cache-disabled` post-match (the gate
+must not pre-decide a predicate that could flap between the two evaluations).
+An errored explicit read — a throwing `key()`, or a built-in store's swallowed
+backend failure (`CACHE_READ_ERROR`) — also never falls back: it renders
+uncached, exactly as without ppr.
+
 `transition({ when })` is evaluated from the
 matched manifest before route handlers on every PPR match, so it can vary by
 URL/params/action or middleware context without disabling replay; handler-set
@@ -202,6 +223,19 @@ nonce, and an absent/corrupt segment snapshot fall open to the ordinary partial
 path when encountered by the shell capture. A transition already replayed from
 an explicit cache tier remains frozen by that tier's normal semantics.
 
+Two more decisions are made before any shell-store read, so probes and
+prerendered routes never spend passive `getShell` I/O:
+
+- A partial request carrying neither `X-RSC-Router-Client-Path` nor `Referer`
+  (a curl probe, a synthetic monitor) can never produce a partial match; it
+  reports `BYPASS; reason=no-navigation-context`. Alert on replay hit-rate
+  with this in mind — such probes are not cache misses.
+- A `Prerender()` route's partial is served from the build-time prerender
+  store inside matching (a better-than-HIT outcome); it reports
+  `BYPASS; reason=prerender-store`. Its captures never record a doc segment
+  record (the prerender store short-circuits the cache write), so replay
+  seeding would be impossible anyway.
+
 Fresh and stale-within-SWR runtime shells replay. The stale read is passive: it
 uses `getShell(key, { claimRevalidation: false })`, does not claim SWR ownership,
 and cannot recapture HTML. A later document request owns the background
@@ -224,10 +258,35 @@ Partial responses expose the actual decision as `x-rango-ppr-replay`:
 `HIT; freshness=fresh|stale` or `BYPASS; reason=<bounded-token>`. With
 performance metrics enabled, the same decision appears as
 `ppr-navigation-replay` in `Server-Timing`. `HIT` means matching consumed the
-seeded segment record after it decoded successfully, not merely that a snapshot
-existed. An explicit `cache()` scope that supplies the match cannot produce a
-false HIT. There is still no Flight resume API; this is segment replay followed
-by normal Flight streaming, not reuse of the HTML `prelude`/`postponed` bytes.
+seeded segment record, not merely that a snapshot existed. Fragment-capable
+clients decode its stored ReactNode fields after the response arrives; if that
+decode fails, the client retries once through the server decode-and-evict path
+and disables further passthrough for that browser document. The retry replaces
+the fragment-capable response-cache slot, and a corrupt seeded snapshot is
+recaptured at the key that supplied it. An explicit `cache()` scope that supplies
+the match cannot produce a
+false HIT — it reports `explicit-cache-hit`. There is still no Flight resume
+API; this is segment replay followed by normal Flight streaming, not reuse of
+the HTML `prelude`/`postponed` bytes. Replayed segments do ride the partial
+payload as verbatim `__rangoFragment` envelopes (#700 fragment splice — the
+stored per-segment Flight strings are string-copied instead of
+deserialize→re-serialize per request); the client expands them at its
+navigation/prefetch decode chokepoints before anything renders, so they are
+consumer-invisible.
+
+The bounded bypass tokens, grouped by when they are decided:
+
+| Token                                                                             | Decided           | Meaning                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `method`, `dynamic`, `nonce`, `store-unavailable`, `passive-read-unsupported`     | pre-read          | request/route/store ineligible for replay                                                                                                                                                                                                                                 |
+| `no-navigation-context`                                                           | pre-read          | no `X-RSC-Router-Client-Path`/`Referer`; a partial match is impossible                                                                                                                                                                                                    |
+| `prerender-store`                                                                 | pre-read or match | `Prerender()` route served by its baked artifact (pre-read probe of the normal variant; reclassified post-match when the store actually served, either variant)                                                                                                           |
+| `intercept`                                                                       | match             | the navigation resolved to an intercept — replay is never armed for intercepts (they keep their normal cache path); no heal capture                                                                                                                                       |
+| `cache-disabled`                                                                  | pre-read or match | `cache(false)` (pre-read, static) or `condition()` false (decided at the lookup); consumer opt-out is absolute                                                                                                                                                            |
+| `read-error`, `no-entry`, `invalid-version`, `corrupt-entry`, `stale-build-entry` | shell read        | no usable shell entry (`no-entry`/`invalid-version`/`corrupt-entry`/`stale-build-entry` schedule the navigation-only heal capture)                                                                                                                                        |
+| `handler-live-holes`, `transition-when`, `no-segment-snapshot`                    | eligibility       | entry exists but its snapshot cannot replay (no canonical doc record, or handler/transition liveness); on a route with an enabled `cache()` scope, `no-segment-snapshot` heals when the lookup did not refuse (a `condition()` false-at-capture entry becomes replayable) |
+| `explicit-cache-hit`                                                              | match             | the route's own `cache()` tier supplied the match                                                                                                                                                                                                                         |
+| `snapshot-miss`                                                                   | match             | an eligible snapshot was seeded but matching did not consume it                                                                                                                                                                                                           |
 
 ### Capture-generation invalidation
 
@@ -295,9 +354,10 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
 - A ppr-declared route that CANNOT be honored (missing shell store family,
   per-request nonce) serves plain axis 1 with NO header and warns once per
   key — no header + a declared `ppr` means look for that warning.
-- On Cloudflare, `CFCacheStore` WITHOUT a KV namespace has an inert shell
-  family (the shell tier is KV-only): every ppr route stays `MISS` forever.
-  The store warns once per isolate — bind KV
+- On Cloudflare, `CFCacheStore` reads PPR shells from the per-colo Cache API,
+  falls through to KV on a miss, and promotes the KV hit back into that colo.
+  WITHOUT a KV namespace its shell family remains inert: every ppr route stays
+  `MISS` forever. The store warns once per isolate — bind KV
   (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store.
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
@@ -307,6 +367,11 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   later request. In dev, with `debugPerformance` on, the
   last capture outcome for a key also rides the next document GET's
   `Server-Timing` as `ppr-capture;desc="…"`.
+- For deployed Cloudflare tier diagnostics, build with
+  `INTERNAL_RANGO_DEBUG=1` and run `wrangler tail`. `[CFCacheStore][shell]`
+  JSON events distinguish L1 hit/miss, KV fallback/promotion, tier writes, and
+  marker rejection, with `cf-ray`/colo and read timings. The flag is baked at
+  build time; setting only a Worker runtime variable is too late.
 
 ### Unit / integration testing (public primitives)
 

package/skills/router-setup/SKILL.md

@@ -120,8 +120,13 @@ interface RangoOptions<TEnv> {
   // Set to false to disable prefetch caching.
   prefetchCacheTTL?: number | false;
 
-  // Default prefetch strategy for Links without a `prefetch` prop
-  // (dev: "none", production: "viewport"). Per-Link props win in both directions.
+  // Default prefetch strategy for Links without a `prefetch` prop and for
+  // intercepted plain anchors inside basename. false/none opts out; true allows
+  // an application route whose path has a common static-resource extension.
+  // data-prefetch-scope="false"/"none" on a container is a hard subtree
+  // opt-out for both Links and plain anchors, including explicit opt-ins.
+  // (dev: "none", production: "viewport").
+  // Per-Link props win over the router default, not a disabled container scope.
   defaultPrefetch?: "hover" | "viewport" | "render" | "adaptive" | "none";
 
   // CSP nonce provider (for router.fetch)

package/skills/testing/client-components.md

@@ -8,20 +8,21 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 
 ### Options — `RenderRouteOptions`
 
-| Field           | Type                                                                   | Meaning                                                                                                                                                                                                              |
-| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request`       | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                 |
-| `loaderData`    | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                       |
-| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                  |
-| `params`        | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                               |
-| `locationState` | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                         |
-| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                        |
-| `handle`        | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                       |
-| `routeMap`      | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                      |
-| `basename`      | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root. |
-| `mount`         | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                          |
-| `theme`         | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                        |
-| `nonce`         | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                |
+| Field             | Type                                                                   | Meaning                                                                                                                                                                                                                                       |
+| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`         | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                                          |
+| `loaderData`      | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                                                |
+| `loaders`         | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                                           |
+| `params`          | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                                                        |
+| `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                                                  |
+| `handles`         | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                                                 |
+| `handle`          | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                                                |
+| `routeMap`        | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                                               |
+| `basename`        | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root.                          |
+| `mount`           | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                                                   |
+| `theme`           | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                                                 |
+| `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
+| `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
 
 `RenderRouteSpec = { path, Component, layout?, loaderIds?, name? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational.
 

package/skills/vercel/SKILL.md

@@ -56,7 +56,7 @@ Per-function knobs go under `vercel` and are written into `.vc-config.json`:
 rango({
   preset: "vercel",
   vercel: {
-    runtime: "nodejs22.x", // default
+    runtime: "nodejs24.x", // default
     maxDuration: 30, // seconds, default
     memory: 1024, // MB (platform default when omitted)
     regions: ["fra1"], // pin regions (platform default when omitted)

package/src/browser/event-controller.ts

@@ -14,6 +14,7 @@ import {
   filterSegmentOrder,
   filterRouteSegmentIds,
 } from "./react/filter-segment-order.js";
+import { notifyListeners } from "./notify-listeners.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -269,6 +270,71 @@ export interface EventController {
   hadAnyConcurrentActions(): boolean;
 }
 
+type LocationChangeController = Pick<EventController, "getState" | "subscribe">;
+
+interface LocationChangeSubscription {
+  registrations: Map<
+    symbol,
+    { href: string; listener: (href: string) => void }
+  >;
+  notificationVersion: number;
+  unsubscribe: () => void;
+}
+
+const locationChangeSubscriptions = new WeakMap<
+  LocationChangeController,
+  LocationChangeSubscription
+>();
+
+/** Share one controller subscription across all location-change consumers. */
+export function subscribeToLocationChange(
+  eventController: LocationChangeController,
+  listener: (href: string) => void,
+): () => void {
+  let subscription = locationChangeSubscriptions.get(eventController);
+  if (!subscription) {
+    subscription = {
+      registrations: new Map(),
+      notificationVersion: 0,
+      unsubscribe: () => {},
+    };
+    locationChangeSubscriptions.set(eventController, subscription);
+    const currentSubscription = subscription;
+    subscription.unsubscribe = eventController.subscribe(() => {
+      const notificationVersion = ++currentSubscription.notificationVersion;
+      const nextHref = eventController.getState().location.href;
+      notifyListeners(
+        [...currentSubscription.registrations],
+        ([, registration]) => {
+          if (registration.href === nextHref) return;
+          registration.href = nextHref;
+          registration.listener(nextHref);
+        },
+        ([token, registration]) =>
+          currentSubscription.registrations.get(token) === registration,
+        () => notificationVersion === currentSubscription.notificationVersion,
+      );
+    });
+  }
+
+  const token = Symbol();
+  subscription.registrations.set(token, {
+    href: eventController.getState().location.href,
+    listener,
+  });
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    subscription!.registrations.delete(token);
+    if (subscription!.registrations.size > 0) return;
+    if (locationChangeSubscriptions.get(eventController) === subscription) {
+      locationChangeSubscriptions.delete(eventController);
+    }
+    subscription!.unsubscribe();
+  };
+}
+
 const DEFAULT_ACTION_STATE: TrackedActionState = {
   state: "idle",
   actionId: null,
@@ -308,7 +374,11 @@ function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
     if (timeout !== null) clearTimeout(timeout);
     timeout = setTimeout(() => {
       timeout = null;
-      listeners.forEach((listener) => listener());
+      notifyListeners(
+        [...listeners],
+        (listener) => listener(),
+        (listener) => listeners.has(listener),
+      );
     }, 0);
   };
 }
@@ -394,6 +464,39 @@ export function createEventController(
 
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
 
+  function notifyActionListenerSets(
+    subscriptions: Iterable<[string, Set<ActionStateListener>]>,
+  ): void {
+    const subscriptionSnapshots = [...subscriptions].map(
+      ([subscriptionId, listeners]) => ({
+        listenerSnapshot: [...listeners],
+        listeners,
+        subscriptionId,
+      }),
+    );
+    function* notifications(): Generator<{
+      listener: ActionStateListener;
+      listeners: Set<ActionStateListener>;
+      state: TrackedActionState;
+    }> {
+      for (const {
+        listenerSnapshot,
+        listeners,
+        subscriptionId,
+      } of subscriptionSnapshots) {
+        const state = getActionState(subscriptionId);
+        for (const listener of listenerSnapshot) {
+          yield { listener, listeners, state };
+        }
+      }
+    }
+    notifyListeners(
+      notifications(),
+      ({ listener, state }) => listener(state),
+      ({ listener, listeners }) => listeners.has(listener),
+    );
+  }
+
   function notifyAction(actionId: string) {
     const existing = actionNotifyTimeouts.get(actionId);
     if (existing !== undefined) {
@@ -403,12 +506,11 @@ export function createEventController(
       actionId,
       setTimeout(() => {
         actionNotifyTimeouts.delete(actionId);
-        for (const [subscriptionId, listeners] of actionListeners) {
-          if (matchesActionId(subscriptionId, actionId)) {
-            const state = getActionState(subscriptionId);
-            listeners.forEach((listener) => listener(state));
-          }
-        }
+        notifyActionListenerSets(
+          [...actionListeners].filter(([subscriptionId]) =>
+            matchesActionId(subscriptionId, actionId),
+          ),
+        );
       }, 0),
     );
   }
@@ -846,10 +948,7 @@ export function createEventController(
     // "addToCart"), not full entry actionIds. Passing them to notifyAction
     // would fail the suffix matcher — instead, notify each subscriber with
     // its own state.
-    for (const [subscriptionId, listeners] of actionListeners) {
-      const state = getActionState(subscriptionId);
-      listeners.forEach((listener) => listener(state));
-    }
+    notifyActionListenerSets(actionListeners);
   }
 
   // ========================================================================