@orkestrel/scaffold 0.0.119 → 0.0.121
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.
- package/dist/bin/main.js +19 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +52 -51
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
|
@@ -273,7 +273,7 @@ The core supplies the entities a browser session and an agent use. Its host-spec
|
|
|
273
273
|
| `BROWSER_DEFAULT_VIEWPORT_HEIGHT` | const | `720` | Sets the default viewport height, `720` pixels. |
|
|
274
274
|
| `BROWSER_DEFAULT_VIEWPORT_WIDTH` | const | `1280` | Sets the default viewport width, `1280` pixels. |
|
|
275
275
|
| `BROWSER_FRAME_WORLD_NAME` | const | `"__orkestrelBrowserFrame"` | Names the isolated world used for iframe evaluation, `'__orkestrelBrowserFrame'`. |
|
|
276
|
-
| `BROWSER_HAR_CREATOR` | const | `Readonly<{ name: "@orkestrel/browser"; version: "0.0.
|
|
276
|
+
| `BROWSER_HAR_CREATOR` | const | `Readonly<{ name: "@orkestrel/browser"; version: "0.0.31"; }>` | Names the tool identity embedded in HAR 1.2 documents. |
|
|
277
277
|
| `BROWSER_KEY_MODIFIERS` | const | `Readonly<Record<string, number>>` | Maps a canonical modifier name to its CDP Input modifier bit value. |
|
|
278
278
|
| `BROWSER_MOUSE_BUTTON_MASKS` | const | `Readonly<Record<BrowserMouseButton, number>>` | Maps each public mouse button to its CDP Input pressed-button bit value. |
|
|
279
279
|
| `BROWSER_NAVIGATION_REASONS` | const | `readonly BrowserNavigationReason[]` | Lists every CDP `Page.ClientNavigationReason` value a page accepts as a navigation's reason, as of Chromium 141; a page reads any other reason as undefined. |
|
|
@@ -36,8 +36,6 @@ budget.consume(7_000) // crosses 10_000 — fires `signal`
|
|
|
36
36
|
|
|
37
37
|
### Validators
|
|
38
38
|
|
|
39
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
40
|
-
|
|
41
39
|
| Name | Kind | Signature | Summary |
|
|
42
40
|
| ---------------- | -------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
43
41
|
| `isBudget` | function | `(value: unknown) => value is BudgetInterface<unknown>` | Determines whether a value implements `BudgetInterface`, returning `false` rather than throwing on hostile input. |
|
|
@@ -72,8 +70,6 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
|
72
70
|
|
|
73
71
|
### Types
|
|
74
72
|
|
|
75
|
-
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 `\|`.
|
|
76
|
-
|
|
77
73
|
| Name | Kind | Signature | Summary |
|
|
78
74
|
| -------------------- | --------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
75
|
| `BudgetOptions` | interface | `{ id?, max, consumer, signal? }` | Represents the options for constructing a cumulative budget, accepted by the `createBudget` function and the `Budget` constructor. |
|
|
@@ -124,7 +120,7 @@ These invariants hold across `src/core` ↔ `budget.md`:
|
|
|
124
120
|
8. **Traceable identity.** `id` is a stable string for the handle's lifetime — caller-supplied through `options.id`, including an empty string, or a `crypto.randomUUID()` default only when `id` is omitted. `max` is the validated ceiling, exposed read-only. The abort reason on owned exhaustion is a `BudgetError` coded `'exhaust'` with the fixed message `budget reached its ceiling`, whose `context` holds the `id`, `max`, and `consumed` at the crossing; a parent abort keeps the parent's reason, including when the parent aborted before the crossing and nothing had read the composite signal. `consume` tests the composed signal, not the owned controller, before it aborts the controller, so the parent's reason survives whether or not the host's `AbortSignal.any` has propagated the parent's abort yet; on Node 24.22.0 the propagation is eager and an owned-controller test gives the same reason.
|
|
125
121
|
9. **Strict once-read boundaries.** `validateBudgetOptions`, `validateTokenBudgetOptions`, `validateMeterOptions`, and `validateTokenMeterOptions` accept the typed contracts while defending their hostile JavaScript boundary: they require a plain record, read each declared property exactly once inside a contained boundary, validate with structured `ContractError` taxonomy/context, and return a fresh normalized object that omits absent optional keys. `Budget` calls the budget helper before allocating its controller; `createTokenBudget` calls the token helper before creating its consumer and public budget; `Meter` calls the meter helper before it stores anything; `createTokenMeter` calls the token-meter helper before it composes the meter.
|
|
126
122
|
10. **Validated token accounting.** `TokenScope` is the public `'completion' | 'total' | 'prompt'` selector and defaults to `completion` in `createTokenBudget`. Token factories reject unsupported scopes and malformed usage; all three `TokenUsage` fields must be finite and nonnegative before the selected charge is used.
|
|
127
|
-
11. **Total guards and cross-copy recognition.** `isBudget`, `isBudgetAmount`, `isBudgetError`, `isBudgetSignal`, `isTokenScope`, and `isTokenUsage` return `false`, rather than throw, for off-shape, hostile, or revoked input. `isBudgetError` uses the identity brand instead of `instanceof BudgetError`, while retaining the native `Error` base check. The constructor stamps `BUDGET_ERROR_BRAND`, the registry-global `Symbol.for('@orkestrel/budget.
|
|
123
|
+
11. **Total guards and cross-copy recognition.** `isBudget`, `isBudgetAmount`, `isBudgetError`, `isBudgetSignal`, `isTokenScope`, and `isTokenUsage` return `false`, rather than throw, for off-shape, hostile, or revoked input. `isBudgetError` uses the identity brand instead of `instanceof BudgetError`, while retaining the native `Error` base check. The constructor stamps `BUDGET_ERROR_BRAND`, the registry-global `Symbol.for('@orkestrel/budget.BudgetError')`, as a non-enumerable own property whose value is the error itself. The guard requires that exact identity, the native `Error` base, a prototype other than `Error.prototype`, the code `'exhaust'`, and a `context` holding a string `id` and number `max` and `consumed`. Subclass instances and renamed errors pass without reading `name`. One rule serves every copy: a reason built by another installation, or by the CommonJS entry when the guard came from the ESM entry, narrows exactly as one built by the same copy, and the reverse holds too. A transparent proxy over a genuine error is refused, because its forwarded descriptor stores the target. An unbranded `Error` carrying `code: 'exhaust'`, and an error from a copy that stamps no brand, such as 0.0.13, stay outside the type. The brand is a recognition marker, not proof of origin: a complete forgery that stamps its own identity under the key passes.
|
|
128
124
|
12. **Signal-only observation.** Neither `Budget` nor `Meter` has an Emitter, `EventMap`, or `on` hook. The budget's native `AbortSignal` is the observation mechanism.
|
|
129
125
|
13. **DOC ↔ SOURCE method bijection.** The `## Methods` tables list exactly the public methods of `BudgetInterface` and `MeterInterface` — exhaustive, both directions — and `Budget` and `Meter` expose the same public methods as their interfaces, no more.
|
|
130
126
|
14. **Growth metering.** `charge(delta)` refuses a non-string delta with a `literal`-coded `ContractError` before any state changes. It then counts the delta, estimates the whole text, refuses a nonfinite or negative estimate with a `range`-coded `ContractError`, and measures the estimate's growth over the growth the budget has accepted plus the growth of every charge still in flight. Only when that growth is positive does it consume `producer(growth)`. Each charge in flight holds a per-call claim of its growth from before the producer runs until the charge settles, so a charge that re-enters the meter synchronously, through the producer, the budget's consumer, or an abort listener the crossing fires, measures its own growth past the claims and the nested and outer charges sum to the serial result. `charged` is the total growth the budget accepted from this meter: it rises by a charge's growth only after the budget's `consume` returns, and a throw from the producer or the budget drops the claim and raises nothing. For a budget the meter alone charges and never clears, `charged` therefore equals the budget's `consumed` whenever no charge is in flight, in serial use, under re-entry through the producer or the budget's consumer, and under refusal. A nested charge an abort listener makes is added before the outer charge, which the budget added first, so with growths that are not integers the two can differ in the last digit. In serial use `charged` equals the latest accepted estimate up to floating-point rounding. A throw from the estimator, or a refused estimate, claims nothing. Every refusal leaves the delta counted, and the next charge measures the growth from the text that includes it. A meter has no reset; create one per stream.
|
|
@@ -194,7 +194,7 @@ Engine, runner, preflight, and contact-sheet contracts from [`types.ts`](../src/
|
|
|
194
194
|
| `CaptureOutcome` | interface | `{ project, variant, count }` | Carries one project's owner-bearing passed work count from a finished stage. |
|
|
195
195
|
| `CaptureRunPlan` | interface | `{ command, projects, selector, filter, case?, state?, final, directory, config }` | Carries everything every stage of one invocation shares. |
|
|
196
196
|
| `CaptureInvocationOptions` | interface | `{ command, root, requests, stdout, stderr, terminate?, ownership? }` | Configures one runner invocation's identity, workspace, and output. |
|
|
197
|
-
| `CaptureChildTerminationHandler` | type | `(child:
|
|
197
|
+
| `CaptureChildTerminationHandler` | type | `(child: DuplexInterface) => Promise<boolean>` | Terminates one supervised child and reports whether its exit was confirmed. |
|
|
198
198
|
| `CaptureInvocationInterface` | interface | `{ id, request, directory, signal, interrupted, attach(), release(), prepare(), holders(), publish(), retract(), launched(), spawn() }` | Owns one runner invocation's identity, request file, children, and interruption. |
|
|
199
199
|
| `CaptureDiscoveryRequest` | interface | `{ version, phase, id, nonce, config, pid, args }` | Carries the request the runner publishes for the discovery child that reads its wrapper. |
|
|
200
200
|
| `CaptureHostEntry` | interface | `{ project, viewport? }` | Describes one wrapper project to the runner: its host declarations and, when it has one, its viewport. |
|
|
@@ -588,7 +588,7 @@ const request = readCaptureRequest({
|
|
|
588
588
|
request?.selector // 'pages:mail' when a runner is the parent, otherwise undefined
|
|
589
589
|
```
|
|
590
590
|
|
|
591
|
-
**Processes.** The runner spawns `process.execPath` with the installed `node_modules/vitest/vitest.mjs`, an argument array, and no shell. The child inherits the environment with every case-folded `capture` name removed and `CAPTURE_REQUESTS` set to the request directory, and a `capture` command, like discovery, sets exactly one `CAPTURE=1`. Each stage writes its own log and JSON report under `<requests>/runs/<id>/`, and the child's output is teed to the host's streams and the log. Each child runs through `@orkestrel/process` `
|
|
591
|
+
**Processes.** The runner spawns `process.execPath` with the installed `node_modules/vitest/vitest.mjs`, an argument array, and no shell. The child inherits the environment with every case-folded `capture` name removed and `CAPTURE_REQUESTS` set to the request directory, and a `capture` command, like discovery, sets exactly one `CAPTURE=1`. Each stage writes its own log and JSON report under `<requests>/runs/<id>/`, and the child's output is teed to the host's streams and the log. Each child runs through `@orkestrel/process` `createDuplex` with stdin closed immediately. Its byte output is decoded with `StringDecoder`, preserving split UTF-8, carriage returns, and missing final newlines, and the decoder is flushed at termination. A writer or log failure, or a session whose output did not drain before its observation bound, refuses the stage. An interrupt aborts the stage's signal and ends each child's tree: Windows tree termination, or POSIX `SIGTERM` followed by `SIGKILL` after a 250 ms grace. A pre-aborted invocation launches no child. The invocation then removes its request and releases its handlers.
|
|
592
592
|
|
|
593
593
|
**Host evidence (2026-10-28).** A real console Ctrl+C on Windows and a process-group SIGINT through the built executable on Linux each ended the stage tree, started no later stage, removed the request, and left the manifest bytes unchanged. The Windows reading uses a console-capable terminal; the POSIX automated case runs only where its process-group mechanism is available.
|
|
594
594
|
|
|
@@ -121,6 +121,17 @@ read — is module data rather than public API, for the reason the Base64 alphab
|
|
|
121
121
|
| `decodeUTF16LE` | function | `(bytes: Uint8Array) => string \| undefined` | Decodes little-endian UTF-16 bytes into their text, reading two bytes per code unit, low byte first. An odd length and an unpaired surrogate are `undefined`. A leading FF FE is kept as U+FEFF rather than stripped. |
|
|
122
122
|
| `isUTF16LE` | function | `(value: unknown) => value is Uint8Array` | Checks whether a value is bytes that decode as UTF-16LE — true for exactly the byte sequences `decodeUTF16LE` answers text for. An odd length and an unpaired surrogate are false. Total on any value: a string, `null`, a sibling view kind, or a proxy is false rather than a throw. |
|
|
123
123
|
|
|
124
|
+
### Marks
|
|
125
|
+
|
|
126
|
+
The marks module, [`marks/constants.ts`](../src/core/marks/constants.ts), holds the byte order mark a
|
|
127
|
+
consumer writes or strips around a coding. `BOM` is the one public constant in this package, kept
|
|
128
|
+
in its own module so the lookup tables behind the codings stay module data. The
|
|
129
|
+
[BOM stance](#the-bom-stance) states how each charset face carries it.
|
|
130
|
+
|
|
131
|
+
| Name | Kind | Signature | Summary |
|
|
132
|
+
| ----- | ----- | ---------- | ------------------------------------------------------------- |
|
|
133
|
+
| `BOM` | const | `"\uFEFF"` | Holds the byte order mark, U+FEFF, as a one-character string. |
|
|
134
|
+
|
|
124
135
|
## The laws
|
|
125
136
|
|
|
126
137
|
Each face keeps the round-trip and canonical-form laws, and the suite drives both as sweeps rather
|
|
@@ -206,8 +217,9 @@ A byte order mark is data here, not a signal. `EF BB BF` decodes to U+FEFF on th
|
|
|
206
217
|
`FF FE` decodes to U+FEFF on the UTF-16LE face, in leading position exactly as anywhere else, and
|
|
207
218
|
each encodes back to those bytes. The round-trip law forces it: a decoder that dropped a leading BOM
|
|
208
219
|
would answer a text whose re-encoding is shorter than the bytes it was given, and no amount of
|
|
209
|
-
documentation makes that a round trip. A consumer that wants the mark removed
|
|
210
|
-
way a consumer wanting lenient Base64 normalizes
|
|
220
|
+
documentation makes that a round trip. A consumer that wants the mark removed compares the leading
|
|
221
|
+
character against `BOM` and removes it, the same way a consumer wanting lenient Base64 normalizes
|
|
222
|
+
first.
|
|
211
223
|
|
|
212
224
|
### Where this package parts from WHATWG
|
|
213
225
|
|
|
@@ -377,6 +389,7 @@ to UTF-16LE.
|
|
|
377
389
|
|
|
378
390
|
```ts
|
|
379
391
|
import {
|
|
392
|
+
BOM,
|
|
380
393
|
decodeLatin1,
|
|
381
394
|
decodeUTF8,
|
|
382
395
|
decodeUTF16LE,
|
|
@@ -392,6 +405,7 @@ encodeUTF8('hi') // Uint8Array [104, 105]
|
|
|
392
405
|
decodeUTF8(new Uint8Array([104, 105])) // 'hi'
|
|
393
406
|
encodeUTF8('\ud800') // undefined — a lone surrogate has no UTF-8 spelling
|
|
394
407
|
decodeUTF8(new Uint8Array([0xc0, 0x80])) // undefined — the overlong spelling of U+0000
|
|
408
|
+
encodeUTF8(BOM) // Uint8Array [239, 187, 191]
|
|
395
409
|
decodeUTF8(new Uint8Array([0xef, 0xbb, 0xbf])) // '\ufeff' — the BOM is data, not a signal
|
|
396
410
|
|
|
397
411
|
// ISO-8859-1 is the identity on a byte, so only its encode side can refuse.
|
|
@@ -461,7 +475,8 @@ measureUTF8('\ud800') // undefined — ill-formed text has no UTF-8 spelling
|
|
|
461
475
|
round-trip law walks a well-formed text population built from characters spanning every UTF-8
|
|
462
476
|
width threshold, the BOM, the Latin-1 ceiling, the Windows-1252 bands, and the code points on
|
|
463
477
|
either side of the surrogate range, and pins each width threshold at the byte length the
|
|
464
|
-
specification fixes.
|
|
478
|
+
specification fixes. A named case carries `BOM` through both faces, leading position included, and
|
|
479
|
+
pins it against `String.fromCodePoint(0xfeff)`. The canonical-form law walks the exhaustive two-byte space on every charset
|
|
465
480
|
face, re-encoding every admitted pair to itself, and reads the Windows-1252 defined mapping as a
|
|
466
481
|
bijection and the Latin-1 mapping as the identity bijection. Beside the sweeps sit the written-out
|
|
467
482
|
refusal rows — the overlongs, the encoded surrogates, the out-of-range and truncated sequences,
|
|
@@ -63,8 +63,6 @@ subclasses regardless of their `name`, and rejects transparent proxies and unbra
|
|
|
63
63
|
|
|
64
64
|
The style engine — text style as data, rendered by a swappable renderer (ANSI default; a browser `%c` renderer at the same seam).
|
|
65
65
|
|
|
66
|
-
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.
|
|
67
|
-
|
|
68
66
|
| Name | Kind | Signature | Summary |
|
|
69
67
|
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
70
68
|
| `Color` | type | `'black' \| 'red' \| 'green' \| 'yellow' \| 'blue' \| 'magenta' \| 'cyan' \| 'white' \| 'brightBlack' \| 'brightRed' \| 'brightGreen' \| 'brightYellow' \| 'brightBlue' \| 'brightMagenta' \| 'brightCyan' \| 'brightWhite' \| 'default'` | Names a terminal color — the 8 standard base colors, their 8 bright variants, and `default` (the target's own default ink, emitting no color code). |
|
|
@@ -88,8 +86,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
88
86
|
|
|
89
87
|
Structured logging — the immutable `LogRecord` + the `entry` event are the transport seam; `Sink` is the one output primitive.
|
|
90
88
|
|
|
91
|
-
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.
|
|
92
|
-
|
|
93
89
|
| Name | Kind | Signature | Summary |
|
|
94
90
|
| ------------------------ | --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
95
91
|
| `LogLevel` | type | `'debug' \| 'info' \| 'warn' \| 'error'` | Names the severity level of a `LogRecord` — one coherent, ascending scale, `debug` < `info` < `warn` < `error`, that a `LoggerInterface` gates by threshold. |
|
|
@@ -111,16 +107,14 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
111
107
|
|
|
112
108
|
Narrative reporting — pure width-aware layout renderers + a lean `Reporter` front-end, over the same styler and sink substrate.
|
|
113
109
|
|
|
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. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
115
|
-
|
|
116
110
|
| Name | Kind | Signature | Summary |
|
|
117
111
|
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
-
| `Alignment` | type | `'left' \| 'center' \| 'right'` | Names the horizontal text alignment within a fixed-width cell — `left` / `center` / `right`, the conventional set a `
|
|
112
|
+
| `Alignment` | type | `'left' \| 'center' \| 'right'` | Names the horizontal text alignment within a fixed-width cell — `left` / `center` / `right`, the conventional set a `TableColumn` (and the box / separator title) aligns by. |
|
|
119
113
|
| `BorderStyle` | type | `'single' \| 'double' \| 'round' \| 'heavy'` | Names a box-drawing border style — `single` / `double` / `round` / `heavy`, the standard Unicode line weights the renderers frame with, each selecting a full junction set in `BORDER_CHARS`. |
|
|
120
114
|
| `BorderChars` | interface | `{ horizontal, vertical, topLeft, topRight, bottomLeft, bottomRight, cross, teeDown, teeUp, teeRight, teeLeft }` | Represents one complete box-drawing junction set for a `BorderStyle` — the edges, the corners, and the `T` / cross junctions the box and table renderers need to frame content and rule a table. |
|
|
121
115
|
| `SeparatorOptions` | interface | `{ title?, width?, fill?, styler?, style? }` | Configures `renderSeparator` — a horizontal rule, optionally carrying a centered title. Every key is optional. |
|
|
122
116
|
| `BoxOptions` | interface | `{ content, title?, padding?, border?, width?, styler?, style? }` | Configures `renderBox` — content framed in box-drawing characters. A `Reporter` supplies its own chrome style only when the caller gives neither `styler` nor `style`. |
|
|
123
|
-
| `
|
|
117
|
+
| `TableColumn` | interface | `{ label, align? }` | Represents one column of a `TableOptions` — its header label and how its cells align. |
|
|
124
118
|
| `TableOptions` | interface | `{ columns, rows, border?, styler?, style? }` | Configures `renderTable` — a bordered grid of columns + rows with per-column alignment and width-aware sizing. A `Reporter` supplies its own chrome style only when the caller gives neither `styler` nor `style`. |
|
|
125
119
|
| `TreeNode` | interface | `{ label, children? }` | Represents one node of a `TreeOptions` tree — a label plus optional children, recursively. |
|
|
126
120
|
| `TreeOptions` | interface | `{ root, border?, styler?, style? }` | Configures `renderTree` — a nested `TreeNode` tree drawn with box-drawing connectors. A `Reporter` supplies its own chrome style only when the caller gives neither `styler` nor `style`. |
|
|
@@ -150,8 +144,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
150
144
|
|
|
151
145
|
Console interception — take control of `console.*` on the read side; a buffered, mirroring, forwarding interceptor with a lifecycle.
|
|
152
146
|
|
|
153
|
-
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.
|
|
154
|
-
|
|
155
147
|
| Name | Kind | Signature | Summary |
|
|
156
148
|
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
157
149
|
| `CaptureLevel` | type | `'log' \| 'info' \| 'warn' \| 'error' \| 'debug'` | Identifies one intercepted `console` method — `log` / `info` / `warn` / `error` / `debug`, the names a `CaptureInterface` patches and reports under. |
|
|
@@ -170,8 +162,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
170
162
|
|
|
171
163
|
The one error type the console layer throws — an internal invariant or unreachable-guard violation.
|
|
172
164
|
|
|
173
|
-
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.
|
|
174
|
-
|
|
175
165
|
| Name | Kind | Signature | Summary |
|
|
176
166
|
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
177
167
|
| `ConsoleErrorCode` | type | `'INVARIANT'` | Names the machine-readable error code a `ConsoleError` carries — `INVARIANT`, the only code the package throws. |
|
|
@@ -182,8 +172,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
182
172
|
|
|
183
173
|
Live activity animations — pure frame producers over the same styler and sink substrate; the line overwrite is the sink's job.
|
|
184
174
|
|
|
185
|
-
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 class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
186
|
-
|
|
187
175
|
| Name | Kind | Signature | Summary |
|
|
188
176
|
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
189
177
|
| `BarOptions` | interface | `{ current, total, width?, fill?, empty?, styler?, style? }` | Configures the pure `renderBar` renderer — a determinate progress bar string (`█████░░░░░ 50% (5/10)`), width-aware and styler-optional. |
|
|
@@ -201,8 +189,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
201
189
|
|
|
202
190
|
The SGR code data the ANSI renderer maps through, and the styler's color / attribute axes (`src/core`). All `Object.freeze`d data; the SGR numbers are the fixed ECMA-48 spec.
|
|
203
191
|
|
|
204
|
-
A `Shape` cell holds the constant's declared type.
|
|
205
|
-
|
|
206
192
|
| Name | Kind | Signature | Summary |
|
|
207
193
|
| ------------------ | ----- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
208
194
|
| `FOREGROUND_CODES` | const | `Readonly<Record<Exclude<Color, 'default'>, number>>` | Maps each `Color` to its SGR foreground parameter — the 8 base colors at 30–37 and their bright variants at 90–97. `default` is intentionally absent (it emits no code). |
|
|
@@ -224,8 +210,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
224
210
|
|
|
225
211
|
The level order + label colors, the box-drawing junction sets, status icons / colors, and default widths / glyphs (`src/core`). All `Object.freeze`d data; the box-drawing + braille glyphs are fixed Unicode. There is no separate tree-connector table: a tree derives its branch / corner / guide runs from the same `BORDER_CHARS` set a box or a table draws with, so a box, a table, and a tree all answer to one `border`.
|
|
226
212
|
|
|
227
|
-
A `Shape` cell holds the constant's declared type.
|
|
228
|
-
|
|
229
213
|
| Name | Kind | Signature | Summary |
|
|
230
214
|
| --------------------- | ----- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
231
215
|
| `LEVEL_SEVERITY` | const | `Readonly<Record<LogLevel, number>>` | Maps each `LogLevel` to its numeric severity — the ascending order the level gate compares through (`debug` 0 < `info` 1 < `warn` 2 < `error` 3). A record is kept when its level's severity is at or above the logger's threshold. The source of truth for level ordering. |
|
|
@@ -240,7 +224,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
240
224
|
| `DEFAULT_WIDTH` | const | `80` | Sets the default visible column width for the width-aware renderers — the separator rule and a `renderBox` with no explicit `width`, and the reporter's `section` rule. A sane terminal default (80 columns); a caller overrides it per-call or through `ReporterOptions.width`. |
|
|
241
225
|
| `DEFAULT_PADDING` | const | `1` | Sets the default horizontal padding inside a box's edges (`renderBox`) — one cell. |
|
|
242
226
|
| `DEFAULT_BORDER` | const | `BorderStyle` | Sets the default `BorderStyle` the box / table renderers frame with when none is given — `single`. |
|
|
243
|
-
| `DEFAULT_ALIGN` | const | `Alignment` | Sets the default cell `Alignment` a `
|
|
227
|
+
| `DEFAULT_ALIGN` | const | `Alignment` | Sets the default cell `Alignment` a `TableColumn` uses when none is given — `left`. |
|
|
244
228
|
| `SEPARATOR_FILL` | const | `"\u2500"` | Holds the default fill character `renderSeparator` draws its rule with — `─`. |
|
|
245
229
|
| `SEPARATOR_TITLE_GAP` | const | `" "` | Holds the single padding cell on each side of a separator's embedded title (`title`) — keeps the title from butting against the rule. One space. |
|
|
246
230
|
| `SECOND_MS` | const | `1000` | Sets the millisecond threshold at or above which `formatDuration` (and so `Reporter.timing`) switches from a `…ms` rendering to a `…s` (seconds, 2 d.p.) rendering — `1000`, exactly one second. |
|
|
@@ -249,8 +233,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
249
233
|
|
|
250
234
|
The intercepted-method set, the bounded-buffer cap, the level projection, and the spinner frames / bar glyphs / track width (`src/core`). All `Object.freeze`d data.
|
|
251
235
|
|
|
252
|
-
A `Shape` cell holds the constant's declared type.
|
|
253
|
-
|
|
254
236
|
| Name | Kind | Signature | Summary |
|
|
255
237
|
| -------------------------- | ----- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
256
238
|
| `CAPTURE_LEVELS` | const | `readonly CaptureLevel[]` | Lists every `CaptureLevel`, frozen — the `console.*` methods a `CaptureInterface` intercepts by default (and the source of truth for the capture-level axis; drives exhaustive tests). The universal console methods: `log`, `info`, `warn`, `error`, `debug`. |
|
|
@@ -266,8 +248,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
266
248
|
|
|
267
249
|
The browser `%c` console sink — translates the core's ANSI output into a `console.log('%c…', css)` call at the output boundary ([`src/browser`](../src/browser), surfaced through `@src/browser`). The core owns the `SinkInterface` contract + the style data model; this module owns only the browser-side translation.
|
|
268
250
|
|
|
269
|
-
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.
|
|
270
|
-
|
|
271
251
|
| Name | Kind | Signature | Summary |
|
|
272
252
|
| -------------------- | --------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
273
253
|
| `BrowserPalette` | interface | `{ color?, attribute? }` | Holds partial browser CSS overrides for the core color and attribute axes — a named `color` or `attribute` entry replaces only that entry, and every omission keeps its default. |
|
|
@@ -283,8 +263,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
283
263
|
|
|
284
264
|
The SGR → CSS translation data the browser sink maps ANSI runs through (`src/browser`). The number↔name mapping is derived from core's code maps, never re-hardcoded; the browser module reads core's `RESET_CODE` directly (no local re-export).
|
|
285
265
|
|
|
286
|
-
A `Shape` cell holds the constant's declared type.
|
|
287
|
-
|
|
288
266
|
| Name | Kind | Signature | Summary |
|
|
289
267
|
| --------------- | ----- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
290
268
|
| `COLOR_HEX` | const | `Readonly<Record<Exclude<Color, 'default'>, string>>` | Maps each named `Color` to its hex value — the 16 standard terminal colors a browser DevTools console renders the same `Color` names as. The source of truth for the browser color axis: the ANSI renderer maps a `Color` name to an SGR number, and this maps the same name to the CSS color the `%c` sink paints with, so a browser shows the same 16 colors a terminal does. |
|
|
@@ -296,8 +274,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
296
274
|
|
|
297
275
|
The server output backend — a TTY-aware `Sink` over the real `process` streams with a raw process-stream capture ([`src/server`](../src/server), surfaced through `@src/server`). The core owns the `SinkInterface` / `LogLevel` contracts + the `console` `Capture`; this module owns the server-only stream backend. Color detection lives here and only here: `inferStyled` reads the environment, `createServerSink` fixes each target's `styled` fact at construction, and nothing in core or the browser probes for color (the color-detection contract).
|
|
298
276
|
|
|
299
|
-
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 `\|`. An extended interface's name comes before `plus`, with the members it adds after. 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.
|
|
300
|
-
|
|
301
277
|
| Name | Kind | Signature | Summary |
|
|
302
278
|
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
303
279
|
| `StreamTargetInterface` | interface | `{ write(), isTTY?, columns? }` | Declares the minimal writable-stream shape the server sink and process capture address — exactly the slice of a Node `tty.WriteStream` / `process.stdout` they touch and no more. |
|
|
@@ -322,8 +298,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
322
298
|
|
|
323
299
|
The default stream set, buffer cap, no-TTY column fallback, and the stream → log-level projection (`src/server`). All `Object.freeze`d data.
|
|
324
300
|
|
|
325
|
-
A `Shape` cell holds the constant's declared type.
|
|
326
|
-
|
|
327
301
|
| Name | Kind | Signature | Summary |
|
|
328
302
|
| ---------------------- | ----- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
329
303
|
| `STREAM_LEVELS` | const | `readonly StreamLevel[]` | Lists the process streams a `ProcessCaptureInterface` can intercept, in `stdout`-then-`stderr` order — the `StreamLevel` universe and the default configured set. |
|
|
@@ -335,7 +309,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
335
309
|
|
|
336
310
|
The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. Each type's `readonly` data members, for example `emitter` / `active` / `message` / `level` / `name` / `current` / `total` / `succeeded` / `columns`, stay in the preceding Surface rows and are not repeated here. Each implementing class implements its interface exactly, so this doubles as the per-instance method surface.
|
|
337
311
|
|
|
338
|
-
**Data-only / callable surfaces (no `## Methods` subsection).** `ServerSinkInterface` adds `styled` and `columns` data members to `SinkInterface` (its `write` is the inherited contract in the following `SinkInterface` table). Every `*Options` / `*EventMap` / `LogRecord` / `Style` / `Theme` / `ThemeStatus` / `BorderChars` / `
|
|
312
|
+
**Data-only / callable surfaces (no `## Methods` subsection).** `ServerSinkInterface` adds `styled` and `columns` data members to `SinkInterface` (its `write` is the inherited contract in the following `SinkInterface` table). Every `*Options` / `*EventMap` / `LogRecord` / `Style` / `Theme` / `ThemeStatus` / `BorderChars` / `TableColumn` / `TreeNode` / `StepPosition` / `ProgressReport` / `WriterSet` / `CapturedMessage` / `CapturedChunk` / `CaptureResult` / `BrowserPalette` / `ConsoleOutput` / `StyleAccumulator` / `StreamTargetInterface` row is a data / options shape with no behavioral methods.
|
|
339
313
|
|
|
340
314
|
#### `RendererInterface`
|
|
341
315
|
|