@flyingrobots/bijou-node 4.2.0 → 4.4.1

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 (5) hide show
  1. package/README.md +21 -71
  2. package/dist/io.d.ts.map +1 -1
  3. package/dist/io.js +19 -0
  4. package/dist/io.js.map +1 -1
  5. package/package.json +3 -3
package/README.md CHANGED
@@ -2,13 +2,13 @@
2
2
 
3
3
  Node.js adapters and runtime utilities for Bijou.
4
4
 
5
- This package bridges the pure `@flyingrobots/bijou` core and the `@flyingrobots/bijou-tui` runtime to the Node.js environment. It owns runtime detection, terminal I/O, Chalk-backed styling, worker-thread helpers, and the native surface recorder.
5
+ `@flyingrobots/bijou-node` bridges the pure core and the TUI runtime to the Node.js environment. It owns platform detection, terminal I/O, Chalk-backed styling, and worker-thread helpers.
6
6
 
7
- ## Package Role
7
+ ## Role
8
8
 
9
- - **Worker runtime support** — `runInWorker()` and `startWorkerApp()` let TEA apps move heavy update work off the main thread while keeping input and rendering responsive.
10
- - **Native surface recorder** — scripted captures can be recorded directly from captured `Surface[]` frames with `recordDemoGif()`.
11
- - **Node boundary stays explicit** — runtime facts, I/O, and styling remain behind the port interfaces instead of leaking `process`, `readline`, or Chalk into the pure packages.
9
+ - **Port Implementation**: Maps Node.js APIs to the Bijou port interfaces.
10
+ - **Worker Runtime**: Offloads heavy TEA logic to worker threads while maintaining main-thread responsiveness.
11
+ - **Bootstrapping**: One-line context initialization with `initDefaultContext()`.
12
12
 
13
13
  ## Install
14
14
 
@@ -16,86 +16,36 @@ This package bridges the pure `@flyingrobots/bijou` core and the `@flyingrobots/
16
16
  npm install @flyingrobots/bijou @flyingrobots/bijou-node
17
17
  ```
18
18
 
19
- ## Usage
19
+ ## Quick Start
20
20
 
21
21
  ```typescript
22
22
  import { initDefaultContext } from '@flyingrobots/bijou-node';
23
- import { box, headerBox } from '@flyingrobots/bijou';
23
+ import { headerBox } from '@flyingrobots/bijou';
24
24
 
25
- // Wire up Node.js adapters and set the default context.
26
- // Auto-detects TTY, CI, NO_COLOR, and TERM=dumb.
27
25
  initDefaultContext();
28
26
 
29
27
  console.log(headerBox('My CLI', { detail: 'v1.0.0' }));
30
28
  ```
31
29
 
32
- ## Features Breakdown
30
+ ## Port Mapping
33
31
 
34
- - **Port implementation for Node.js**: complete `RuntimePort`, `IOPort`, and `StylePort` adapters for `@flyingrobots/bijou`.
35
- - **Runtime detection**: environment variables, TTY state, and terminal dimensions sourced from `process`.
36
- - **Interactive terminal I/O**: stdin/stdout integration with readline and resize-event support.
37
- - **Styling backend**: Chalk-powered color/style methods wired into bijou styling APIs.
38
- - **One-line bootstrap**: `initDefaultContext()` creates a production-ready context and registers it as default on first call.
39
- - **Worker helpers**: `runInWorker()` and `startWorkerApp()` for moving app logic into a worker thread.
40
- - **Native recorder**: `recordDemoGif()` and related helpers for scripted surface capture.
41
-
42
- ## What It Provides
43
-
44
- `bijou-node` implements the three ports that `@flyingrobots/bijou` requires:
45
-
46
- | Port | Implementation | What it does |
32
+ | Port | Node.js Implementation | Responsibility |
47
33
  | :--- | :--- | :--- |
48
- | `RuntimePort` | `nodeRuntime()` | `process.env`, TTY detection, terminal dimensions |
49
- | `IOPort` | `nodeIO()` | `process.stdout/stdin`, readline, resize events |
50
- | `StylePort` | `chalkStyle()` | RGB/hex color via chalk, respects `NO_COLOR` |
51
-
52
- ### API
34
+ | **`RuntimePort`** | `nodeRuntime()` | `process.env`, TTY detection, dimensions |
35
+ | **`IOPort`** | `nodeIO()` | `stdout`/`stdin`, readline, resize events |
36
+ | **`StylePort`** | `chalkStyle()` | RGB/hex styling, `NO_COLOR` support |
53
37
 
54
- ```typescript
55
- // Individual port factories
56
- import { nodeRuntime, nodeIO, chalkStyle } from '@flyingrobots/bijou-node';
57
-
58
- // All-in-one context (most common)
59
- import { createNodeContext, initDefaultContext } from '@flyingrobots/bijou-node';
38
+ ## API
60
39
 
61
- // createNodeContext() — returns a BijouContext without setting it as default
62
- const ctx = createNodeContext();
40
+ - **`createNodeContext()`**: Returns a wired `BijouContext` without setting it as the global default.
41
+ - **`initDefaultContext()`**: Registers the first context as the global default for all Bijou components.
42
+ - **`runInWorker()`**: Starts a TEA app inside a worker thread.
43
+ - **`recordDemoGif()`**: Captures surface frames and rasterizes them to GIF for documentation.
63
44
 
64
- // initDefaultContext() — first call registers as global default; later calls return fresh unregistered contexts
65
- initDefaultContext();
66
- ```
45
+ ## Documentation
67
46
 
