pathenger 0.1.0 → 0.9.0

package/README.md

@@ -1,8 +1,12 @@
 # pathenger
 
-Step-by-step flows for command-line apps. Explicit, branching, testable.
+Easy to use, explicit, predictable, dynamic yet structured; pathenger is step driven CLI orchestration framework.
 
-Most prompt libraries hand you widgets and wish you luck with the orchestration. pathenger inverts that: you declare your CLI as a graph of steps, each one of which shows a message, does some work, or asks a question, and the flow engine walks the graph until you tell it to exit. Branches, loops, validation, and async work are all first-class. Your CLI _is_ the flow.
+Common prompt libraries hand you widgets and wish you luck with the orchestration. pathenger does the opposite.
+
+You declare your CLI as a graph of steps, each one of which shows a message, does some work, or asks a question, and the flow engine walks the graph until you tell it to exit.
+
+Branches, loops, validation, and async work are all first-class. No other tool provides this approach.
 
 ```ts
 import { pathenger } from 'pathenger'
@@ -20,21 +24,35 @@ io.step.input({
 	id: 'name',
 	type: 'text',
 	message: 'What is your name?',
-	validate: (value) => value.length > 1 || 'A little longer, please.',
-	next: 'goodbye'
+	next: 'goodbye',
+	validate: (value) => {
+		const isInputLongEnough = value.length > 1
+		return isInputLongEnough || 'Must be more than 1 character.'
+	}
 })
 
 io.step.output({
 	id: 'goodbye',
-	message: () => `Nice to meet you, ${io.results.name}.`,
 	level: 'success',
-	next: io.exit()
+	next: io.exit(),
+	message: () => `Nice to meet you, ${io.results.name}.`
 })
 
 io.start('welcome')
 ```
 
-That's a complete program. No `main()`, no prompt-then-if-then-prompt spaghetti. Register steps, point them at each other, start the flow.
+That's a complete program.
+
+There is no `main()`, no free-form paths your program takes, no prompt-then-if-then-prompt spaghetti. You register steps, point them at each other, and start the flow.
+
+What you get that widget libraries don't have:
+
+- A validated flow graph that fails at startup, not six prompts deep
+- Legal cycles, so menu-driven apps that run until quit come free
+- Opt-in backtracking with side-effect compensation, so users can edit an earlier answer
+- Preseeded answers for CI and instant `--yes` modes
+- A headless test harness that asserts on the path your flow took
+- Typed results and shared state across every step and helper
 
 ## Install
 
@@ -60,15 +78,12 @@ Create one `io` per app and export it from a module. Every step file and every e
 // source/io.ts
 import { pathenger } from 'pathenger'
 
