From 97d7269ba544fdcde455e37e4fa556cb81cae03b Mon Sep 17 00:00:00 2001
From: PJ <ipriyanshujain@gmail.com>
Date: Mon, 27 Apr 2026 00:05:30 +0700
Subject: [PATCH] feat(spec): add whenRoute action gating helper

whenRoute(route, allowedRoutes, body) wraps an actions() generator
that returns [] unless route.current matches one of the allowed
values. Accepts a single route or an array.
---
 pkg/spec/src/actions.ts | 13 +++++++++++++
 pkg/spec/src/index.ts   |  1 +
 2 files changed, 14 insertions(+)

diff --git a/pkg/spec/src/actions.ts b/pkg/spec/src/actions.ts
index 9e2f160..1010ea3 100644
--- a/pkg/spec/src/actions.ts
+++ b/pkg/spec/src/actions.ts
@@ -17,6 +17,19 @@ export function actions(generator: () => Action[]): ActionGenerator {
   return globalThis.__sanderling__.actions(generator);
 }
 
+export function whenRoute(
+  routeExtractor: { readonly current: string | null },
+  routes: string | readonly string[],
+  body: () => Action[],
+): ActionGenerator {
+  const allowed = typeof routes === "string" ? [routes] : routes;
+  return actions(() => {
+    const current = routeExtractor.current;
+    if (current === null || !allowed.includes(current)) return [];
+    return body();
+  });
+}
+
 export function weighted(...entries: WeightedEntry[]): ActionGenerator {
   return globalThis.__sanderling__.weighted(...entries);
 }
diff --git a/pkg/spec/src/index.ts b/pkg/spec/src/index.ts
index f462d4d..e60355f 100644
--- a/pkg/spec/src/index.ts
+++ b/pkg/spec/src/index.ts
@@ -38,4 +38,5 @@ export {
   taps,
   waitOnce,
   weighted,
+  whenRoute,
 } from "./actions.ts";