Enhancement: Support Strongly-Typed Step Outcomes and Locators in Playbook Steps

[rickcedwhat-ai]

Problem Description

Currently, when sharing selectors/locators between adjacent steps (e.g. from .detect() to .prep()), the downstream step receives a loosely-typed lastOutcome object. Developers must manually cast the locator (e.g., lastOutcome.locator as Locator) and do not get autocomplete or type-safety on the outcome names:

.detect((page) => [
  { name: 'found', isSuccess: true, locator: page.getByRole('textbox', { name: 'Name' }) }
])
.prep('fill details', async (page, ctx, lastOutcome) => {
  if (lastOutcome?.name === 'found') { // No type safety or autocomplete on 'found'
    const input = lastOutcome.locator as Locator; // Requires manual cast
    await input.fill('value');
  }
})

Proposed Solution

Refactor the generic types of the Play builder class so that the list of outcomes provided in .detect() or .attempt() maps to a strongly-typed union. Downstream steps like .prep(), .attempt(), or .cleanup() should automatically infer:

1. lastOutcome.name (restricted to the literal string names defined in the prior step).
2. lastOutcome.locator (typed properly as Locator instead of any or unknown).

Example hypothetical signature:

class Play<
  TContext = any,
  TOutcomes extends { name: string; locator?: any } = any
> {
  detect<const TNewOutcomes extends ReadonlyArray<OutcomeDefinition>>(
    detector: (page: Page) => TNewOutcomes,
    options?: DetectOptions
  ): Play<TContext, TNewOutcomes[number]>;
}

[coderabbitai]

🔗 Related PRs

#12 - feat: implement Play, Playbook, Director, SyncStrategy [merged]
#22 - feat(play): positional attempt() API [merged]
#26 - feat(play)!: third-arg outcome and Play.run lastOutcome [merged]
#35 - feat: rename detectPageState → detectState, warn on empty relator [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[rickcedwhat-ai]

Blocked by #55 — this belongs in the future RBAC/playbook library, not in the core sugar primitives.