-type StoreT {
-	isPnpmInstalled?: boolean
-	templates?: Template[]
-}
+type StoreT = { isPnpmInstalled?: boolean; templates?: TemplateT[] }
 
 export const io = pathenger.create<StoreT>()
 ```
 
-The generic types `io.store` so every access is checked and autocompleted across your whole codebase. You can also declare your results shape with a second generic — see [TypeScript](#typescript).
+The generic types `io.store` so every access is checked and autocompleted across your whole codebase. A second generic types `io.results` (see [TypeScript](#typescript)).
 
 Your entry point imports the step files (importing registers them) and starts the flow:
 
@@ -102,27 +117,28 @@ Lifecycle: **pre → message → task → post → next**
 | ---------- | -------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
 | `id`       | `string`                                                 | yes      | Unique step id. Registering a duplicate throws immediately.                                                    |
 | `message`  | `string \| () => string`                                 | yes      | The text shown for this step. Functions run synchronously at render time.                                      |
-| `level`    | `'info' \| 'success' \| 'warning' \| 'error' \| 'debug'` | no       | Styling/color of the message. Defaults to `'info'`.                                                            |
-| `duration` | `number`                                                 | no       | Minimum milliseconds the step stays on screen (see below).                                                     |
-| `pre`      | `() => void \| Promise<void>`                            | no       | Async setup, runs silently _before_ the message renders.                                                       |
-| `task`     | `() => unknown \| Promise<unknown>`                      | no       | Async work, runs _while_ the message is on screen, with a spinner. Its return value becomes the step's result. |
+| `level`    | `'info' \| 'success' \| 'warning' \| 'error' \| 'debug'` | no       | Styling of the message. Defaults to `'info'`.                                                                  |
+| `duration` | `number`                                                 | no       | Minimum milliseconds the step stays on screen.                                                                 |
+| `pre`      | `() => void \| Promise<void>`                            | no       | Async setup. Runs silently _before_ the message renders.                                                       |
+| `task`     | `() => unknown \| Promise<unknown>`                      | no       | Async work. Runs _while_ the message is on screen, with a spinner. Its return value becomes the step's result. |
 | `post`     | `(result) => void \| Promise<void>`                      | no       | Side effects after the result is locked in. Cannot block progression.                                          |
-| `next`     | `string \| (result) => string \| ExitToken`              | yes      | Where to go. Receives the step's result.                                                                       |
+| `back`     | `(result) => void \| Promise<void>`                      | no       | Compensation hook. Runs when the user goes back past this step, undoing its side effects. See [Going back](#going-back). |
+| `next`     | `string \| (result) => string \| ExitTokenT`             | yes      | Where to go. Receives the step's result.                                                                       |
 
 ### `duration`
 
-`duration` is the **minimum time the step stays on screen**. That single rule covers everything:
+`duration` is the minimum time the step stays on screen. One rule, two effects:
 
-- Message-only step with `duration: 1000` → the message shows for one second, then the flow advances. Use this to pace output so it reads as deliberate rather than dumped.
-- Step with a `task` → the spinner runs for _at least_ `duration`, and longer if the task is still pending. Fast tasks don't flash; slow tasks aren't cut off.
+- A message-only step with `duration: 1000` shows for one second, then advances. Use this to pace output.
+- A step with a `task` spins for _at least_ `duration`, longer if the task is still pending. Fast tasks don't flash, slow tasks aren't cut off.
 
 ### `pre` vs `task`
 
-`pre` runs **before** the message renders. It's setup: fetch the data the step needs to display itself. `task` runs **while** the message is on screen. It's the work the message narrates, i.e "Cloning product template…" with a spinner, where the message _is the UX for the work_. If you fold your work into `pre`, the user stares at the previous step while it happens and your message flashes by after the fact. Put display prerequisites in `pre`; put the actual work in `task`.
+`pre` runs before the message renders. It fetches whatever the step needs to display itself. `task` runs while the message is on screen. It is the work the message narrates: "Cloning product template…" with a spinner. If you fold your work into `pre`, the user stares at the previous step while it happens and your message flashes by after the fact.
 
 ### The step's result
 
-An output step's result is its task's return value (`undefined` if there's no task). It lands in `io.results[id]` and is passed to `next` and `post`. Tasks that need to record more than one value write to `io.store`. (That is what it is for.)
+An output step's result is its task's return value (`undefined` if there's no task). It lands in `io.results[id]` and is passed to `next` and `post`. Tasks that need to record more than one value write to `io.store`. That is what it is for.
 
 ## Input steps
 
@@ -146,28 +162,30 @@ io.step.input({
 
 Lifecycle: **pre → message → input (filter per keystroke) → validate (on submit) → post → next**
 
-| Property   | Type                                                   | Required | What it does                                                                                                                         |
-| ---------- | ------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`       | `string`                                               | yes      | Unique step id.                                                                                                                      |
-| `type`     | `'text' \| 'select' \| 'multiselect' \| 'confirm'`     | yes      | Which prompt to render.                                                                                                              |
-| `message`  | `string \| () => string`                               | yes      | The question. Functions run synchronously at render time.                                                                            |
-| `tip`      | `string \| () => string`                               | no       | Persistent hint rendered dim beneath the input. Turns red when validation fails.                                                     |
-| `pre`      | `() => void \| Promise<void>`                          | no       | Async setup before the message renders.                                                                                              |
-| `validate` | `(value) => true \| string \| Promise<true \| string>` | no       | Runs on ENTER. Return a string to block progression and show it as the reason, in red. May be async — a spinner shows while it runs. |
-| `post`     | `(result) => void \| Promise<void>`                    | no       | Side effects after the answer is accepted. Cannot block progression — that's `validate`'s job.                                       |
-| `next`     | `string \| (result) => string \| ExitToken`            | yes      | Where to go. Receives the answer.                                                                                                    |
+| Property   | Type                                                   | Required | What it does                                                                                                          |
+| ---------- | ------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `id`       | `string`                                               | yes      | Unique step id.                                                                                                       |
+| `type`     | `'text' \| 'select' \| 'multiselect' \| 'confirm'`     | yes      | Which prompt to render.                                                                                               |
+| `message`  | `string \| () => string`                               | yes      | The question. Functions run synchronously at render time.                                                             |
+| `tip`      | `string \| () => string`                               | no       | Persistent hint rendered dim beneath the input.                                                                       |
+| `pre`      | `() => void \| Promise<void>`                          | no       | Async setup before the message renders.                                                                               |
+| `validate` | `(value) => true \| string \| Promise<true \| string>` | no       | Runs on ENTER. Return a string to block progression and show it in red. Async is fine, a spinner shows while it runs. |
+| `post`     | `(result) => void \| Promise<void>`                    | no       | Side effects after the answer is accepted. Cannot block progression, that's `validate`'s job.                         |
+| `canGoBack`| `boolean`                                              | no       | Lets the user press the back key here to return to the previous input step and edit it. See [Going back](#going-back). |
+| `back`     | `(result) => void \| Promise<void>`                    | no       | Compensation hook. Runs when the user goes back past this step. See [Going back](#going-back).                        |
+| `next`     | `string \| (result) => string \| ExitTokenT`           | yes      | Where to go. Receives the answer.                                                                                     |
 
 An input step's result is the submitted answer. It lands in `io.results[id]` and is passed to `validate`, `post`, and `next`.
 
 ### `type: 'text'`
 
-| Property      | Type                                   | What it does                                                                                                                                                                                                           |
-| ------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `value`       | `string \| () => string`               | Initial _editable_ value, prefilled in the input.                                                                                                                                                                      |
-| `placeholder` | `string \| () => string`               | Ghost text shown when the input is empty. Never submitted.                                                                                                                                                             |
-| `filter`      | `RegExp \| (value: string) => boolean` | Runs on **every keystroke**, synchronously. The keystroke is rejected if the candidate value fails. Regexes use **full-match semantics** — `/^[a-z]*$/` and `/[a-z]*/` behave identically; the whole value must match. |
+| Property      | Type                                   | What it does                                                                                                                                                            |
+| ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `string \| () => string`               | Initial _editable_ value, prefilled in the input.                                                                                                                       |
+| `placeholder` | `string \| () => string`               | Ghost text shown when the input is empty. Never submitted.                                                                                                              |
+| `filter`      | `RegExp \| (value: string) => boolean` | Runs on every keystroke, synchronously. The keystroke is rejected if the candidate value fails. Regexes are full-match: `/^[a-z]*$/` and `/[a-z]*/` behave identically. |
 
-`filter` and `validate` split validation the way it actually needs to be split: `filter` is cheap and sync, so it can run per keystroke and physically keep bad characters out. `validate` runs once on submit, so it's allowed to be async and expensive — hit an API, read the filesystem, take its time behind a spinner. Don't put a network call in a keystroke handler; pathenger won't let you.
+`filter` is cheap and sync, so it runs per keystroke and physically keeps bad characters out. `validate` runs once on submit, so it can be async and expensive: hit an API, read the filesystem, take its time behind a spinner. Don't put a network call in a keystroke handler. pathenger won't let you.
 
 ```ts
 // Deriving the initial value from an earlier answer
@@ -182,11 +200,11 @@ io.step.input({
 
 ### `type: 'select'`
 
-| Property  | Type                                                                           | What it does                     |
-| --------- | ------------------------------------------------------------------------------ | -------------------------------- |
-| `options` | `Option[] \| () => Option[]` where `Option = { label: string, value: string }` | The choices. Arrow keys + ENTER. |
+| Property  | Type                                                                                                | What it does                     |
+| --------- | --------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `options` | `SelectOptionT[] \| () => SelectOptionT[]` where `SelectOptionT = { label: string, value: string }` | The choices. Arrow keys + ENTER. |
 
-The result is the chosen option's `value` — the string itself, not the `{ label, value }` object.
+The result is the chosen option's `value`, the string itself, not the object.
 
 ```ts
 io.step.input({
@@ -203,7 +221,7 @@ io.step.input({
 
 ### `type: 'multiselect'`
 
-Same `options` shape as `select`; SPACE toggles, ENTER submits. The result is an **array** of the chosen values (empty array if nothing was chosen — use `validate` to require a minimum).
+Same `options` shape as `select`. SPACE toggles, ENTER submits. The result is an array of the chosen values, in declaration order. Empty if nothing was chosen; require a minimum with `validate`.
 
 ```ts
 io.step.input({
@@ -223,7 +241,7 @@ io.step.input({
 | `yes`    | `string` | Label for the affirmative. Defaults to `'Yes'`. |
 | `no`     | `string` | Label for the negative. Defaults to `'No'`.     |
 
-The result is a `boolean`.
+The result is a `boolean`. Arrow keys toggle, `y`/`n` submit instantly.
 
 ```ts
 io.step.input({
@@ -238,11 +256,9 @@ io.step.input({
 
 ## Dynamic properties are sync. Lifecycle hooks are async.
 
-This is the rule that keeps steps predictable, so it gets its own heading.
-
-Any _display_ property — `message`, `tip`, `placeholder`, `value`, `options` — can be a function, and that function runs **synchronously at render time**. It reads from `io.results` and `io.store`; it never fetches. Anything async belongs in a lifecycle hook: `pre`, `task`, `validate`, or `post`.
+Any display property (`message`, `tip`, `placeholder`, `value`, `options`) can be a function, and that function runs synchronously at render time. It reads from `io.results` and `io.store`. It never fetches. Anything async belongs in a lifecycle hook: `pre`, `task`, `validate`, or `post`.
 
-So "the select options come from an API" looks like this — `pre` fetches, `options` reads:
+So "the select options come from an API" looks like this. `pre` fetches, `options` reads:
 
 ```ts
 io.step.input({
@@ -258,7 +274,7 @@ io.step.input({
 })
 ```
 
-The render loop never awaits a property, and you always know exactly when your code runs.
+The render loop never awaits a property. You always know exactly when your code runs.
 
 ## Branching and why explicit `next` is the point
 
@@ -295,17 +311,88 @@ next: () => io.exit.error('Could not clone. Check your SSH credentials.') // red
 
 No magic strings. An exit token can't collide with a step id, can't be typo'd into a broken reference, and carries its message as data instead of a parsed prefix.
 
+## Going back
+
+`next` moves the flow forward. Going back lets the user return to an earlier question and edit their answer. Opt an input step in with `canGoBack`, and pressing the back key (`Escape` by default) on that prompt returns to the previous input step.
+
+```ts
+io.step.input({
+	id: 'deployment',
+	type: 'select',
+	message: 'On-prem or cloud?',
+	options: [
+		{ label: 'On-Prem', value: 'on-prem' },
+		{ label: 'Cloud', value: 'cloud' }
+	],
+	next: 'region'
+})
+
+io.step.input({
+	id: 'region',
+	type: 'text',
+	message: 'Which region?',
+	canGoBack: true, // Escape here returns to `deployment`
+	next: 'confirm'
+})
+```
+
+The previous step re-renders with its earlier answer already filled in, so the user edits instead of retyping. Resubmitting proceeds forward normally, and every step downstream runs fresh from there.
+
+### The mental model: back is time travel to the moment the prompt was shown
+
+When a step is entered, pathenger runs its `pre`, then snapshots `io.results` and `io.store` exactly as they stand, then renders. Going back restores that snapshot and re-renders the target **without** re-running its `pre`. So the step you land on looks precisely as it did when you first saw it — same options, same prefilled values, same store.
+
+This is deliberate. It's the behavior you already know from a web page: scroll down, scroll back up, and the top of the page is still there — it doesn't re-fetch just because you returned to it. Back means _edit a previous answer_, not _refresh_. If you want completely fresh data, `Ctrl+C` and restart; that's cheap. And because every step below the one you edit runs its `pre` again on the way forward, anything that actually depends on the changed answer is recomputed anyway.
+
+`pre` therefore runs exactly once per forward entry. No idempotency caveat, no "pre might run twice" footnote. You always know when your code runs.
+
+### `back`: undoing side effects
+
+Restoring a snapshot rolls back `io.results` and `io.store`. It cannot roll back the world. If a step cloned a repo, wrote a file, or hit an API, going past it should undo that work — so give the step a `back` hook.
+
+```ts
+io.step.output({
+	id: 'cloneTemplate',
+	message: 'Cloning template.',
+	task: async () => await cloneTemplate(io.results.productId),
+	back: async () => await removeDirectory(io.results.productId),
+	next: 'installDeps'
+})
+```
+
+`back` lives on **any** step, output or input — side effects happen in `task` and in `pre` alike, so anywhere can need cleanup. When the user goes back across several steps at once, each unwound step's `back` runs in **reverse order** (last done, first undone — the saga pattern), each receiving the result being discarded. `back` may be async; a failing `back` surfaces its error and halts rather than leaving a half-undone world in silence.
+
+Two orthogonal properties, each in its natural home: `canGoBack` on input steps says _the user may leave here backwards_; `back` on any step says _here's how to undo me when I'm unwound_.
+
+### The world is your job
+
+pathenger guarantees exactly one thing when going back: `io.results` and `io.store` are restored to the target step's post-`pre` snapshot. Everything else your steps touched — the filesystem, the network, a database, a spawned process — is outside its reach. That's what `back` hooks are for, and they only run on steps that declare them. Enable `canGoBack` on a step and you're accepting responsibility for making every side effect between there and the previous question reversible. If you don't write that cleanup, going back won't do it for you.
+
+### Choosing the back key
+
+The back key is global, set once when you start the flow. Default is `Escape`. Pass `backKey` to change it — a bare key name, or a combo joined with `+`:
+
+```ts
+io.start('welcome', { backKey: 'ctrl+b' })
+```
+
+Supported modifiers are `ctrl`, `shift`, and `meta` (`alt` is treated as `meta`). Examples: `'escape'`, `'ctrl+b'`, `'ctrl+shift+left'`.
+
+### Cost
+
+History is only tracked when at least one input step sets `canGoBack`. If none do, there are no snapshots and no overhead — the feature is entirely pay-as-you-go. Because snapshots use `structuredClone`, `io.results` and `io.store` must be structured-cloneable while back is enabled: no functions, class instances, or promises stored in them. pathenger throws a clear error at snapshot time if they aren't.
+
 ## `io.results` and `io.store`
 
-**`io.results`** is engine-owned: after a step completes, `io.results[id]` holds its result (the answer for input steps, the task's return value for output steps). Read it anywhere — in later steps' dynamic properties, in `next` functions, in extracted helpers.
+**`io.results`** is engine-owned. After a step completes, `io.results[id]` holds its result: the answer for input steps, the task's return value for output steps. Read it anywhere.
 
-**`io.store`** is yours. It's the shared state for everything that isn't a single step's result: flags set by tasks, data fetched in `pre`, accumulations across a loop. Because your app exports one `io` instance, extracted functions just import it — no context parameter threading through five layers of helpers:
+**`io.store`** is yours. It holds everything that isn't a single step's result: flags set by tasks, data fetched in `pre`, accumulations across a loop. Because your app exports one `io` instance, extracted functions just import it:
 
 ```ts
 // source/utilities/cloneTemplate.ts
 import { io } from '../io'
 
-export async function cloneTemplate() {
+export const cloneTemplate = async () => {
 	try {
 		await git.clone(templateUrl, io.results.productId)
 		io.store.didCloneSucceed = true
@@ -317,23 +404,23 @@ export async function cloneTemplate() {
 
 Rule of thumb: if one step produces it and the flow consumes it, let it be the step's result. If it's shared, shaped, or written from helpers, put it in the store.
 
-## Starting the flow — and what gets validated
+## Starting the flow
 
 ```ts
 io.start('welcome')
 ```
 
-`io.start` validates the graph **before rendering anything**:
+`io.start` validates the graph before rendering anything:
 
-- Every static string `next` must resolve to a registered step. A typo fails at startup with a message naming the step and the missing id — never mid-flow after the user has answered six prompts.
+- Every static string `next` must resolve to a registered step. A typo fails at startup with a message naming the step and the missing id, never mid-flow after the user has answered six prompts.
 - The start id must exist.
-- Unreachable steps produce a warning (they're often a sign of a broken reference elsewhere).
+- Unreachable steps produce a warning.
 
-Duplicate ids don't even make it that far — `io.step.output` / `io.step.input` throw at registration.
+Duplicate ids fail even earlier: `io.step.output` and `io.step.input` throw at registration.
 
-Function `next`s can't be checked statically, so they're checked at runtime: returning an unknown id produces an error that names _which step_ returned _which bad id_, not a stack trace from the engine's guts.
+Function `next`s are checked at runtime. Returning an unknown id produces an error naming _which step_ returned _which bad id_, not a stack trace from the engine's guts.
 
-`Ctrl+C` is handled for you: the terminal is restored (no half-drawn prompt), an optional `onCancel` runs, and the process exits cleanly:
+`Ctrl+C` is handled for you: the terminal is restored, an optional `onCancel` runs, and the process exits cleanly.
 
 ```ts
 io.start('welcome', { onCancel: () => console.log('\nNo worries. Nothing was changed.') })
@@ -341,7 +428,7 @@ io.start('welcome', { onCancel: () => console.log('\nNo worries. Nothing was cha
 
 ## Preseeded answers
 
-Pass answers up front and their steps resolve without prompting — the step still runs its lifecycle (`pre`, `validate`, `post`, `next`), it just skips the interactive part. This is how a scaffolding CLI grows a `--yes` mode, and how flows run in CI:
+Pass answers up front and their steps resolve without prompting. The step still runs its full lifecycle (`pre`, `validate`, `post`, `next`), it just skips the interactive part. This is how a scaffolding CLI grows a `--yes` mode, and how flows run in CI:
 
 ```ts
 io.start('welcome', {
@@ -349,11 +436,11 @@ io.start('welcome', {
 })
 ```
 
-Preseeded answers still go through `validate`. If a preseeded answer fails validation, the flow falls back to prompting for that step interactively — or, with `interactive: false`, exits with an error. `interactive: false` also means any _unseeded_ input step is an error: perfect for CI, where a hung prompt is a hung pipeline.
+Preseeded answers still go through `validate`. An invalid preseed falls back to prompting interactively, or with `interactive: false`, exits with an error. `interactive: false` also makes any unseeded input step an error: perfect for CI, where a hung prompt is a hung pipeline.
 
 ## Testing
 
-Interactive CLIs are notoriously untestable. pathenger flows aren't, because the graph is data. `io.test` runs the flow headless — no TTY, no rendering, durations skipped — and returns what happened:
+Interactive CLIs are notoriously untestable. pathenger flows aren't, because the graph is data. `io.test` runs the flow headless (no TTY, no rendering, durations skipped) and returns what happened:
 
 ```ts
 import { io } from '../source/io'
@@ -379,11 +466,11 @@ test('choosing on-prem routes through verification', async () => {
 
 `run.visited` is the ordered list of step ids the flow walked, `run.results` is the final results object, and `run.exit` tells you how it ended. Assert on paths, not pixels.
 
-`pathenger.create()` returns an instance precisely so tests can isolate: your _app_ makes `io` a singleton by exporting it, but a test can always construct a fresh one.
+`pathenger.create()` returns an instance precisely so tests can isolate. Your _app_ makes `io` a singleton by exporting it. A test can always construct a fresh one.
 
 ## Handing over the terminal
 
-Sometimes a task needs to run a child process that has its own interactive moment — `git clone` asking for an SSH passphrase, an editor, a pager. Don't fight it; hand over the terminal:
+Sometimes a task needs to run a child process with its own interactive moment: `git clone` asking for an SSH passphrase, an editor, a pager. Don't fight it. Hand over the terminal:
 
 ```ts
 io.step.output({
@@ -401,19 +488,16 @@ io.step.output({
 })
 ```
 
-`io.suspend` restores the cursor, leaves raw mode, runs your function with the terminal fully released, then re-enters the flow and redraws. The child process prompts however it wants; pathenger picks up where it left off.
+`io.suspend` restores the cursor, leaves raw mode, runs your function with the terminal fully released, then re-enters the flow and redraws. The child process prompts however it wants. pathenger picks up where it left off.
 
 ## TypeScript
 
-Declare your store and (optionally) your results shape when you create the instance:
+Declare your store and results shapes when you create the instance:
 
 ```ts
-interface Store {
-	isPnpmInstalled?: boolean
-	templates?: Template[]
-}
+type StoreT = { isPnpmInstalled?: boolean; templates?: TemplateT[] }
 
-interface Results {
+type ResultsT = {
 	productId: string
 	productName: string
 	deployment: 'on-prem' | 'cloud'
@@ -421,10 +505,10 @@ interface Results {
 	features: string[]
 }
 
-export const io = pathenger.create<Store, Results>()
+export const io = pathenger.create<StoreT, ResultsT>()
 ```
 
-Now `io.store.isPnpmInstalled` is a checked `boolean | undefined`, `io.results.deployment` is `'on-prem' | 'cloud'`, and a typo'd key is a compile error. Declaring your shapes up front is very much in the spirit of the library: explicit beats inferred-and-mysterious.
+Now `io.store.isPnpmInstalled` is a checked `boolean | undefined`, `io.results.deployment` is `'on-prem' | 'cloud'`, and a typo'd key is a compile error. Explicit beats inferred-and-mysterious.
 
 ## A complete example
 
@@ -435,11 +519,9 @@ import { pathenger } from 'pathenger'
 import { titleCase } from 'change-case'
 import { fetcher, hasGlobalPnpm, cloneTemplate } from './utilities'
 
-interface Store {
-	didCloneSucceed?: boolean
-}
+type StoreT = { didCloneSucceed?: boolean }
 
-const io = pathenger.create<Store>()
+const io = pathenger.create<StoreT>()
 
 io.step.output({
 	id: 'welcome',
@@ -548,7 +630,7 @@ io.start('welcome')
 
 ## Why not just use a prompt library?
 
-inquirer, prompts, and @clack/prompts are good at what they do: individual prompt widgets. But the moment your CLI has branches, loops, validation against live data, or async work between questions, the orchestration lands in your lap as a pile of `if`s and `await`s, and it's exactly the part that's hard to read, hard to change, and impossible to test.
+inquirer, prompts, and @clack/prompts are good at what they do: individual prompt widgets. But the moment your CLI has branches, loops, validation against live data, or async work between questions, the orchestration lands in your lap as a pile of `if`s and `await`s. That pile is exactly the part that's hard to read, hard to change, and impossible to test.
 
 pathenger owns the orchestration. The flow is declared, so it can be validated at startup, preseeded for CI, walked headlessly in tests, and read top-to-bottom by the next person. The prompts are the easy part. The graph is the product.
 
@@ -556,12 +638,12 @@ pathenger owns the orchestration. The flow is declared, so it can be validated a
 
 |                                        |                                                                                     |
 | -------------------------------------- | ----------------------------------------------------------------------------------- |
-| `pathenger.create<Store, Results>()`   | Create an `io` instance. Export one per app.                                        |
+| `pathenger.create<StoreT, ResultsT>()` | Create an `io` instance. Export one per app.                                        |
 | `io.step.output(step)`                 | Register an output step. Throws on duplicate id.                                    |
 | `io.step.input(step)`                  | Register an input step. Throws on duplicate id.                                     |
-| `io.start(startId, options?)`          | Validate the graph and run the flow. Options: `answers`, `interactive`, `onCancel`. |
+| `io.start(startId, options?)`          | Validate the graph and run the flow. Options: `answers`, `interactive`, `onCancel`, `backKey`. |
 | `io.test(startId, options?)`           | Run headless. Returns `{ visited, results, exit }`.                                 |
 | `io.results`                           | Every completed step's result, keyed by step id. Engine-owned.                      |
-| `io.store`                             | Your shared state. Typed by the `Store` generic.                                    |
+| `io.store`                             | Your shared state. Typed by the `StoreT` generic.                                   |
 | `io.exit()` / `io.exit.error(message)` | Exit tokens, usable anywhere a step id is accepted.                                 |
-| `io.suspend(fn)`                       | Release the terminal for a child process, then resume the flow.                     |
+| `io.suspend(run)`                      | Release the terminal for a child process, then resume the flow.                     |

package/dist/backSignal.d.ts

@@ -0,0 +1,10 @@
+import type { KeypressT } from './terminal.js';
+declare const backSignalMark: unique symbol;
+export type BackSignalT = {
+    [backSignalMark]: true;
+};
+export declare const createBackSignal: () => BackSignalT;
+export declare const checkIsBackSignal: (candidate: unknown) => candidate is BackSignalT;
+export type BackKeypressCheckT = (keypress: KeypressT) => boolean;
+export declare const buildBackKeypressCheck: (backKey: string) => BackKeypressCheckT;
+export {};

package/dist/backSignal.js

@@ -0,0 +1,32 @@
+const backSignalMark = Symbol('pathenger.backSignal');
+export const createBackSignal = () => {
+    return { [backSignalMark]: true };
+};
+export const checkIsBackSignal = (candidate) => {
+    const isObjectLike = typeof candidate === 'object' && candidate !== null;
+    if (!isObjectLike)
+        return false;
+    return backSignalMark in candidate;
+};
+// backKey is a lowercase key name with optional modifiers,
+// joined by "+" — "escape", "ctrl+b", "ctrl+shift+left"
+export const buildBackKeypressCheck = (backKey) => {
+    const parts = backKey.toLowerCase().split('+');
+    const keyName = parts[parts.length - 1];
+    const modifiers = parts.slice(0, -1);
+    const needsCtrl = modifiers.includes('ctrl');
+    const needsShift = modifiers.includes('shift');
+    const needsMeta = modifiers.includes('meta') || modifiers.includes('alt');
+    return (keypress) => {
+        const doesNameMatch = keypress.name === keyName;
+        if (!doesNameMatch)
+            return false;
+        if (keypress.isCtrl !== needsCtrl)
+            return false;
+        if (keypress.isShift !== needsShift)
+            return false;
+        if (keypress.isMeta !== needsMeta)
+            return false;
+        return true;
+    };
+};

package/dist/cancelSignal.d.ts

@@ -0,0 +1,9 @@
+import type { KeypressT } from './terminal.js';
+declare const cancelSignalMark: unique symbol;
+export type CancelSignalT = {
+    [cancelSignalMark]: true;
+};
+export declare const createCancelSignal: () => CancelSignalT;
+export declare const checkIsCancelSignal: (candidate: unknown) => candidate is CancelSignalT;
+export declare const throwIfCancelKeypress: (keypress: KeypressT) => void;
+export {};

package/dist/cancelSignal.js

@@ -0,0 +1,15 @@
+const cancelSignalMark = Symbol('pathenger.cancelSignal');
+export const createCancelSignal = () => {
+    return { [cancelSignalMark]: true };
+};
+export const checkIsCancelSignal = (candidate) => {
+    const isObjectLike = typeof candidate === 'object' && candidate !== null;
+    if (!isObjectLike)
+        return false;
+    return cancelSignalMark in candidate;
+};
+export const throwIfCancelKeypress = (keypress) => {
+    const isCancelKeypress = keypress.isCtrl && keypress.name === 'c';
+    if (isCancelKeypress)
+        throw createCancelSignal();
+};

package/dist/create.d.ts

@@ -0,0 +1,34 @@
+import type { ExitTokenT } from './exitToken.js';
+import type { FlowOutcomeT } from './runFlow.js';
+import type { InputStepT, OutputStepT } from './types.js';
+export type StartOptionsT = {
+    answers?: Record<string, unknown>;
+    interactive?: boolean;
+    onCancel?: () => void;
+    backKey?: string;
+};
+export type TestOptionsT = {
+    answers?: Record<string, unknown>;
+};
+export type TestRunT<ResultsT> = {
+    visited: string[];
+    results: ResultsT;
+    exit: FlowOutcomeT;
+};
+export type ExitFunctionT = {
+    (): ExitTokenT;
+    error: (message: string) => ExitTokenT;
+};
+export type IoT<StoreT, ResultsT> = {
+    step: {
+        output: <TaskResultT>(outputStep: OutputStepT<TaskResultT>) => OutputStepT<TaskResultT>;
+        input: (inputStep: InputStepT) => InputStepT;
+    };
+    start: (startId: string, startOptions?: StartOptionsT) => Promise<void>;
+    test: (startId: string, testOptions?: TestOptionsT) => Promise<TestRunT<ResultsT>>;
+    results: ResultsT;
+    store: StoreT;
+    exit: ExitFunctionT;
+    suspend: <ReturnT>(runWithTerminal: () => Promise<ReturnT>) => Promise<ReturnT>;
+};
+export declare const create: <StoreT extends object = Record<string, unknown>, ResultsT extends object = Record<string, unknown>>() => IoT<StoreT, ResultsT>;