@orkestrel/scaffold 0.0.114 → 0.0.116

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/dist/bin/main.js +137 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/orchestration.md +5 -3
  4. package/dist/host/agents/platforms/windows.md +1 -0
  5. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
  9. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  11. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  12. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
  14. package/dist/host/claude/agents/analyst.md +1 -1
  15. package/dist/host/claude/agents/astra.md +2 -2
  16. package/dist/host/claude/agents/builder.md +4 -4
  17. package/dist/host/claude/agents/opus.md +3 -3
  18. package/dist/host/claude/agents/orkestrel.md +5 -7
  19. package/dist/host/claude/agents/planner.md +8 -2
  20. package/dist/host/claude/rules/campaign.md +2 -1
  21. package/dist/host/claude/rules/documentation.md +1 -0
  22. package/dist/host/claude/rules/names.md +3 -1
  23. package/dist/host/claude/rules/tests.md +7 -4
  24. package/dist/host/claude/rules/writing.md +1 -0
  25. package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
  26. package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
  27. package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
  28. package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
  29. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  30. package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
  31. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  32. package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
  33. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  34. package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
  35. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
  36. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  37. package/dist/host/codex/agents/analyst.toml +8 -5
  38. package/dist/host/codex/agents/astra.toml +4 -5
  39. package/dist/host/codex/agents/builder.toml +5 -5
  40. package/dist/host/codex/agents/opus.toml +3 -4
  41. package/dist/host/codex/agents/orkestrel.toml +2 -1
  42. package/dist/host/codex/agents/planner.toml +8 -5
  43. package/dist/host/codex/agents/reviewer.toml +5 -4
  44. package/dist/host/guides/abort.md +17 -17
  45. package/dist/host/guides/agent.md +445 -445
  46. package/dist/host/guides/brief.md +143 -143
  47. package/dist/host/guides/browser.md +731 -731
  48. package/dist/host/guides/budget.md +39 -39
  49. package/dist/host/guides/capture.md +298 -298
  50. package/dist/host/guides/console.md +109 -109
  51. package/dist/host/guides/contract.md +335 -335
  52. package/dist/host/guides/csv.md +30 -30
  53. package/dist/host/guides/database.md +163 -163
  54. package/dist/host/guides/emitter.md +17 -17
  55. package/dist/host/guides/form.md +99 -99
  56. package/dist/host/guides/guide.md +361 -183
  57. package/dist/host/guides/html.md +49 -49
  58. package/dist/host/guides/indexeddb.md +40 -40
  59. package/dist/host/guides/interpret.md +139 -139
  60. package/dist/host/guides/lsp.md +114 -114
  61. package/dist/host/guides/markdown.md +68 -68
  62. package/dist/host/guides/mcp.md +3745 -3745
  63. package/dist/host/guides/middleware.md +170 -170
  64. package/dist/host/guides/msg.md +95 -95
  65. package/dist/host/guides/ndjson.md +8 -8
  66. package/dist/host/guides/ollama.md +56 -56
  67. package/dist/host/guides/pool.md +21 -21
  68. package/dist/host/guides/probe.md +82 -82
  69. package/dist/host/guides/process.md +99 -99
  70. package/dist/host/guides/program.md +98 -96
  71. package/dist/host/guides/qualifier.md +70 -70
  72. package/dist/host/guides/queue.md +37 -37
  73. package/dist/host/guides/rater.md +38 -38
  74. package/dist/host/guides/reason.md +308 -308
  75. package/dist/host/guides/relation.md +50 -50
  76. package/dist/host/guides/router.md +58 -58
  77. package/dist/host/guides/scaffold.md +554 -419
  78. package/dist/host/guides/sea.md +128 -128
  79. package/dist/host/guides/server.md +100 -100
  80. package/dist/host/guides/sqlite.md +28 -28
  81. package/dist/host/guides/sse.md +20 -20
  82. package/dist/host/guides/study.md +444 -444
  83. package/dist/host/guides/table.md +82 -82
  84. package/dist/host/guides/template.md +41 -41
  85. package/dist/host/guides/terminal.md +121 -121
  86. package/dist/host/guides/test.md +273 -273
  87. package/dist/host/guides/timeout.md +18 -18
  88. package/dist/host/guides/tool.md +27 -27
  89. package/dist/host/guides/toolbox.md +166 -166
  90. package/dist/host/guides/websocket.md +54 -54
  91. package/dist/host/guides/worker.md +24 -24
  92. package/dist/host/guides/workflow.md +187 -187
  93. package/dist/host/guides/workspace.md +55 -55
  94. package/dist/host/manifest.json +93 -93
  95. package/dist/host/tests/setupPolicy.ts +5 -3
  96. package/dist/src/core/index.cjs +89 -3
  97. package/dist/src/core/index.cjs.map +1 -1
  98. package/dist/src/core/index.d.cts +229 -144
  99. package/dist/src/core/index.d.ts +229 -144
  100. package/dist/src/core/index.js +87 -4
  101. package/dist/src/core/index.js.map +1 -1
  102. package/dist/src/server/index.cjs +292 -66
  103. package/dist/src/server/index.cjs.map +1 -1
  104. package/dist/src/server/index.d.cts +188 -6
  105. package/dist/src/server/index.d.ts +188 -6
  106. package/dist/src/server/index.js +287 -69
  107. package/dist/src/server/index.js.map +1 -1
  108. package/package.json +4 -3
