@yaebal/scenes 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @yaebal/scenes
+
+context inside a scene: the base context plus the scene control.
+
+## install
+
+```sh
+pnpm add @yaebal/scenes
+```
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,49 @@
+import type { Context, Plugin } from "@yaebal/core";
+import { type StorageAdapter } from "@yaebal/session";
+/** context inside a scene: the base context plus the scene control. */
+export type SceneContext = Context & {
+    scene: SceneControl;
+};
+/** a scene step. reads the user's input (`ctx.text`), then `next()` / `leave()`. */
+export type Step = (ctx: SceneContext) => unknown | Promise<unknown>;
+/** a scene: an optional entry hook (asks the first question) and ordered steps. */
+export interface SceneDef {
+    enter?: Step;
+    steps: Step[];
+}
+export interface SceneControl {
+    /** enter a scene (runs its `enter` hook). */
+    enter(name: string): Promise<void>;
+    /** advance to the next step (the new step runs on the next message). */
+    next(): void;
+    /** leave the current scene. */
+    leave(): Promise<void>;
+    /** the active scene name, if any. */
+    readonly current: string | undefined;
+    /** the current step index. */
+    readonly step: number;
+}
+interface SceneState {
+    scene: string;
+    step: number;
+}
+export interface ScenesOptions {
+    /** where to persist scene state. defaults to in-memory. */
+    storage?: StorageAdapter<SceneState>;
+    /** scene key for an update. defaults to per-chat (`ctx.chat.id`). */
+    getKey?: (ctx: Context) => string | undefined;
+}
+/**
+ * scenes plugin: step-by-step wizards. each step handles one user message and
+ * asks the next question; `next()` advances, `leave()` exits. state lives per
+ * chat, so this is safe under the sequential update loop (no suspended promises).
+ *
+ * while in a scene every message is consumed and never reaches other handlers —
+ * so a `/cancel` won't fire its command unless a step checks for it
+ * (`if (ctx.text === "/cancel") return ctx.scene.leave()`).
+ */
+export declare function scenes(defs: Record<string, SceneDef>, options?: ScenesOptions): Plugin<Context, {
+    scene: SceneControl;
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE,uEAAuE;AACvE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC;AAE7D,oFAAoF;AACpF,MAAM,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAErE,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACxB,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,IAAI,EAAE,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC5B,6CAA6C;IAC7C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,wEAAwE;IACxE,IAAI,IAAI,IAAI,CAAC;IACb,+BAA+B;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,UAAU;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC7B,2DAA2D;IAC3D,OAAO,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACrC,qEAAqE;IACrE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EAC9B,OAAO,GAAE,aAAkB,GACzB,MAAM,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,CAAC,CAwF1C"}

package/lib/index.js

@@ -0,0 +1,87 @@
+import { MemoryStorage } from "@yaebal/session";
+/**
+ * scenes plugin: step-by-step wizards. each step handles one user message and
+ * asks the next question; `next()` advances, `leave()` exits. state lives per
+ * chat, so this is safe under the sequential update loop (no suspended promises).
+ *
+ * while in a scene every message is consumed and never reaches other handlers —
+ * so a `/cancel` won't fire its command unless a step checks for it
+ * (`if (ctx.text === "/cancel") return ctx.scene.leave()`).
+ */
+export function scenes(defs, options = {}) {
+    const storage = options.storage ?? new MemoryStorage();
+    const getKey = options.getKey ?? ((ctx) => ctx.chat?.id?.toString());
+    // per-request consume step, shared from `derive` (which builds the control and
+    // owns the mutable state) to the routing `use` that runs after it.
+    const runners = new WeakMap();
+    const plugin = (composer) => composer
+        .derive(async (ctx) => {
+        const key = getKey(ctx);
+        let state = key !== undefined ? await storage.get(key) : undefined;
+        let advance = false;
+        let left = false;
+        const persist = async () => {
+            if (key === undefined)
+                return;
+            if (left || !state)
+                await storage.delete(key);
+            else
+                await storage.set(key, state);
+        };
+        const control = {
+            get current() {
+                return state?.scene;
+            },
+            get step() {
+                return state?.step ?? 0;
+            },
+            next() {
+                advance = true;
+            },
+            async enter(name) {
+                state = { scene: name, step: 0 };
+                advance = false;
+                left = false;
+                await defs[name]?.enter?.(ctx);
+                await persist();
+            },
+            async leave() {
+                left = true;
+                state = undefined;
+                await persist();
+            },
+        };
+        // in a scene with a message? run the current step instead of other handlers.
+        runners.set(ctx, async () => {
+            if (state && ctx.message) {
+                const def = defs[state.scene];
+                const step = def?.steps[state.step];
+                if (step) {
+                    await step(ctx);
+                    if (!left && state) {
+                        if (advance)
+                            state = { scene: state.scene, step: state.step + 1 };
+                        // re-resolve from the current scene — a step may have switched it via enter()
+                        const length = defs[state.scene]?.steps.length ?? 0;
+                        if (state.step >= length) {
+                            state = undefined;
+                            left = true;
+                        }
+                        await persist();
+                    }
+                    return true; // consumed
+                }
+            }
+            return false;
+        });
+        return { scene: control };
+    })
+        .use(async (ctx, next) => {
+        const consumed = await runners.get(ctx)?.();
+        runners.delete(ctx);
+        if (!consumed)
+            await next();
+    });
+    return plugin;
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { MemoryStorage } from "@yaebal/session";
+import { scenes } from "./index.js";
+const noop = async () => { };
+const entry = (c) => c.toMiddleware();
+const api = {};
+const msgCtx = (text, chatId) => new Context({
+    api,
+    update: {
+        update_id: 1,
+        message: {
+            message_id: 1,
+            date: 0,
+            chat: { id: chatId, type: "private" },
+            from: { id: chatId, is_bot: false, first_name: "u" },
+            text,
+        },
+    },
+    updateType: "message",
+});
+test("a wizard collects input across messages and leaves", async () => {
+    const collected = {};
+    const asked = [];
+    const defs = {
+        reg: {
+            enter: (ctx) => {
+                asked.push("name?");
+            },
+            steps: [
+                (ctx) => {
+                    collected.name = ctx.text ?? "";
+                    ctx.scene.next();
+                    asked.push("age?");
+                },
+                (ctx) => {
+                    collected.age = ctx.text ?? "";
+                    return ctx.scene.leave();
+                },
+            ],
+        },
+    };
+    const storage = new MemoryStorage();
+    let fellThrough = 0;
+    const mw = entry(new Composer()
+        .install(scenes(defs, { storage }))
+        .command("reg", (ctx) => ctx.scene.enter("reg"))
+        .on("message:text", () => {
+        fellThrough++;
+    }));
+    await mw(msgCtx("/reg", 1), noop); // enter → asks name
+    assert.deepEqual(asked, ["name?"]);
+    assert.deepEqual((await storage.get("1")) ?? null, { scene: "reg", step: 0 });
+    await mw(msgCtx("Alice", 1), noop); // step 0 → name, advance, asks age
+    assert.equal(collected.name, "Alice");
+    assert.deepEqual((await storage.get("1")) ?? null, { scene: "reg", step: 1 });
+    await mw(msgCtx("30", 1), noop); // step 1 → age, leave
+    assert.equal(collected.age, "30");
+    assert.equal(await storage.get("1"), undefined); // scene cleared
+    // scene messages were consumed — the fallthrough handler never saw them
+    assert.equal(fellThrough, 0);
+});
+test("messages outside a scene fall through to normal handlers", async () => {
+    let seen = "";
+    const mw = entry(new Composer().install(scenes({ reg: { steps: [] } })).on("message:text", (ctx) => {
+        seen = ctx.text;
+    }));
+    await mw(msgCtx("hello", 2), noop);
+    assert.equal(seen, "hello");
+});
+test("a step can switch scenes via enter()", async () => {
+    const defs = {
+        a: { steps: [(ctx) => ctx.scene.enter("b")] },
+        b: { steps: [(ctx) => ctx.scene.leave()] },
+    };
+    const storage = new MemoryStorage();
+    const mw = entry(new Composer()
+        .install(scenes(defs, { storage }))
+        .command("a", (ctx) => ctx.scene.enter("a")));
+    await mw(msgCtx("/a", 5), noop); // in scene a
+    await mw(msgCtx("go", 5), noop); // step a[0] → enter("b")
+    assert.deepEqual((await storage.get("5")) ?? null, { scene: "b", step: 0 });
+    await mw(msgCtx("done", 5), noop); // step b[0] → leave
+    assert.equal(await storage.get("5"), undefined);
+});
+test("a step that does not advance re-runs (validation)", async () => {
+    let attempts = 0;
+    const defs = {
+        ask: {
+            steps: [
+                (ctx) => {
+                    attempts++;
+                    if (ctx.text === "ok")
+                        return ctx.scene.leave();
+                    // invalid → stay on the same step
+                },
+            ],
+        },
+    };
+    const storage = new MemoryStorage();
+    const mw = entry(new Composer()
+        .install(scenes(defs, { storage }))
+        .command("ask", (ctx) => ctx.scene.enter("ask")));
+    await mw(msgCtx("/ask", 3), noop);
+    await mw(msgCtx("nope", 3), noop); // stays
+    assert.deepEqual((await storage.get("3")) ?? null, { scene: "ask", step: 0 });
+    await mw(msgCtx("ok", 3), noop); // leaves
+    assert.equal(await storage.get("3"), undefined);
+    assert.equal(attempts, 2);
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@yaebal/scenes",
+  "version": "0.0.1",
+  "description": "yaebal scenes plugin — step-by-step wizards over multiple messages.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/core": "0.0.1",
+    "@yaebal/session": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "scenes",
+    "wizard",
+    "fsm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/scenes"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,142 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Middleware } from "@yaebal/core";
+import { MemoryStorage } from "@yaebal/session";
+import { type SceneContext, type SceneDef, scenes } from "./index.js";
+
+const noop = async () => {};
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+
+const api = {} as never;
+const msgCtx = (text: string, chatId: number) =>
+	new Context({
+		api,
+		update: {
+			update_id: 1,
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: chatId, type: "private" },
+				from: { id: chatId, is_bot: false, first_name: "u" },
+				text,
+			},
+		} as never,
+		updateType: "message",
+	});
+
+test("a wizard collects input across messages and leaves", async () => {
+	const collected: Record<string, string> = {};
+	const asked: string[] = [];
+	const defs: Record<string, SceneDef> = {
+		reg: {
+			enter: (ctx) => {
+				asked.push("name?");
+			},
+			steps: [
+				(ctx: SceneContext) => {
+					collected.name = ctx.text ?? "";
+					ctx.scene.next();
+
+					asked.push("age?");
+				},
+				(ctx: SceneContext) => {
+					collected.age = ctx.text ?? "";
+
+					return ctx.scene.leave();
+				},
+			],
+		},
+	};
+
+	const storage = new MemoryStorage<{ scene: string; step: number }>();
+	let fellThrough = 0;
+
+	const mw = entry(
+		new Composer<Context>()
+			.install(scenes(defs, { storage }))
+			.command("reg", (ctx) => ctx.scene.enter("reg"))
+			.on("message:text", () => {
+				fellThrough++;
+			}),
+	);
+
+	await mw(msgCtx("/reg", 1), noop); // enter → asks name
+	assert.deepEqual(asked, ["name?"]);
+	assert.deepEqual((await storage.get("1")) ?? null, { scene: "reg", step: 0 });
+
+	await mw(msgCtx("Alice", 1), noop); // step 0 → name, advance, asks age
+	assert.equal(collected.name, "Alice");
+	assert.deepEqual((await storage.get("1")) ?? null, { scene: "reg", step: 1 });
+
+	await mw(msgCtx("30", 1), noop); // step 1 → age, leave
+	assert.equal(collected.age, "30");
+	assert.equal(await storage.get("1"), undefined); // scene cleared
+
+	// scene messages were consumed — the fallthrough handler never saw them
+	assert.equal(fellThrough, 0);
+});
+
+test("messages outside a scene fall through to normal handlers", async () => {
+	let seen = "";
+
+	const mw = entry(
+		new Composer<Context>().install(scenes({ reg: { steps: [] } })).on("message:text", (ctx) => {
+			seen = ctx.text;
+		}),
+	);
+
+	await mw(msgCtx("hello", 2), noop);
+	assert.equal(seen, "hello");
+});
+
+test("a step can switch scenes via enter()", async () => {
+	const defs: Record<string, SceneDef> = {
+		a: { steps: [(ctx: SceneContext) => ctx.scene.enter("b")] },
+		b: { steps: [(ctx: SceneContext) => ctx.scene.leave()] },
+	};
+
+	const storage = new MemoryStorage<{ scene: string; step: number }>();
+	const mw = entry(
+		new Composer<Context>()
+			.install(scenes(defs, { storage }))
+			.command("a", (ctx) => ctx.scene.enter("a")),
+	);
+
+	await mw(msgCtx("/a", 5), noop); // in scene a
+	await mw(msgCtx("go", 5), noop); // step a[0] → enter("b")
+	assert.deepEqual((await storage.get("5")) ?? null, { scene: "b", step: 0 });
+
+	await mw(msgCtx("done", 5), noop); // step b[0] → leave
+	assert.equal(await storage.get("5"), undefined);
+});
+
+test("a step that does not advance re-runs (validation)", async () => {
+	let attempts = 0;
+	const defs: Record<string, SceneDef> = {
+		ask: {
+			steps: [
+				(ctx: SceneContext) => {
+					attempts++;
+					if (ctx.text === "ok") return ctx.scene.leave();
+					// invalid → stay on the same step
+				},
+			],
+		},
+	};
+
+	const storage = new MemoryStorage<{ scene: string; step: number }>();
+	const mw = entry(
+		new Composer<Context>()
+			.install(scenes(defs, { storage }))
+			.command("ask", (ctx) => ctx.scene.enter("ask")),
+	);
+
+	await mw(msgCtx("/ask", 3), noop);
+	await mw(msgCtx("nope", 3), noop); // stays
+	assert.deepEqual((await storage.get("3")) ?? null, { scene: "ask", step: 0 });
+	
+	await mw(msgCtx("ok", 3), noop); // leaves
+	assert.equal(await storage.get("3"), undefined);
+	assert.equal(attempts, 2);
+});

package/src/index.ts

@@ -0,0 +1,141 @@
+import type { Context, Plugin } from "@yaebal/core";
+import { MemoryStorage, type StorageAdapter } from "@yaebal/session";
+
+/** context inside a scene: the base context plus the scene control. */
+export type SceneContext = Context & { scene: SceneControl };
+
+/** a scene step. reads the user's input (`ctx.text`), then `next()` / `leave()`. */
+export type Step = (ctx: SceneContext) => unknown | Promise<unknown>;
+
+/** a scene: an optional entry hook (asks the first question) and ordered steps. */
+export interface SceneDef {
+	enter?: Step;
+	steps: Step[];
+}
+
+export interface SceneControl {
+	/** enter a scene (runs its `enter` hook). */
+	enter(name: string): Promise<void>;
+	/** advance to the next step (the new step runs on the next message). */
+	next(): void;
+	/** leave the current scene. */
+	leave(): Promise<void>;
+	/** the active scene name, if any. */
+	readonly current: string | undefined;
+	/** the current step index. */
+	readonly step: number;
+}
+
+interface SceneState {
+	scene: string;
+	step: number;
+}
+
+export interface ScenesOptions {
+	/** where to persist scene state. defaults to in-memory. */
+	storage?: StorageAdapter<SceneState>;
+	/** scene key for an update. defaults to per-chat (`ctx.chat.id`). */
+	getKey?: (ctx: Context) => string | undefined;
+}
+
+/**
+ * scenes plugin: step-by-step wizards. each step handles one user message and
+ * asks the next question; `next()` advances, `leave()` exits. state lives per
+ * chat, so this is safe under the sequential update loop (no suspended promises).
+ *
+ * while in a scene every message is consumed and never reaches other handlers —
+ * so a `/cancel` won't fire its command unless a step checks for it
+ * (`if (ctx.text === "/cancel") return ctx.scene.leave()`).
+ */
+export function scenes(
+	defs: Record<string, SceneDef>,
+	options: ScenesOptions = {},
+): Plugin<Context, { scene: SceneControl }> {
+	const storage = options.storage ?? new MemoryStorage<SceneState>();
+	const getKey = options.getKey ?? ((ctx: Context) => ctx.chat?.id?.toString());
+
+	// per-request consume step, shared from `derive` (which builds the control and
+	// owns the mutable state) to the routing `use` that runs after it.
+	const runners = new WeakMap<Context, () => Promise<boolean>>();
+
+	const plugin: Plugin<Context, { scene: SceneControl }> = (composer) =>
+		composer
+			.derive(async (ctx) => {
+				const key = getKey(ctx);
+
+				let state = key !== undefined ? await storage.get(key) : undefined;
+				let advance = false;
+				let left = false;
+
+				const persist = async (): Promise<void> => {
+					if (key === undefined) return;
+
+					if (left || !state) await storage.delete(key);
+					else await storage.set(key, state);
+				};
+
+				const control: SceneControl = {
+					get current() {
+						return state?.scene;
+					},
+					get step() {
+						return state?.step ?? 0;
+					},
+					next() {
+						advance = true;
+					},
+					async enter(name) {
+						state = { scene: name, step: 0 };
+						advance = false;
+						left = false;
+
+						await defs[name]?.enter?.(ctx as unknown as SceneContext);
+						await persist();
+					},
+					async leave() {
+						left = true;
+						state = undefined;
+
+						await persist();
+					},
+				};
+
+				// in a scene with a message? run the current step instead of other handlers.
+				runners.set(ctx, async () => {
+					if (state && ctx.message) {
+						const def = defs[state.scene];
+						const step = def?.steps[state.step];
+
+						if (step) {
+							await step(ctx as unknown as SceneContext);
+
+							if (!left && state) {
+								if (advance) state = { scene: state.scene, step: state.step + 1 };
+
+								// re-resolve from the current scene — a step may have switched it via enter()
+								const length = defs[state.scene]?.steps.length ?? 0;
+								if (state.step >= length) {
+									state = undefined;
+									left = true;
+								}
+
+								await persist();
+							}
+							return true; // consumed
+						}
+					}
+
+					return false;
+				});
+
+				return { scene: control };
+			})
+			.use(async (ctx, next) => {
+				const consumed = await runners.get(ctx)?.();
+				runners.delete(ctx);
+
+				if (!consumed) await next();
+			});
+			
+	return plugin;
+}