[Enhancement] Strongly-Typed Step Outcomes and Locators

[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 autocomplete or type safety
    const input = lastOutcome.locator as Locator; // Manual typecast required
    await input.fill('value');
  }
})

Proposed Solution

Refactor the generic types of the Play builder class so that the list of outcomes defined in .detect() or .attempt() maps to a strongly-typed union. Downstream steps 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).

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

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

🔗 Related PRs

#12 - feat: implement Play, Playbook, Director, SyncStrategy [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.