Scene-as-composer: builder step API, reusable modules, full Composer DSL on Scene

[kravetsone]

Summary

Redesign Scene as a first-class EventComposer. Each step becomes a sub-composer with lifecycle hooks plus the full bot DSL, and scenes can compose into one another via scene.extend(otherScene). Fully back-compat — every existing test (74) and existing API (step("message", handler), .ask(), .onEnter, enterSub/exitSub, …) keeps working unchanged.

// New: each step is a sub-composer
const confirm = new Scene().step("confirm", c => c
    .enter(ctx => ctx.send("Sure?", confirmKb))
    .callbackQuery("yes", ctx => ctx.scene.step.next())
    .callbackQuery("no",  ctx => ctx.scene.exit())
);

// Scenes compose: confirm's step inlines into checkout
const checkout = new Scene("checkout")
    .derive(async ctx => ({ user: await db.users.find(ctx.from!.id) }))
    .onEnter(ctx => analytics.track("checkout_start", ctx.user))
    .command("cancel", ctx => ctx.scene.exit())
    .step("review", c => c.message("Order looks good?").on("message", ctx =>
        ctx.scene.update({ ack: true })))
    .extend(confirm)
    .step("complete", c => c.message("Done! 🎉"));

What's new

• Scene IS an EventComposer — full Composer DSL on every Scene (.command, .callbackQuery, .hears, .on, .use, .derive, .guard, .branch, .when, .extend, …). Scene-level handlers act as scene-global middleware (e.g. global /cancel from any step).
• Builder step API — .step(c => c…) and .step("name", c => c…). Each step is a StepComposer with lifecycle hooks (.enter, .exit, .fallback, .message, .events, .updates<T>()) plus the gramio surface.
• Named steps + hybrid ids — step("intro", ...) for named, step(c => …) for numeric (autoincrement). step.id and step.previousId are now string | number. step.next/previous walks the array; step.go("name") jumps by name.
• scene.extend(otherScene) — merge another Scene's steps + middleware into this one. Numeric ids renumber, named ids throw on collision. Enables reusable step modules.
• Step modules — new Scene() (no name) → `isModule = true`. `validateScenes` rejects direct registration. Use only via `scene.extend(module)`.
• scene.onExit(handler) — symmetric to onEnter; fires on `exit` / `exitSub` / `reenter`.
• .derive() visible in .onEnter — derives apply before onEnter so `ctx.user` etc. work in onEnter without workarounds. Distinguished from `step.go()` transitions via a new `entered` flag in storage.
• ctx.scene.update({...}) auto-advances builder steps — walks `~scene.steps` array by index, supporting named ids.

Architecture

• `src/scene-composer.ts` — `createComposer` instance with gramio's `_composerMethods` table → `SceneComposerBase`.
• `src/step-composer.ts` — `createComposer` with gramio methods + step lifecycle (`.enter/.exit/.fallback/.message/.events/.updates`).
• `src/scene.ts` — `Scene` extends `SceneComposerBase`. Scene-specific data on `this["scene"]` (separate from composer's ``). Internal runtime methods renamed to `dispatch`/`dispatchActive` to avoid collision with inherited `Composer.compose/run`.
• `src/scene-internals.ts` — shared types for the `~scene` slot.
• `src/types.ts` — `stepId: string | number` (was `number`); new `entered?: boolean` field.
• `src/utils.ts` — `getStepDerives` walks `~scene.steps` for next/previous; `update()` defaults to advance-by-index in builder mode; `validateScenes` rejects modules.

Bugs found & fixed via testing

1. `firstTime` path was skipping scene-level `.derive()` / `.decorate()` — fixed by running setup chain first.
2. `dispatchActive` fallback logic was inverted; terminal (passthrough) fired before fallback could check — rewrote routing as clean if/else.
3. Guard middleware was skipped on firstTime path — added `guard` to setup whitelist; failing guard now blocks step entry.
4. `update({})` without options didn't advance named steps — fallback to walk-array-by-index.

Migration notes

• `stepId: number` → `stepId: string | number` in storage. Existing numeric records remain valid (subset). No data migration needed.
• New optional `entered?: boolean` field. Old data treated as `false` — correct default.
• `gramio` peer-dep bumped from `>=0.7.0` to `>=0.9.0` (when `_composerMethods` was exported).
• Internal `scene.compose(ctx, onNext, passthrough)` and `scene.run(ctx, storage, key, data, passthrough)` were renamed to `scene.dispatch` / `scene.dispatchActive`. These were only ever called from the package internals (`utils.ts`, `index.ts`); the inherited `Composer.compose()` / `Composer.run(ctx, next?)` are unchanged for users who call them.

Tests

• 132/132 tests across 12 files, all green.
• 58 new tests in 7 new files cover the new API (builder, navigation, lifecycle, extend(scene), onExit, update semantics, full Composer DSL on Scene, complex realistic flows).
• All 74 existing tests (legacy API) keep passing without changes.

Test plan

• `bun test` (132/132 passing)
• `bun tsc --noEmit` (clean)
• `bun biome check` (clean)
• Manual exercise of new API in an example bot