docs(revalidate): canonical ctx.isAction idioms + shop-demo adoption - #559

Problem

ctx.isAction() is the rename-safe way to match server actions in a revalidate predicate, but the canonical guidance was thin and partly self-contradictory: the ShouldRevalidateFn JSDoc taught a single ambiguous ||-vs-?? example, and the shop demo modeled actionId?.includes("Cart") ?? false — valid, but rename-fragile, and not what a consumer should reach for first.

This PR lands the recommendation where consumers actually look (the JSDoc that shows on IDE hover + the rango skill) and adopts it in the two shop demo predicates where the conversion is a clean win. It deliberately does not sweep the rest of the suite — see Notes.

What a consumer sees differently

The hover doc on revalidate(...) and the rango skill now teach two named idioms instead of one ambiguous example:

The first draft of the suppress idiom wrote ctx.isAction(X) || ctx.stale; since stale?: boolean is optional, that evaluates to undefined — i.e. defer, not suppress — whenever stale is absent. Fixed to the bare form, so the JSDoc and skill exemplars are now identical.

Shop demo adoption (the clean wins)

// before
revalidate(({ actionId }) => actionId?.includes("Cart") ?? false)

// after — rename-safe and shorter (isAction is already a strict boolean, so the
// old `?? false` tail was a no-op)
import * as ShopActions from "../handlers/shop/actions/shop.actions.js";
revalidate((ctx) => ctx.isAction(ShopActions))

Both shop sites are pure-suppress, so the conversion is exactly equivalent (verified by e2e).

Code-change summary

• packages/rangojs-router/src/types/handler-context.ts — ShouldRevalidateFn JSDoc teaches the two named idioms with ctx.isAction.
• packages/rangojs-router/skills/rango/SKILL.md — matching defer/suppress note.
• tests/vite-rsc-demo/src/urls/shop.tsx — 2 pure-suppress predicates → ctx.isAction(ShopActions) / ctx.isAction(addToCart, addToCartWithResult), + 1 import * as ShopActions.
• tests/cloudflare-basic/src/urls.tsx — drop a redundant : ResponseHandlerContext annotation + its now-unused import (inline path.* callbacks are contextually typed; proven clean under strict:true).

Test plan

• typecheck — vite-rsc-demo + cloudflare-basic
• unit — 3562 passed (the router change is JSDoc-only)
• lint / format — clean
• e2e dev + production — shop-actions + shop-loaders, 22 passed (pins the kept isAction(ShopActions) cart-revalidation and shared-loader-freshness in both modes)

Notes / deliberately not done

• kanban/todos/loaders demos kept on actionId?.includes(...). actionId substring matching is supported floor API — the typesafety skill calls it the "floor and escape hatch" — not a deprecated pattern, so a demo using it isn't a hygiene violation. Those fixtures keep exercising that path through real action flows, and the isAction rewrite there needed a verbose ctx.actionId == null ? <fallback> : false guard that read worse than the original. The recommendation lives in the docs; the suite keeps its pattern variety.
• No skill-docs sweep. ~14 other skill snippets still show actionId?.includes in the defer form; the API path has dedicated e2e (action-id-resolution.test.ts, is-action.test.ts), and two snippets must stay substring regardless: the loader return-protocol section (built on actionId's string | undefined shape — isAction would make ?? false dead code) and server-actions' startsWith("src/actions/account/") (matches unimported modules, which isAction cannot express).