@@ -100,9 +100,9 @@ What a driver is, and what one step of a field reducer produces ([`src/core`](..
100
100
 
101
101
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
102
102
 
103
- | API | Kind | Shape | Summary |
103
+ | Name | Kind | Signature | Summary |
104
104
  | ------------------- | --------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
105
- | `TerminalInterface` | interface | `{} plus ask` | Declares the contract for asking a form of a human at a keyboard — `ask` and nothing beside it, because a form is one question however many fields it holds. The server `Terminal` implements it against a real TTY; a `PromptClientInterface` holds one to answer forms parked elsewhere. |
105
+ | `TerminalInterface` | interface | `{ ask() }` | Declares the contract for asking a form of a human at a keyboard — `ask` and nothing beside it, because a form is one question however many fields it holds. The server `Terminal` implements it against a real TTY; a `PromptClientInterface` holds one to answer forms parked elsewhere. |
106
106
  | `PromptStatus` | type | `'active' \| 'submit' \| 'cancel'` | Names where one field's reducer stands after a key. `active`: keep asking, because the key was consumed or the answer was refused. `submit`: the field resolved with its `value`. `cancel`: the user aborted with ctrl-c. Names its axis, never `kind`. |
107
107
  | `PromptStep` | interface | `{ state, view, status, value? }` | Represents the result of one reducer step — the next `state`, the rendered `view`, the `status`, and, on `submit` alone, the candidate `value`. The whole contract between a pure reducer and the impure driver: the driver applies the next `state`, writes the `view`, and reads `value` on `submit`. |
108
108
 
@@ -113,7 +113,7 @@ total: no `node:*`, no I/O, and no input throws.
113
113
 
114
114
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to.
115
115
 
116
- | API | Kind | Shape | Summary |
116
+ | Name | Kind | Signature | Summary |
117
117
  | ------------- | --------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118
118
  | `KeyEvent` | interface | `{ name?, sequence, ctrl, meta, shift }` | Represents one decoded keypress — the TTY-agnostic representation of a single key, the output of `parseKey`. A driver reads `name` and the modifier flags to decide its transition; `sequence` is preserved so a printable character round-trips and an unknown escape is never lost. |
119
119
  | `parseKey` | function | `(input: string \| Uint8Array) => KeyEvent` | Decodes one keypress's bytes into a `KeyEvent` — total, never throws. A `Uint8Array` is read as UTF-8; the resulting string is matched against the known control bytes and the CRLF pair (`CONTROL_NAMES`) and escape sequences (`SEQUENCE_NAMES`), falling back to a single printable character. An unrecognized sequence carries no `name`, with the raw `sequence` preserved. |
@@ -127,7 +127,7 @@ line shapes every view is assembled from ([`src/core`](../src/core)).
127
127
 
128
128
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to.
129
129
 
130
- | API | Kind | Shape | Summary |
130
+ | Name | Kind | Signature | Summary |
131
131
  | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
132
132
  | `PromptIcon` | type | `'question' \| 'pointer' \| 'dot' \| 'selected' \| 'checked' \| 'unchecked' \| 'success' \| 'error'` | Names one glyph slot a rendered field draws — the icon axis of a `PromptTheme`. A named value set, not a toggle, so it stays a union. |
133
133
  | `PromptRole` | type | `'question' \| 'pointer' \| 'message' \| 'content' \| 'success' \| 'error' \| 'selected' \| 'focus' \| 'hint' \| 'muted' \| 'description'` | Names one styling slot a rendered field paints through — the semantic axis of a `PromptTheme`. A role says what a fragment means; the theme decides what that meaning looks like, so a consumer re-maps styled output by naming roles rather than reimplementing a renderer. |
@@ -147,7 +147,7 @@ only: the form validates, the form settles, and none of this code does either.
147
147
 
148
148
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to.
149
149
 
150
- | API | Kind | Shape | Summary |
150
+ | Name | Kind | Signature | Summary |
151
151
  | --------------------- | --------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
152
152
  | `InputState` | interface | `{ message, default, styler, theme, value }` | Represents the immutable state a text field's reducer carries — built by `createInputState`, rendered by `renderInputView`, and advanced by `reduceInput`. |
153
153
  | `createInputState` | function | `(field: TextField, styler?: StylerInterface, theme?: PromptThemeOptions) => InputState` | Builds the initial text-field reducer state — the sanitized label, the declared default, the styler, and the resolved theme. |
@@ -180,11 +180,11 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
180
180
  A schema that arrived over a wire is data from somebody else. These are the projection that makes it
181
181
  safe to print ([`src/core`](../src/core)).
182
182
 
183
- | API | Kind | Summary |
184
- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
185
- | `sanitizeDisplayText` | function | Sanitizes text for one single-line display slot. Composes console's ANSI `strip` and C0 `stripControls` passes with removal of tab, line feed, and carriage return. |
186
- | `sanitizeSchema` | function | Sanitizes every terminal-readable string in a parsed form schema, keeping every identity and answer string verbatim and dropping field metadata. |
187
- | `sanitizeThemeIcons` | function | Sanitizes every glyph a wire-supplied `PromptThemeOptions` carries for a single-line display slot. Only the icons need it: a role is guard-narrowed to a console `Style`, whose colors and attributes are fixed name sets, so no role can carry a byte a terminal would act on. |
183
+ | Name | Kind | Signature | Summary |
184
+ | --------------------- | -------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
185
+ | `sanitizeDisplayText` | function | `(text: string) => string` | Sanitizes text for one single-line display slot. Composes console's ANSI `strip` and C0 `stripControls` passes with removal of tab, line feed, and carriage return. |
186
+ | `sanitizeSchema` | function | `(schema: FormSchema) => FormSchema` | Sanitizes every terminal-readable string in a parsed form schema, keeping every identity and answer string verbatim and dropping field metadata. |
187
+ | `sanitizeThemeIcons` | function | `(theme: PromptThemeOptions) => PromptThemeOptions` | Sanitizes every glyph a wire-supplied `PromptThemeOptions` carries for a single-line display slot. Only the icons need it: a role is guard-narrowed to a console `Style`, whose colors and attributes are fixed name sets, so no role can carry a byte a terminal would act on. |
188
188
 
189
189
  ### The headless broker
190
190
 
@@ -193,23 +193,23 @@ can answer, and `answer` drives the parked form to settlement ([`src/core`](../s
193
193
 
194
194
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
195
195
 
196
- | API | Kind | Shape | Summary |
197
- | --------------------- | --------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
198
- | `PromptInterface` | interface | `{ emitter, count } plus park / pending / answer / stop / destroy` | Declares the headless form broker — parks a live form until somebody elsewhere answers it. The headless arm of the local-TTY, headless, and remote trio: there is no terminal here, so a transport forwards each `pending` record to whoever can answer, and `answer` drives the parked form to settlement. |
199
- | `Prompt` | class | `PromptInterface` | Implements the headless form broker. It parks live forms, exposes their serialized schemas, applies remote answers to the authoritative form, and abandons a parked form on timeout, release, or teardown. |
200
- | `createPrompt` | function | `(options?: PromptOptions) => PromptInterface` | Creates the headless `PromptInterface` broker. It parks live forms and applies remote answers to the authoritative instances. |
201
- | `PromptOptions` | interface | `{ on?, error?, timeout?, timer?, cap? }` | Configures `createPrompt` and every `PromptInterface` broker, including one a `TerminalManagerInterface` mounts per endpoint. |
202
- | `ParkRequest` | interface | `{ from?, to? }` | Represents the parking envelope — everything the broker needs about a park that the form itself does not say. |
203
- | `PendingForm` | interface | `{ id, schema, status, time, from?, to? }` | Represents one form parked by the broker — an id-keyed, wire-safe record of a live form awaiting a remote answer. The value a `pending` listener receives and the broker serializes over SSE to a `PromptClientInterface`. |
204
- | `PendingFormStatus` | type | `'pending' \| 'answered' \| 'expired'` | Names the lifecycle status of a parked `PendingForm` — where the ticket stands, which is not where the form stands. A ticket is `pending` until somebody answers it; the form it carries has its own status, and each is a separate fact about a separate entity. |
205
- | `ParkedForm` | interface | `{ form, pending, cancel }` | Represents one parked form's runtime state inside the broker — the live form, the wire-safe record the broker exposes, and the cancel for its expiry timer. |
206
- | `AnswerError` | type | `{ reason: 'unknown' } \| { reason: 'rejected', errors }` | Explains why `PromptInterface.answer` refused — `unknown` for an id no form is parked under, `rejected` for values the authoritative form itself refused, carrying the `FieldError` list it reported. Names its axis with `reason`. |
207
- | `PromptEventMap` | type | `{ pending, answer, expire }` | Declares the broker's event map — lean, errors `unknown`, no listener-error event. |
208
- | `isPendingForm` | function | `PendingForm` | Narrows an unknown wire value to a `PendingForm` envelope — the envelope alone, because the form package's `parseForm` owns the schema payload. |
209
- | `isPendingFormStatus` | const | `PendingFormStatus` | Narrows an unknown value to a `PendingFormStatus`. |
210
- | `TimerHandler` | type | `(callback: () => void, ms: number) => TimerCancelFunction` | Represents one injected timer — arms a deadline `callback` to fire after `ms`, returning a `TimerCancelFunction` that cancels it. The broker's timeout seam: the default wraps the host `setTimeout` and `clearTimeout`; a test injects a deterministic timer that captures the callback and fires it on demand, with no real time and no global patching. |
211
- | `TimerCancelFunction` | type | `() => void` | Cancels a pending `TimerHandler` deadline — idempotent, safe to call after the timer fired. |
212
- | `defaultTimer` | function | `(callback: () => void, ms: number) => TimerCancelFunction` | Implements the default `TimerHandler` — a thin host `setTimeout` / `clearTimeout` wrapper that arms `callback` after `ms` and returns a `TimerCancelFunction`. The deadline seam behind both the `Prompt` broker (its expiry) and the `PromptClient` (its reconnect backoff); a test injects a deterministic timer instead, so neither entity touches real time. |
196
+ | Name | Kind | Signature | Summary |
197
+ | --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
198
+ | `PromptInterface` | interface | `{ emitter, count, park(), pending(), answer(), stop(), destroy() }` | Declares the headless form broker — parks a live form until somebody elsewhere answers it. The headless arm of the local-TTY, headless, and remote trio: there is no terminal here, so a transport forwards each `pending` record to whoever can answer, and `answer` drives the parked form to settlement. |
199
+ | `Prompt` | class | `new (options?: PromptOptions) => PromptInterface` | Implements the headless form broker. It parks live forms, exposes their serialized schemas, applies remote answers to the authoritative form, and abandons a parked form on timeout, release, or teardown. |
200
+ | `createPrompt` | function | `(options?: PromptOptions) => PromptInterface` | Creates the headless `PromptInterface` broker. It parks live forms and applies remote answers to the authoritative instances. |
201
+ | `PromptOptions` | interface | `{ on?, error?, timeout?, timer?, cap? }` | Configures `createPrompt` and every `PromptInterface` broker, including one a `TerminalManagerInterface` mounts per endpoint. |
202
+ | `ParkRequest` | interface | `{ from?, to? }` | Represents the parking envelope — everything the broker needs about a park that the form itself does not say. |
203
+ | `PendingForm` | interface | `{ id, schema, status, time, from?, to? }` | Represents one form parked by the broker — an id-keyed, wire-safe record of a live form awaiting a remote answer. The value a `pending` listener receives and the broker serializes over SSE to a `PromptClientInterface`. |
204
+ | `PendingFormStatus` | type | `'pending' \| 'answered' \| 'expired'` | Names the lifecycle status of a parked `PendingForm` — where the ticket stands, which is not where the form stands. A ticket is `pending` until somebody answers it; the form it carries has its own status, and each is a separate fact about a separate entity. |
205
+ | `ParkedForm` | interface | `{ form, pending, cancel }` | Represents one parked form's runtime state inside the broker — the live form, the wire-safe record the broker exposes, and the cancel for its expiry timer. |
206
+ | `AnswerError` | type | `{ readonly reason: 'unknown'; } \| { readonly reason: 'rejected'; readonly errors: readonly FieldError[]; }` | Explains why `PromptInterface.answer` refused — `unknown` for an id no form is parked under, `rejected` for values the authoritative form itself refused, carrying the `FieldError` list it reported. Names its axis with `reason`. |
207
+ | `PromptEventMap` | type | `{ readonly pending: readonly [form: PendingForm]; readonly answer: readonly [id: string, values: FormValues]; readonly expire: readonly [id: string]; }` | Declares the broker's event map — lean, errors `unknown`, no listener-error event. |
208
+ | `isPendingForm` | function | `(value: unknown) => value is PendingForm` | Narrows an unknown wire value to a `PendingForm` envelope — the envelope alone, because the form package's `parseForm` owns the schema payload. |
209
+ | `isPendingFormStatus` | const | `Guard<PendingFormStatus>` | Narrows an unknown value to a `PendingFormStatus`. |
210
+ | `TimerHandler` | type | `(callback: () => void, ms: number) => TimerCancelFunction` | Represents one injected timer — arms a deadline `callback` to fire after `ms`, returning a `TimerCancelFunction` that cancels it. The broker's timeout seam: the default wraps the host `setTimeout` and `clearTimeout`; a test injects a deterministic timer that captures the callback and fires it on demand, with no real time and no global patching. |
211
+ | `TimerCancelFunction` | type | `() => void` | Cancels a pending `TimerHandler` deadline — idempotent, safe to call after the timer fired. |
212
+ | `defaultTimer` | function | `(callback: () => void, ms: number) => TimerCancelFunction` | Implements the default `TimerHandler` — a thin host `setTimeout` / `clearTimeout` wrapper that arms `callback` after `ms` and returns a `TimerCancelFunction`. The deadline seam behind both the `Prompt` broker (its expiry) and the `PromptClient` (its reconnect backoff); a test injects a deterministic timer instead, so neither entity touches real time. |
213
213
 
214
214
  ### The wire seam
215
215
 
@@ -218,10 +218,10 @@ The `http`-free frame shape a consumer's own HTTP spine mounts the broker over
218
218
 
219
219
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to.
220
220
 
221
- | API | Kind | Shape | Summary |
221
+ | Name | Kind | Signature | Summary |
222
222
  | ------------------ | --------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
223
223
  | `WireEvent` | interface | `{ event, data, id? }` | Represents one SSE-shaped wire frame — the `event` name, its already-stringified `data` payload, and an optional `id`. The transport-neutral shape `serializePending`, `serializeExpire`, and `serializeDestroy` build, with no `http` dependency. |
224
- | `isWireEvent` | const | `WireEvent` | Narrows an unknown value to a transport-neutral `WireEvent` — the guard a consumer's own transport applies to an inbound frame. |
224
+ | `isWireEvent` | const | `Guard<WireEvent>` | Narrows an unknown value to a transport-neutral `WireEvent` — the guard a consumer's own transport applies to an inbound frame. |
225
225
  | `serializePending` | function | `(form: PendingForm) => WireEvent` | Serializes a parked `PendingForm` into a `pending` `WireEvent`, whose frame `id` is the form's own id. |
226
226
  | `serializeExpire` | function | `(id: string) => WireEvent` | Serializes a parked form's expiry or release into an `expire` `WireEvent`, whose `data` is the JSON `{ id }` payload. |
227
227
  | `serializeDestroy` | function | `() => WireEvent` | Serializes the `destroy` `WireEvent` a broker or manager sends when it is going away, which carries no payload. |
@@ -234,18 +234,18 @@ and SSE are web standards.
234
234
 
235
235
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
236
236
 
237
- | API | Kind | Shape | Summary |
238
- | ----------------------- | --------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
239
- | `PromptClientInterface` | interface | `{ emitter, url, connected } plus connect / disconnect / destroy` | Declares the SSE form bridge — the client-side counterpart to `PromptInterface`. It receives serialized `PendingForm` records from a remote broker, rebuilds each schema locally, drives it through a `TerminalInterface`, and POSTs the answer back, so a human at this machine answers forms a broker parked elsewhere. |
240
- | `PromptClient` | class | `PromptClientInterface` | Implements the SSE form bridge. It ingests serialized forms from a remote broker without waiting on a render, drives one form at a time through a local terminal, posts each answer back, and asks again when the authoritative form refuses one. |
241
- | `createPromptClient` | function | `(options: PromptClientOptions) => PromptClientInterface` | Creates the SSE prompt `PromptClientInterface` bridge — it connects to a remote broker's SSE endpoint, dispatches each received form to a local `TerminalInterface`, and POSTs the answer back. Universal — `fetch` and SSE are web standards. |
242
- | `PromptClientOptions` | interface | `{ url, terminal, token?, reconnect?, delay?, on?, error?, fetch?, timer? }` | Configures `createPromptClient` and the `PromptClientInterface`. |
243
- | `PromptClientEventMap` | type | `{ connect, disconnect, expire, error }` | Declares the client's event map — lean, errors `unknown`, no listener-error event. |
244
- | `FetchHandler` | type | `(input: string, init?: FetchInit) => Promise<Response>` | Represents a minimal `fetch` — the subset of the global `fetch` a `PromptClientInterface` uses: open the SSE stream, POST an answer. Injected so a test drives the client with a scripted `Response` instead of a real network. |
245
- | `FetchInit` | interface | `{ method?, headers?, body?, signal? }` | Represents the request init a `PromptClientInterface` passes to its `FetchHandler` — the `RequestInit` fields it actually sets. |
246
- | `globalFetch` | function | `(input: string, init?: FetchInit) => Promise<Response>` | Implements the default `FetchHandler` — the global `fetch`, adapted to the minimal injected shape the `PromptClient` uses. |
247
- | `isAbortError` | function | `(error: unknown) => boolean` | Checks whether a caught value is an `AbortError` — the `PromptClient` distinguishes a deliberate `disconnect` / teardown (an aborted `fetch`) from a real fault, so it exits its connect loop quietly instead of emitting `error` / reconnecting. |
248
- | `isInsecureRemote` | function | `(url: string) => boolean` | Checks whether `url` is an insecure remote endpoint — a plain `http://` URL whose host is not a loopback address. Pure string parsing (no `URL` global), so it stays total on malformed input; the `PromptClient` warns once when a `token` would cross such an endpoint in cleartext. |
237
+ | Name | Kind | Signature | Summary |
238
+ | ----------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
239
+ | `PromptClientInterface` | interface | `{ emitter, url, connected, connect(), disconnect(), destroy() }` | Declares the SSE form bridge — the client-side counterpart to `PromptInterface`. It receives serialized `PendingForm` records from a remote broker, rebuilds each schema locally, drives it through a `TerminalInterface`, and POSTs the answer back, so a human at this machine answers forms a broker parked elsewhere. |
240
+ | `PromptClient` | class | `new (options: PromptClientOptions) => PromptClientInterface` | Implements the SSE form bridge. It ingests serialized forms from a remote broker without waiting on a render, drives one form at a time through a local terminal, posts each answer back, and asks again when the authoritative form refuses one. |
241
+ | `createPromptClient` | function | `(options: PromptClientOptions) => PromptClientInterface` | Creates the SSE prompt `PromptClientInterface` bridge — it connects to a remote broker's SSE endpoint, dispatches each received form to a local `TerminalInterface`, and POSTs the answer back. Universal — `fetch` and SSE are web standards. |
242
+ | `PromptClientOptions` | interface | `{ url, terminal, token?, reconnect?, delay?, on?, error?, fetch?, timer? }` | Configures `createPromptClient` and the `PromptClientInterface`. |
243
+ | `PromptClientEventMap` | type | `{ readonly connect: readonly []; readonly disconnect: readonly []; readonly expire: readonly [id: string]; readonly error: readonly [error: unknown]; }` | Declares the client's event map — lean, errors `unknown`, no listener-error event. |
244
+ | `FetchHandler` | type | `(input: string, init?: FetchInit) => Promise<Response>` | Represents a minimal `fetch` — the subset of the global `fetch` a `PromptClientInterface` uses: open the SSE stream, POST an answer. Injected so a test drives the client with a scripted `Response` instead of a real network. |
245
+ | `FetchInit` | interface | `{ method?, headers?, body?, signal? }` | Represents the request init a `PromptClientInterface` passes to its `FetchHandler` — the `RequestInit` fields it actually sets. |
246
+ | `globalFetch` | function | `(input: string, init?: FetchInit) => Promise<Response>` | Implements the default `FetchHandler` — the global `fetch`, adapted to the minimal injected shape the `PromptClient` uses. |
247
+ | `isAbortError` | function | `(error: unknown) => boolean` | Checks whether a caught value is an `AbortError` — the `PromptClient` distinguishes a deliberate `disconnect` / teardown (an aborted `fetch`) from a real fault, so it exits its connect loop quietly instead of emitting `error` / reconnecting. |
248
+ | `isInsecureRemote` | function | `(url: string) => boolean` | Checks whether `url` is an insecure remote endpoint — a plain `http://` URL whose host is not a loopback address. Pure string parsing (no `URL` global), so it stays total on malformed input; the `PromptClient` warns once when a `token` would cross such an endpoint in cleartext. |
249
249
 
250
250
  ### The terminal manager
251
251
 
@@ -254,14 +254,14 @@ A named registry of brokers, so several parties can ask forms of each other by n
254
254
 
255
255
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
256
256
 
257
- | API | Kind | Shape | Summary |
258
- | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
259
- | `TerminalManagerInterface` | interface | `{ emitter, count } plus terminal / terminals / add / ask / pending / answer / open / save / remove / destroy` | Declares a registry of named `PromptInterface` brokers, one per endpoint, so several parties (agents, tools, humans) can ask forms of each other by name, attributed with a `from` → `to` edge on every parked record. |
260
- | `TerminalManager` | class | `TerminalManagerInterface` | Registers named `PromptInterface` brokers, one per endpoint, so several parties can `ask` forms of each other by name with a `from` → `to` attribution edge on every parked form, and refuses `DEADLOCK` on a transitive cycle across every in-flight ask. |
261
- | `createTerminalManager` | function | `(options?: TerminalManagerOptions) => TerminalManagerInterface` | Creates the multi-endpoint `TerminalManager` — a named registry of `PromptInterface` brokers so several parties can `ask` forms of each other by name, with a transitive cycle check that refuses `DEADLOCK` across every in-flight ask. |
262
- | `TerminalManagerOptions` | interface | `{ store?, timeout?, timer?, cap?, on?, error? }` | Configures `createTerminalManager` and the `TerminalManagerInterface`. |
263
- | `TerminalManagerEventMap` | type | `{ pending, answer, expire }` | Declares the manager's event map — the name-attributed re-emission of every mounted broker's events, so a caller subscribes once for every endpoint instead of once per broker. |
264
- | `TerminalAnswerError` | type | `AnswerError \| { reason: 'target' }` | Explains why a `TerminalManagerInterface.answer` call refused — an `AnswerError` from the endpoint's own broker, or `target` when no endpoint is mounted under that name. That is the same condition `TerminalErrorCode`'s `TARGET` names for `TerminalManagerInterface.ask`, so one word carries it on both doors. One discriminant, `reason`, across every member. |
257
+ | Name | Kind | Signature | Summary |
258
+ | -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
259
+ | `TerminalManagerInterface` | interface | `{ emitter, count, terminal(), terminals(), add(), ask(), pending(), answer(), open(), save(), remove(), destroy() }` | Declares a registry of named `PromptInterface` brokers, one per endpoint, so several parties (agents, tools, humans) can ask forms of each other by name, attributed with a `from` → `to` edge on every parked record. |
260
+ | `TerminalManager` | class | `new (options?: TerminalManagerOptions) => TerminalManagerInterface` | Registers named `PromptInterface` brokers, one per endpoint, so several parties can `ask` forms of each other by name with a `from` → `to` attribution edge on every parked form, and refuses `DEADLOCK` on a transitive cycle across every in-flight ask. |
261
+ | `createTerminalManager` | function | `(options?: TerminalManagerOptions) => TerminalManagerInterface` | Creates the multi-endpoint `TerminalManager` — a named registry of `PromptInterface` brokers so several parties can `ask` forms of each other by name, with a transitive cycle check that refuses `DEADLOCK` across every in-flight ask. |
262
+ | `TerminalManagerOptions` | interface | `{ store?, timeout?, timer?, cap?, on?, error? }` | Configures `createTerminalManager` and the `TerminalManagerInterface`. |
263
+ | `TerminalManagerEventMap` | type | `{ readonly pending: readonly [form: PendingForm]; readonly answer: readonly [to: string, id: string, values: FormValues]; readonly expire: readonly [to: string, id: string]; }` | Declares the manager's event map — the name-attributed re-emission of every mounted broker's events, so a caller subscribes once for every endpoint instead of once per broker. |
264
+ | `TerminalAnswerError` | type | `AnswerError \| { readonly reason: 'target'; }` | Explains why a `TerminalManagerInterface.answer` call refused — an `AnswerError` from the endpoint's own broker, or `target` when no endpoint is mounted under that name. That is the same condition `TerminalErrorCode`'s `TARGET` names for `TerminalManagerInterface.ask`, so one word carries it on both doors. One discriminant, `reason`, across every member. |
265
265
 
266
266
  ### The terminal store
267
267
 
@@ -270,16 +270,16 @@ form is process-bound and is never resurrected ([`src/core`](../src/core)).
270
270
 
271
271
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
272
272
 
273
- | API | Kind | Shape | Summary |
274
- | ----------------------------- | --------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
275
- | `TerminalStoreInterface` | interface | `{} plus get / set / delete` | Declares the point-access persistence seam for a `TerminalManagerInterface`'s endpoint configs. Every primitive is async; deleting an absent id is a no-op. |
276
- | `TerminalSnapshot` | interface | `{ id, timeout? }` | Represents one endpoint's persisted config snapshot — `id` is the endpoint name and `timeout` its configured default. Parked forms are process-bound and are never resurrected, so `open` always restores an empty broker. |
277
- | `TerminalSnapshotRow` | interface | `{ id, snapshot }` | Represents one opaque persisted row — the shape a table-backed store reads and writes. The store is a `TableInterface<TerminalSnapshotRow>`, and `snapshot` is narrowed with `isTerminalSnapshot` on read. |
278
- | `isTerminalSnapshot` | const | `TerminalSnapshot` | Narrows an unknown value to a `TerminalSnapshot` — a non-empty `id` and an optional numeric `timeout`, the read boundary a store applies to an untrusted persisted row. |
279
- | `MemoryTerminalStore` | class | `TerminalStoreInterface` | Implements the in-memory `TerminalStoreInterface` — a process-lifetime `Map` of `TerminalSnapshot` records keyed by endpoint id, the default store `createMemoryTerminalStore` builds and the exact twin of `DatabaseTerminalStore`. It carries no idle expiry and no eviction. |
280
- | `DatabaseTerminalStore` | class | `TerminalStoreInterface` | Implements a `TerminalStoreInterface` backed by one table of the `databases` layer — an endpoint's durable config state is a row, so persistence reduces to keyed point-access (`get` / `set` / `delete`) over a `TableInterface`, the driver-pluggable twin of the plain-`Map` `MemoryTerminalStore`. A stored `snapshot` is narrowed with `isTerminalSnapshot` on read. |
281
- | `createMemoryTerminalStore` | function | `() => TerminalStoreInterface` | Creates the in-memory `TerminalStoreInterface` — a process-lifetime `Map` of endpoint config snapshots, the default store backing a `TerminalManagerInterface`'s `open` / `save`. |
282
- | `createDatabaseTerminalStore` | function | `(driver?: DriverInterface) => TerminalStoreInterface` | Creates a `TerminalStoreInterface` backed by one table of the `databases` layer — the driver-pluggable twin of `createMemoryTerminalStore`, storing each endpoint's config snapshot as one opaque JSON column. The default driver is an in-memory `@orkestrel/database` driver. |
273
+ | Name | Kind | Signature | Summary |
274
+ | ----------------------------- | --------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
275
+ | `TerminalStoreInterface` | interface | `{ get(), set(), delete() }` | Declares the point-access persistence seam for a `TerminalManagerInterface`'s endpoint configs. Every primitive is async; deleting an absent id is a no-op. |
276
+ | `TerminalSnapshot` | interface | `{ id, timeout? }` | Represents one endpoint's persisted config snapshot — `id` is the endpoint name and `timeout` its configured default. Parked forms are process-bound and are never resurrected, so `open` always restores an empty broker. |
277
+ | `TerminalSnapshotRow` | interface | `{ id, snapshot }` | Represents one opaque persisted row — the shape a table-backed store reads and writes. The store is a `TableInterface<TerminalSnapshotRow>`, and `snapshot` is narrowed with `isTerminalSnapshot` on read. |
278
+ | `isTerminalSnapshot` | const | `Guard<TerminalSnapshot>` | Narrows an unknown value to a `TerminalSnapshot` — a non-empty `id` and an optional numeric `timeout`, the read boundary a store applies to an untrusted persisted row. |
279
+ | `MemoryTerminalStore` | class | `new () => TerminalStoreInterface` | Implements the in-memory `TerminalStoreInterface` — a process-lifetime `Map` of `TerminalSnapshot` records keyed by endpoint id, the default store `createMemoryTerminalStore` builds and the exact twin of `DatabaseTerminalStore`. It carries no idle expiry and no eviction. |
280
+ | `DatabaseTerminalStore` | class | `new (table: TableInterface<TerminalSnapshotRow>) => TerminalStoreInterface` | Implements a `TerminalStoreInterface` backed by one table of the `databases` layer — an endpoint's durable config state is a row, so persistence reduces to keyed point-access (`get` / `set` / `delete`) over a `TableInterface`, the driver-pluggable twin of the plain-`Map` `MemoryTerminalStore`. A stored `snapshot` is narrowed with `isTerminalSnapshot` on read. |
281
+ | `createMemoryTerminalStore` | function | `() => TerminalStoreInterface` | Creates the in-memory `TerminalStoreInterface` — a process-lifetime `Map` of endpoint config snapshots, the default store backing a `TerminalManagerInterface`'s `open` / `save`. |
282
+ | `createDatabaseTerminalStore` | function | `(driver?: DriverInterface) => TerminalStoreInterface` | Creates a `TerminalStoreInterface` backed by one table of the `databases` layer — the driver-pluggable twin of `createMemoryTerminalStore`, storing each endpoint's config snapshot as one opaque JSON column. The default driver is an in-memory `@orkestrel/database` driver. |
283
283
 
284
284
  ### The terminal error
285
285
 
@@ -289,11 +289,11 @@ re-coded ([`src/core`](../src/core)).
289
289
 
290
290
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
291
291
 
292
- | API | Kind | Shape | Summary |
292
+ | Name | Kind | Signature | Summary |
293
293
  | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
294
294
  | `TerminalErrorCode` | type | `'EXPIRE' \| 'CANCEL' \| 'DRIVER' \| 'DEADLOCK' \| 'TARGET' \| 'LIMIT' \| 'DESTROYED'` | Names the machine-readable condition carried by a `TerminalError` — the axis a `catch` branches on. Names its axis (the failure condition), never `kind`. |
295
295
  | `TerminalError` | class | `new (code: TerminalErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => TerminalError` | Represents the error the terminal surfaces for its own refusals: parking on a destroyed or full broker, an unusable driver stream, a manager routing fault, or a ctrl-c cancellation. A parked form's own lifecycle failures reject through the form's `answer` with the form package's error, never with this one. |
296
- | `isTerminalError` | function | `TerminalError` | Narrows an unknown caught value to a `TerminalError`, so a caller can branch on its `code`. |
296
+ | `isTerminalError` | function | `(value: unknown) => value is TerminalError` | Narrows an unknown caught value to a `TerminalError`, so a caller can branch on its `code`. |
297
297
 
298
298
  ### The core constants
299
299
 
@@ -304,32 +304,32 @@ appears in source.
304
304
 
305
305
  A `Shape` cell holds the constant's declared type.
306
306
 
307
- | API | Kind | Shape | Summary |
308
- | ---------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
309
- | `RETURN` | const | `string` | Names the carriage return byte (`\r`, U+000D) — Enter on most terminals. |
310
- | `NEWLINE` | const | `string` | Names the line feed byte (`\n`, U+000A) — Enter on some terminals / pasted input. |
311
- | `TAB` | const | `string` | Names the tab byte (`\t`, U+0009). |
312
- | `BACKSPACE` | const | `string` | Names the backspace byte (BS, U+0008) — Ctrl+H / some terminals' Backspace. |
313
- | `DELETE` | const | `string` | Names the delete byte (DEL, U+007F) — the usual Backspace byte on a Unix TTY. |
314
- | `SPACE` | const | `string` | Names the space byte (U+0020). |
315
- | `CTRL_C` | const | `string` | Names the Ctrl+C byte (ETX, U+0003) — interrupt / cancel. |
316
- | `CTRL_D` | const | `string` | Names the Ctrl+D byte (EOT, U+0004) — end-of-transmission / finish (the editor's commit key). |
317
- | `CTRL_U` | const | `string` | Names the Ctrl+U byte (NAK, U+0015) — clear the current line. |
318
- | `CTRL_A` | const | `string` | Names the Ctrl+A byte (SOH, U+0001) — move to start of line. |
319
- | `CTRL_E` | const | `string` | Names the Ctrl+E byte (ENQ, U+0005) — move to end of line. |
320
- | `KEY_SS3` | const | `string` | Names the Single Shift Three lead (`ESCO`) — the alternate arrow-key prefix some terminals emit (`ESC O A`). Built from the console module's own `ESC`; the navigation keys' CSI lead is that module's `CSI`, which this package reuses rather than redeclaring. |
321
- | `SEQUENCE_NAMES` | const | `Readonly<Record<string, string>>` | Holds the exact escape sequence to canonical key name table `parseKey` consults for the navigation and editing keys. Covers the CSI form (`ESC[A`…) and the SS3 form (`ESCOA`…) of the arrows, plus the `home` / `end` / `delete` CSI sequences with their numeric-tilde variants. The source of truth for the multi-byte key decode; frozen. |
322
- | `CONTROL_NAMES` | const | `Readonly<Record<string, { readonly name: string; readonly ctrl: boolean }>>` | Holds the control byte (or CRLF pair) to key descriptor table `parseKey` consults for the one-byte keys and the two-byte CRLF Enter chunk. Each entry carries the canonical `name` and whether it is a `ctrl` combination. The source of truth for that decode; frozen. |
323
- | `DEFAULT_MASK` | const | `string` | Names the default mask glyph `createPasswordState` uses — `*`. |
324
- | `PROMPT_ICONS` | const | `Readonly<{ readonly question: string; readonly pointer: string; readonly dot: string; readonly selected: string; readonly checked: string; readonly unchecked: string }>` | Holds the terminal-owned glyphs `DEFAULT_PROMPT_THEME` assembles its `icons` from, beside the console module's own success and error marks. Read only when the default theme is assembled; a view reads its resolved theme and never this constant. Frozen. |
325
- | `PROMPT_ROLES` | const | `readonly PromptRole[]` | Holds every `PromptRole`, in one frozen list — the role axis's source of truth. `createPromptTheme` walks it to merge a partial theme, and a consumer building a complete role map reads it rather than retyping every name. |
326
- | `DEFAULT_PROMPT_THEME` | const | `PromptTheme` | Holds the `PromptTheme` every prompt renders with unless its options supply another — the glyph set assembled from `PROMPT_ICONS` plus the console `STATUS_ICONS` `success` / `error` marks, and the console `Style` each role is painted with. Deeply frozen through the console module's own `freezeStyle`; the baseline `createPromptTheme` merges a partial theme over. |
327
- | `DEFAULT_PROMPT_TIMEOUT_MS` | const | `number` | Holds how long (ms) the `PromptInterface` broker parks an unanswered form before it expires — 5 minutes. |
328
- | `DEFAULT_RECONNECT_DELAY_MS` | const | `number` | Holds how long (ms) the `PromptClientInterface` waits before each reconnect attempt — 2 seconds. |
329
- | `SSE_EVENTS` | const | `Readonly<{ readonly pending: string; readonly expire: string; readonly destroy: string }>` | Holds the SSE `event:` names the broker emits and the `PromptClientInterface` dispatches on — `pending`, `expire`, and `destroy`. Frozen; the source of truth for the wire event vocabulary. |
330
- | `HEADER_TOKEN` | const | `string` | Names the auth-token request header the `PromptClientInterface` sends when a `token` is configured — `x-orkestrel-token`. |
331
- | `ACCEPT_EVENT_STREAM` | const | `string` | Names the `Accept` header value that opens the broker's SSE stream — `text/event-stream`. |
332
- | `SSE_BUFFER_LIMIT` | const | `number` | Sets the maximum number of characters the `PromptClientInterface` lets its SSE parser buffer before treating the stream as hostile — 1 MiB, comfortably above any legitimate prompt payload. Passed as the `limit` to `createSSEParser` so an unterminated or oversized `data:` field cannot grow the buffer without bound (a memory-exhaustion guard). |
307
+ | Name | Kind | Signature | Summary |
308
+ | ---------------------------- | ----- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
309
+ | `RETURN` | const | `string` | Names the carriage return byte (`\r`, U+000D) — Enter on most terminals. |
310
+ | `NEWLINE` | const | `string` | Names the line feed byte (`\n`, U+000A) — Enter on some terminals / pasted input. |
311
+ | `TAB` | const | `string` | Names the tab byte (`\t`, U+0009). |
312
+ | `BACKSPACE` | const | `string` | Names the backspace byte (BS, U+0008) — Ctrl+H / some terminals' Backspace. |
313
+ | `DELETE` | const | `string` | Names the delete byte (DEL, U+007F) — the usual Backspace byte on a Unix TTY. |
314
+ | `SPACE` | const | `" "` | Names the space byte (U+0020). |
315
+ | `CTRL_C` | const | `string` | Names the Ctrl+C byte (ETX, U+0003) — interrupt / cancel. |
316
+ | `CTRL_D` | const | `string` | Names the Ctrl+D byte (EOT, U+0004) — end-of-transmission / finish (the editor's commit key). |
317
+ | `CTRL_U` | const | `string` | Names the Ctrl+U byte (NAK, U+0015) — clear the current line. |
318
+ | `CTRL_A` | const | `string` | Names the Ctrl+A byte (SOH, U+0001) — move to start of line. |
319
+ | `CTRL_E` | const | `string` | Names the Ctrl+E byte (ENQ, U+0005) — move to end of line. |
320
+ | `KEY_SS3` | const | `string` | Names the Single Shift Three lead (`ESCO`) — the alternate arrow-key prefix some terminals emit (`ESC O A`). Built from the console module's own `ESC`; the navigation keys' CSI lead is that module's `CSI`, which this package reuses rather than redeclaring. |
321
+ | `SEQUENCE_NAMES` | const | `Readonly<Record<string, string>>` | Holds the exact escape sequence to canonical key name table `parseKey` consults for the navigation and editing keys. Covers the CSI form (`ESC[A`…) and the SS3 form (`ESCOA`…) of the arrows, plus the `home` / `end` / `delete` CSI sequences with their numeric-tilde variants. The source of truth for the multi-byte key decode; frozen. |
322
+ | `CONTROL_NAMES` | const | `Readonly<Record<string, { readonly name: string; readonly ctrl: boolean; }>>` | Holds the control byte (or CRLF pair) to key descriptor table `parseKey` consults for the one-byte keys and the two-byte CRLF Enter chunk. Each entry carries the canonical `name` and whether it is a `ctrl` combination. The source of truth for that decode; frozen. |
323
+ | `DEFAULT_MASK` | const | `"*"` | Names the default mask glyph `createPasswordState` uses — `*`. |
324
+ | `PROMPT_ICONS` | const | `Readonly<{ question: "?"; pointer: "›"; dot: "○"; selected: "●"; checked: "☑"; unchecked: "☐"; }>` | Holds the terminal-owned glyphs `DEFAULT_PROMPT_THEME` assembles its `icons` from, beside the console module's own success and error marks. Read only when the default theme is assembled; a view reads its resolved theme and never this constant. Frozen. |
325
+ | `PROMPT_ROLES` | const | `readonly PromptRole[]` | Holds every `PromptRole`, in one frozen list — the role axis's source of truth. `createPromptTheme` walks it to merge a partial theme, and a consumer building a complete role map reads it rather than retyping every name. |
326
+ | `DEFAULT_PROMPT_THEME` | const | `PromptTheme` | Holds the `PromptTheme` every prompt renders with unless its options supply another — the glyph set assembled from `PROMPT_ICONS` plus the console `STATUS_ICONS` `success` / `error` marks, and the console `Style` each role is painted with. Deeply frozen through the console module's own `freezeStyle`; the baseline `createPromptTheme` merges a partial theme over. |
327
+ | `DEFAULT_PROMPT_TIMEOUT_MS` | const | `300000` | Holds how long (ms) the `PromptInterface` broker parks an unanswered form before it expires — 5 minutes. |
328
+ | `DEFAULT_RECONNECT_DELAY_MS` | const | `2000` | Holds how long (ms) the `PromptClientInterface` waits before each reconnect attempt — 2 seconds. |
329
+ | `SSE_EVENTS` | const | `Readonly<{ pending: "pending"; expire: "expire"; destroy: "destroy"; }>` | Holds the SSE `event:` names the broker emits and the `PromptClientInterface` dispatches on — `pending`, `expire`, and `destroy`. Frozen; the source of truth for the wire event vocabulary. |
330
+ | `HEADER_TOKEN` | const | `"x-orkestrel-token"` | Names the auth-token request header the `PromptClientInterface` sends when a `token` is configured — `x-orkestrel-token`. |
331
+ | `ACCEPT_EVENT_STREAM` | const | `"text/event-stream"` | Names the `Accept` header value that opens the broker's SSE stream — `text/event-stream`. |
332
+ | `SSE_BUFFER_LIMIT` | const | `1048576` | Sets the maximum number of characters the `PromptClientInterface` lets its SSE parser buffer before treating the stream as hostile — 1 MiB, comfortably above any legitimate prompt payload. Passed as the `limit` to `createSSEParser` so an unterminated or oversized `data:` field cannot grow the buffer without bound (a memory-exhaustion guard). |
333
333
 
334
334
  ### The server Terminal
335
335
 
@@ -339,35 +339,35 @@ raw-mode stdin, drives the core reducers, renders each view in place, and falls
339
339
 
340
340
  A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
341
341
 
342
- | API | Kind | Shape | Summary |
343
- | ---------------------- | --------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
344
- | `Terminal` | class | `TerminalInterface` | Implements `TerminalInterface` for a human at this machine's keyboard — the interactive form driver, and the only impure part of the terminal stack. `ask` walks one form's fields in schema order, feeds raw-mode stdin bytes through `parseKey` into the matching pure reducer, renders each returned view in place, binds every answer through the form's own `fill`, and re-asks what the form refused. It owns no form logic: the schema, the rules, the values, and the settlement all belong to the form it is given, and this class owns only raw mode, the cursor, and the re-render. |
345
- | `createTerminal` | function | `(options?: TerminalOptions) => TerminalInterface` | Creates the interactive terminal form driver — the local-keyboard arm of the terminal trio, beside the core headless `createPrompt` broker and the SSE `createPromptClient` bridge. Where the broker parks a live form until somebody elsewhere answers it, a `Terminal` answers one here: it walks the form's fields in schema order, drives each control's pure reducer over raw-mode stdin, binds every answer through the form's own `fill`, and submits. It is the only impure part of the terminal stack. |
346
- | `TerminalOptions` | interface | `{ input?, output?, theme? }` | Configures `createTerminal` — every member optional, so a bare `createTerminal()` walks a form over the real `process.stdin` / `process.stdout` with the default theme. |
347
- | `InputStreamInterface` | interface | `{ isTTY? } plus on / off / setRawMode? / resume? / pause?` | Represents the minimal input-stream shape the driver reads — exactly the slice of a Node `tty.ReadStream` / `process.stdin` it touches, and no more. A `TerminalOptions` `input` is narrowed to this through `isInputStream`, never an assertion, so a test drives a whole form with a hand-built fake stream that emits scripted key chunks, never touches the real `process.stdin`, and asserts that raw mode is entered once and always cleaned up. |
342
+ | Name | Kind | Signature | Summary |
343
+ | ---------------------- | --------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
344
+ | `Terminal` | class | `new (options?: TerminalOptions) => TerminalInterface` | Implements `TerminalInterface` for a human at this machine's keyboard — the interactive form driver, and the only impure part of the terminal stack. `ask` walks one form's fields in schema order, feeds raw-mode stdin bytes through `parseKey` into the matching pure reducer, renders each returned view in place, binds every answer through the form's own `fill`, and re-asks what the form refused. It owns no form logic: the schema, the rules, the values, and the settlement all belong to the form it is given, and this class owns only raw mode, the cursor, and the re-render. |
345
+ | `createTerminal` | function | `(options?: TerminalOptions) => TerminalInterface` | Creates the interactive terminal form driver — the local-keyboard arm of the terminal trio, beside the core headless `createPrompt` broker and the SSE `createPromptClient` bridge. Where the broker parks a live form until somebody elsewhere answers it, a `Terminal` answers one here: it walks the form's fields in schema order, drives each control's pure reducer over raw-mode stdin, binds every answer through the form's own `fill`, and submits. It is the only impure part of the terminal stack. |
346
+ | `TerminalOptions` | interface | `{ input?, output?, theme? }` | Configures `createTerminal` — every member optional, so a bare `createTerminal()` walks a form over the real `process.stdin` / `process.stdout` with the default theme. |
347
+ | `InputStreamInterface` | interface | `{ on(), off(), setRawMode?(), resume?(), pause?(), isTTY? }` | Represents the minimal input-stream shape the driver reads — exactly the slice of a Node `tty.ReadStream` / `process.stdin` it touches, and no more. A `TerminalOptions` `input` is narrowed to this through `isInputStream`, never an assertion, so a test drives a whole form with a hand-built fake stream that emits scripted key chunks, never touches the real `process.stdin`, and asserts that raw mode is entered once and always cleaned up. |
348
348
 
349
349
  ### The server helpers
350
350
 
351
351
  The stream guards, the cursor math behind the in-place re-render, and the per-field line projections
352
352
  the walk renders with ([`src/server`](../src/server)). All pure, all exported, all unit-tested.
353
353
 
354
- | API | Kind | Summary |
355
- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
356
- | `isInputStream` | function | Checks whether `value` is a usable `InputStreamInterface` — a record with callable `on` / `off` `'data'` subscription methods. A total type guard: it never throws and returns `false` for anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`, or a fake TTY a test injects) to the exact slice the driver reads, never an assertion. |
357
- | `isReadable` | function | Checks whether `value` is a Node `NodeJS.ReadableStream` — a total structural guard checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface` requires as its `input`. The non-TTY fallback narrows the resolved input stream through this before handing it to readline, never through an assertion, so a real piped `process.stdin` (or a `PassThrough` a test injects) crosses into the readline boundary honestly. Never throws; returns `false` for a minimal fake that isn't a full readable. |
358
- | `supportsRawMode` | function | Checks whether an input stream can be driven in raw mode — it reports `isTTY === true` and exposes a callable `setRawMode`. The `Terminal` probes this to choose its path: true selects the interactive raw-mode fields, with arrow-key navigation and a live re-render; false selects the `node:readline` line-input fallback, because a piped or non-terminal stream cannot enter raw mode. Total — never throws. |
359
- | `lineCount` | function | Counts the terminal lines a rendered prompt `view` occupies — one more than its newline count, so a view with no newline is a single line and a view with N newlines spans N+1 lines. The basis of the in-place re-render: the driver records the line count of the view it wrote so the next redraw knows how far up to move the cursor before overwriting. Total; an empty string is one empty line. |
360
- | `renderCursorUp` | function | Returns the cursor-up control sequence that moves the cursor up `count` lines (`ESC[{count}A`), or the empty string when `count` is zero or negative, because no movement is needed and `ESC[0A` is a wasted write. The pure step the in-place re-render uses to climb back over the previous view before clearing it. Total. |
361
- | `redrawPrefix` | function | Returns the full reposition-and-clear prefix to write before re-rendering a prompt view in place — given the line count of the previous view, it moves the cursor up over those lines, returns it to column 0, and erases everything from there to the end of the screen, so the next view is drawn on a clean region and a taller previous view leaves no orphaned rows. Pure; the driver writes this immediately followed by the new view. |
362
- | `fieldToText` | function | Projects any field the walk reads as a line of text into the `TextField` the text reducer takes — `text` itself, and the controls a terminal has no widget for: `number`, `date`, `time`, `datetime`, `color`, one `list` entry, and one `file` entry. The label carries that control's format cue from `CONTROL_HINTS`, and a declared `default` becomes the line a bare return submits. The projection carries no rule, because the authoritative form still evaluates the answer this line binds; it exists only so one reducer covers every one of them. |
363
- | `valueToText` | function | Projects one held answer into the text a read-only line shows — a scalar as itself, a boolean as `yes` / `no` (the word the confirm reducer commits), and a list joined by commas. Absence renders as nothing, because a locked field nobody has answered has nothing to show. |
364
- | `filterEnabled` | function | Returns the choices a `select` or `checkbox` field actually offers — the form refuses a disabled choice's value at every door, including a fill, so the walk never puts one in front of the cursor. Pair with `filterDisabled` to tell the reader what was withheld. |
365
- | `filterDisabled` | function | Returns the choices a `select` or `checkbox` field shows but refuses — the complement of `filterEnabled`, rendered by `renderUnavailableLine` above the list so a reader sees why a declared choice is missing from it. |
366
- | `renderGroupHeader` | function | Renders the section header the walk writes when it enters a new field group, painted by the `message` role. |
367
- | `renderLockedLine` | function | Renders the read-only line a locked field shows — its label, the `LOCKED_MARK`, and the answer the form already holds. The walk writes this instead of a prompt, because the field is still validated and still submitted but must not be edited here. |
368
- | `renderSuggestionLine` | function | Renders the line listing an open select's offered values above its text prompt — a suggestion list, because an open select admits an answer the list does not offer. |
369
- | `renderUnavailableLine` | function | Renders the line naming the choices a field shows but refuses, written above the list the walk drives. |
370
- | `renderNumberedList` | function | Renders the numbered choice list the non-TTY fallback prints — a piped stream cannot navigate with arrow keys, so each offered choice is printed with the number the reader types back. One line per choice, with no trailing newline. |
354
+ | Name | Kind | Signature | Summary |
355
+ | ----------------------- | -------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
356
+ | `isInputStream` | function | `(value: unknown) => value is InputStreamInterface` | Checks whether `value` is a usable `InputStreamInterface` — a record with callable `on` / `off` `'data'` subscription methods. A total type guard: it never throws and returns `false` for anything off-shape, so it narrows the one unavoidable input boundary (the real `process.stdin`, or a fake TTY a test injects) to the exact slice the driver reads, never an assertion. |
357
+ | `isReadable` | function | `(value: unknown) => value is NodeJS.ReadableStream` | Checks whether `value` is a Node `NodeJS.ReadableStream` — a total structural guard checking for the callable `read` / `pipe` / `on` that `node:readline`'s `createInterface` requires as its `input`. The non-TTY fallback narrows the resolved input stream through this before handing it to readline, never through an assertion, so a real piped `process.stdin` (or a `PassThrough` a test injects) crosses into the readline boundary honestly. Never throws; returns `false` for a minimal fake that isn't a full readable. |
358
+ | `supportsRawMode` | function | `(input: InputStreamInterface) => boolean` | Checks whether an input stream can be driven in raw mode — it reports `isTTY === true` and exposes a callable `setRawMode`. The `Terminal` probes this to choose its path: true selects the interactive raw-mode fields, with arrow-key navigation and a live re-render; false selects the `node:readline` line-input fallback, because a piped or non-terminal stream cannot enter raw mode. Total — never throws. |
359
+ | `lineCount` | function | `(view: string) => number` | Counts the terminal lines a rendered prompt `view` occupies — one more than its newline count, so a view with no newline is a single line and a view with N newlines spans N+1 lines. The basis of the in-place re-render: the driver records the line count of the view it wrote so the next redraw knows how far up to move the cursor before overwriting. Total; an empty string is one empty line. |
360
+ | `renderCursorUp` | function | `(count: number) => string` | Returns the cursor-up control sequence that moves the cursor up `count` lines (`ESC[{count}A`), or the empty string when `count` is zero or negative, because no movement is needed and `ESC[0A` is a wasted write. The pure step the in-place re-render uses to climb back over the previous view before clearing it. Total. |
361
+ | `redrawPrefix` | function | `(previousLines: number) => string` | Returns the full reposition-and-clear prefix to write before re-rendering a prompt view in place — given the line count of the previous view, it moves the cursor up over those lines, returns it to column 0, and erases everything from there to the end of the screen, so the next view is drawn on a clean region and a taller previous view leaves no orphaned rows. Pure; the driver writes this immediately followed by the new view. |
362
+ | `fieldToText` | function | `(field: FormField) => TextField` | Projects any field the walk reads as a line of text into the `TextField` the text reducer takes — `text` itself, and the controls a terminal has no widget for: `number`, `date`, `time`, `datetime`, `color`, one `list` entry, and one `file` entry. The label carries that control's format cue from `CONTROL_HINTS`, and a declared `default` becomes the line a bare return submits. The projection carries no rule, because the authoritative form still evaluates the answer this line binds; it exists only so one reducer covers every one of them. |
363
+ | `valueToText` | function | `(value: FieldValue \| undefined) => string` | Projects one held answer into the text a read-only line shows — a scalar as itself, a boolean as `yes` / `no` (the word the confirm reducer commits), and a list joined by commas. Absence renders as nothing, because a locked field nobody has answered has nothing to show. |
364
+ | `filterEnabled` | function | `(choices: readonly FieldChoice[]) => readonly FieldChoice[]` | Returns the choices a `select` or `checkbox` field actually offers — the form refuses a disabled choice's value at every door, including a fill, so the walk never puts one in front of the cursor. Pair with `filterDisabled` to tell the reader what was withheld. |
365
+ | `filterDisabled` | function | `(choices: readonly FieldChoice[]) => readonly FieldChoice[]` | Returns the choices a `select` or `checkbox` field shows but refuses — the complement of `filterEnabled`, rendered by `renderUnavailableLine` above the list so a reader sees why a declared choice is missing from it. |
366
+ | `renderGroupHeader` | function | `(styler: StylerInterface, theme: PromptTheme, label: string) => string` | Renders the section header the walk writes when it enters a new field group, painted by the `message` role. |
367
+ | `renderLockedLine` | function | `(styler: StylerInterface, theme: PromptTheme, label: string, value: string) => string` | Renders the read-only line a locked field shows — its label, the `LOCKED_MARK`, and the answer the form already holds. The walk writes this instead of a prompt, because the field is still validated and still submitted but must not be edited here. |
368
+ | `renderSuggestionLine` | function | `(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]) => string` | Renders the line listing an open select's offered values above its text prompt — a suggestion list, because an open select admits an answer the list does not offer. |
369
+ | `renderUnavailableLine` | function | `(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]) => string` | Renders the line naming the choices a field shows but refuses, written above the list the walk drives. |
370
+ | `renderNumberedList` | function | `(styler: StylerInterface, theme: PromptTheme, choices: readonly FieldChoice[]) => string` | Renders the numbered choice list the non-TTY fallback prints — a piped stream cannot navigate with arrow keys, so each offered choice is printed with the number the reader types back. One line per choice, with no trailing newline. |
371
371
 
372
372
  ### The server constants
373
373
 
@@ -377,23 +377,23 @@ character appears in source.
377
377
 
378
378
  A `Shape` cell holds the constant's declared type.
379
379
 
380
- | API | Kind | Shape | Summary |
380
+ | Name | Kind | Signature | Summary |
381
381
  | ------------------------ | ----- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
382
382
  | `CSI_UP` | const | `string` | Holds the cursor-up sequence template (`ESC[{count}A`) — `renderCursorUp` interpolates the `{count}` placeholder with the number of lines to climb. Kept as a template so the count stays out of the constant. |
383
383
  | `CURSOR_HIDE` | const | `string` | Hides the cursor (`ESC[?25l`) — written before the driver starts redrawing a prompt so the cursor does not flicker across the view during an in-place re-render; paired with `CURSOR_SHOW`. |
384
384
  | `CURSOR_SHOW` | const | `string` | Shows the cursor (`ESC[?25h`) — restores the cursor after a prompt resolves / cancels (the `CURSOR_HIDE` pair). |
385
385
  | `CLEAR_DOWN` | const | `string` | Erases from the cursor down to the end of the screen (`ESC[J`) — wipes the whole previous view, which a `select` or `checkbox` can spread over several lines, in one write before the new view is rendered, so a redraw never leaves orphaned rows behind. |
386
386
  | `CONTROL_HINTS` | const | `Readonly<Partial<Record<FieldControl, string>>>` | Holds the format cue appended to a field's label for each control the walk reads as a line of text — the terminal has no date picker, no color well, and no file chooser, so the accepted shape is stated instead. A control with no entry needs none: `text` and `editor` accept any line, `password` masks one, and `confirm`, `select`, and `checkbox` are answered by key rather than by format. The form's own rules still decide whether the typed value is acceptable. |
387
- | `FILE_HINT` | const | `string` | Holds the instruction a `file` field with `multiple` shows before its entries — one path per line, and a blank line ends the list. |
388
- | `LIST_HINT` | const | `string` | Holds the instruction a `list` field shows before its entries — one entry per line, and a blank line ends the list. |
389
- | `SUGGESTION_LEAD` | const | `string` | Holds the lead on the line listing an open `select`'s offered values, which a typed answer can ignore. |
390
- | `UNAVAILABLE_LEAD` | const | `string` | Holds the lead on the line listing the choices a `select` or `checkbox` shows but refuses, so a reader sees why one is missing from the list it heads. |
391
- | `LOCKED_MARK` | const | `string` | Holds the mark on a locked field's line — the walk renders its value and moves on, because the form refuses an edit there. |
392
- | `REFUSAL_MESSAGE` | const | `string` | States what a field is told when the walk read an answer the control cannot hold — a word typed into a `number`, an off-list value typed into an open `select` whose choice is refused. The value binds as absence and this message is invalidated onto the field, so the walk re-asks it with the reason on screen. |
393
- | `FALLBACK_SELECT_HINT` | const | `string` | Holds the numbered-list prompt the non-TTY `Terminal` `select` fallback appends — a piped (non-terminal) stream cannot navigate with arrow keys, so the choices are printed numbered and the user types one number on a single readline line. |
394
- | `FALLBACK_CHECKBOX_HINT` | const | `string` | Holds the comma-separated multi-select hint the non-TTY `checkbox` fallback shows (the user types one or more numbers). |
395
- | `FALLBACK_EDITOR_HINT` | const | `string` | Holds the hint the non-TTY `editor` fallback shows — a piped stream has no ctrl-d, so end of input finishes the block. |
396
- | `FALLBACK_CONFIRM_HINT` | const | `string` | Holds the hint the non-TTY `confirm` fallback shows — a piped stream sends a whole line, so the answer is typed rather than pressed. |
387
+ | `FILE_HINT` | const | `"One path per line, blank to finish"` | Holds the instruction a `file` field with `multiple` shows before its entries — one path per line, and a blank line ends the list. |
388
+ | `LIST_HINT` | const | `"One entry per line, blank to finish"` | Holds the instruction a `list` field shows before its entries — one entry per line, and a blank line ends the list. |
389
+ | `SUGGESTION_LEAD` | const | `"Suggestions"` | Holds the lead on the line listing an open `select`'s offered values, which a typed answer can ignore. |
390
+ | `UNAVAILABLE_LEAD` | const | `"Unavailable"` | Holds the lead on the line listing the choices a `select` or `checkbox` shows but refuses, so a reader sees why one is missing from the list it heads. |
391
+ | `LOCKED_MARK` | const | `"(locked)"` | Holds the mark on a locked field's line — the walk renders its value and moves on, because the form refuses an edit there. |
392
+ | `REFUSAL_MESSAGE` | const | `"Enter a value this field accepts"` | States what a field is told when the walk read an answer the control cannot hold — a word typed into a `number`, an off-list value typed into an open `select` whose choice is refused. The value binds as absence and this message is invalidated onto the field, so the walk re-asks it with the reason on screen. |
393
+ | `FALLBACK_SELECT_HINT` | const | `"Enter a number"` | Holds the numbered-list prompt the non-TTY `Terminal` `select` fallback appends — a piped (non-terminal) stream cannot navigate with arrow keys, so the choices are printed numbered and the user types one number on a single readline line. |
394
+ | `FALLBACK_CHECKBOX_HINT` | const | `"Enter numbers separated by commas"` | Holds the comma-separated multi-select hint the non-TTY `checkbox` fallback shows (the user types one or more numbers). |
395
+ | `FALLBACK_EDITOR_HINT` | const | `"(end of input finishes)"` | Holds the hint the non-TTY `editor` fallback shows — a piped stream has no ctrl-d, so end of input finishes the block. |
396
+ | `FALLBACK_CONFIRM_HINT` | const | `"(y/n)"` | Holds the hint the non-TTY `confirm` fallback shows — a piped stream sends a whole line, so the answer is typed rather than pressed. |
397
397
 
398
398
  ## Methods
399
399