68
- If you need to replace the default context later in-process, call `setDefaultContext(createNodeContext())` from `@flyingrobots/bijou`.
69
-
70
- See [ARCHITECTURE.md](./ARCHITECTURE.md) for how the adapter maps to Node.js APIs, and [GUIDE.md](./GUIDE.md) for usage patterns.
71
- For upgrading existing apps, see [`../../docs/MIGRATING_TO_V4.md`](../../docs/MIGRATING_TO_V4.md).
72
-
73
- ## Related Packages
74
-
75
- - [`@flyingrobots/bijou`](https://www.npmjs.com/package/@flyingrobots/bijou) — Zero-dependency core with all components and theme engine
76
- - [`@flyingrobots/bijou-tui`](https://www.npmjs.com/package/@flyingrobots/bijou-tui) — TEA runtime for interactive terminal apps
77
-
78
- ## License
79
-
80
- Apache-2.0
47
+ - **[GUIDE.md](./GUIDE.md)**: Productive-fast path for Node setups.
48
+ - **[ADVANCED_GUIDE.md](./ADVANCED_GUIDE.md)**: Worker thread and recorder internals.
81
49
 
82
50
  ---
83
-
84
- <p align="center">
85
- Built with 💎 by <a href="https://github.com/flyingrobots">FLYING ROBOTS</a>
86
- </p>
87
-
88
- ```rust
89
- .-:::::'::: .-:. ::-.::::::. :::. .,-:::::/
90
- ;;;'''' ;;; ';;. ;;;;';;;`;;;;, `;;;,;;-'````'
91
- [[[,,== [[[ '[[,[[[' [[[ [[[[[. '[[[[[ [[[[[[/
92
- `$$$"`` $$' c$$" $$$ $$$ "Y$c$$"$$c. "$$
93
- 888 o88oo,.__ ,8P"` 888 888 Y88 `Y8bo,,,o88o
94
- "MM, """"YUMMMmM" MMM MMM YM `'YMUP"YMM
95
- :::::::.. ... :::::::. ... :::::::::::: .::::::.
96
- ;;;;``;;;; .;;;;;;;. ;;;'';;' .;;;;;;;.;;;;;;;;'''';;;` `
97
- [[[,/[[[' ,[[ \[[, [[[__[[\.,[[ \[[, [[ '[==/[[[[,
98
- $$$$$$c $$$, $$$ $$""""Y$$$$$, $$$ $$ ''' $
99
- 888b "88bo,"888,_ _,88P_88o,,od8P"888,_ _,88P 88, 88b dP
100
- MMMM "W" "YMMMMMP" ""YUMMMP" "YMMMMMP" MMM "YMmMY"
101
- ```
51
+ Built with 💎 by [FLYING ROBOTS](https://github.com/flyingrobots)
package/dist/io.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../src/io.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,SAAS,EAAE,KAAK,MAAM,EAAyC,MAAM,qBAAqB,CAAC;AAEvH,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAkJ1D"}
1
+ {"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../src/io.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,SAAS,EAAE,KAAK,MAAM,EAAyC,MAAM,qBAAqB,CAAC;AAEvH,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAoK1D"}
package/dist/io.js CHANGED
@@ -24,6 +24,25 @@ export function nodeIO(options = {}) {
24
24
  write(data) {
25
25
  process.stdout.write(data);
26
26
  },
27
+ /**
28
+ * Write raw bytes directly to `process.stdout`. Allows the
29
+ * renderer to bypass string encoding on the hot path. Respects
30
+ * `len` so pooled buffers with extra capacity write only the
31
+ * valid prefix. See WritePort.writeBytes docs for the contract.
32
+ *
33
+ * @param buf - The byte buffer (may be a pooled, reused buffer).
34
+ * @param len - Number of valid bytes in `buf` to write.
35
+ */
36
+ writeBytes(buf, len) {
37
+ if (len <= 0)
38
+ return;
39
+ if (len === buf.length) {
40
+ process.stdout.write(buf);
41
+ }
42
+ else {
43
+ process.stdout.write(buf.subarray(0, len));
44
+ }
45
+ },
27
46
  /**
28
47
  * Write a string directly to `process.stderr`.
29
48
  *
package/dist/io.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"io.js","sourceRoot":"","sources":["../src/io.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"io.js","sourceRoot":"","sources":["../src/io.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@flyingrobots/bijou-node",
3
- "version": "4.2.0",
3
+ "version": "4.4.1",
4
4
  "description": "Node.js adapter for bijou — chalk styling, readline I/O, process runtime.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -24,13 +24,13 @@
24
24
  "lint": "tsc --noEmit"
25
25
  },
26
26
  "dependencies": {
27
- "@flyingrobots/bijou-tui": "4.2.0",
27
+ "@flyingrobots/bijou-tui": "4.4.1",
28
28
  "chalk": "^5.6.2",
29
29
  "gifenc": "^1.0.3",
30
30
  "oled-font-5x7": "^1.0.3"
31
31
  },
32
32
  "peerDependencies": {
33
- "@flyingrobots/bijou": "4.2.0"
33
+ "@flyingrobots/bijou": "4.4.1"
34
34
  },
35
35
  "devDependencies": {
36
36
  "@types/node": "^22.0.0",