xonecas.io
70160
Ce

cel-tui / commit 25d7de3

feat(core): add terminal title helper

xonecas2026-04-11 25d7de39bb50c673613b54781da2d6b92ee1ce09 parent cf0d1e0

3 files changed

packages/core/src/cel.test.ts+42−0
@@ -13,6 +13,11 @@ const ESCAPE = kittyEncode("escape");
1313 const SHIFT_TAB = kittyEncode("shift+tab");
1414 const CTRL_S = kittyEncode("ctrl+s");
1515 const LEGACY_CTRL_R = "\x12";
16+const TITLE_SEQUENCE_RE = /\x1b\][02];([^\x07\x1b]*)(?:\x07|\x1b\\)/g;
17+
18+function extractTitlePayloads(output: string): string[] {
19+ return Array.from(output.matchAll(TITLE_SEQUENCE_RE), (match) => match[1]!);
20+}
1621
1722 describe("cel end-to-end", () => {
1823 let term: MockTerminal;
@@ -138,6 +143,43 @@ describe("cel end-to-end", () => {
138143 expect(term.output).toContain("\x1b[?2026l");
139144 });
140145
146+ describe("terminal title", () => {
147+ test("setTitle writes a terminal title OSC sequence with the requested text", () => {
148+ const term = setup();
149+
150+ cel.setTitle("cel-tui demo");
151+
152+ expect(extractTitlePayloads(term.output)).toEqual(["cel-tui demo"]);
153+ });
154+
155+ test("setTitle strips control characters from the title text", () => {
156+ const term = setup();
157+
158+ cel.setTitle("ab\x00c\nd\te\x1bf");
159+
160+ expect(extractTitlePayloads(term.output)).toEqual(["abcdef"]);
161+ });
162+
163+ test("setTitle can be called multiple times and writes each title update", () => {
164+ const term = setup();
165+
166+ cel.setTitle("first");
167+ cel.setTitle("second");
168+
169+ expect(extractTitlePayloads(term.output)).toEqual(["first", "second"]);
170+ });
171+
172+ test("stop does not emit a title restore sequence", () => {
173+ const term = setup();
174+ cel.setTitle("session");
175+ term.clearOutput();
176+
177+ cel.stop();
178+
179+ expect(extractTitlePayloads(term.output)).toEqual([]);
180+ });
181+ });
182+
141183 describe("input handling", () => {
142184 test("onClick fires on mouse click", async () => {
143185 const term = setup(20, 5);
packages/core/src/cel.ts+16−0
@@ -216,6 +216,10 @@ let batchScrollOffsets: Map<object, number> | null = null;
216216 // keys in the same chunk must see the updated value/cursor immediately.
217217 let batchTextInputEdits: Map<TextInputProps, EditState> | null = null;
218218
219+function sanitizeTerminalTitle(title: string): string {
220+ return title.replace(/[\x00-\x1f\x7f-\x9f]/g, "");
221+}
222+
219223 function handleInput(data: string): void {
220224 batchTextInputEdits = new Map();
221225
@@ -1043,6 +1047,18 @@ export const cel = {
10431047 process.nextTick(doRender);
10441048 },
10451049
1050+ /**
1051+ * Set the terminal window or tab title.
1052+ *
1053+ * This is an imperative side effect, not part of the render tree.
1054+ * Control characters are stripped from the title before writing the
1055+ * terminal sequence. Best effort only — some hosts may ignore it.
1056+ */
1057+ setTitle(title: string): void {
1058+ if (!terminal) return;
1059+ terminal.write(`\x1b]2;${sanitizeTerminalTitle(title)}\x1b\\`);
1060+ },
1061+
10461062 /**
10471063 * Stop the framework and restore terminal state.
10481064 *
spec.md+17−0
@@ -13,6 +13,7 @@ cel-tui is a TypeScript TUI framework built around a declarative functional API,
1313 ```ts
1414 cel.viewport(render: () => Node | Node[])
1515 cel.render()
16+cel.setTitle(title: string)
1617 ```
1718
1819 `cel.viewport` sets the render function that returns the UI tree. Accepts a single layer or an array of layers. Each layer is a container with full viewport dimensions, laid out independently. When multiple layers are provided, they are composited bottom-to-top (array index = z-order). Setting the viewport triggers the first render.
@@ -21,6 +22,22 @@ cel.render()
2122
2223 State is fully external to the framework. Use any state management approach — plain variables, classes, libraries. The framework just calls the render function and renders the returned tree.
2324
25+### Terminal Title
26+
27+```ts
28+cel.setTitle(title: string)
29+```
30+
31+Sets the terminal window or tab title as an imperative side effect. This is **global terminal state**, not part of the declarative render tree, so it should be called directly when the title needs to change.
32+
33+The framework emits a best-effort terminal title request using an OSC title sequence. Support varies by terminal emulator, multiplexer, and remote environment — some hosts may ignore it, reinterpret it, or map it to a pane/window title instead.
34+
35+**Semantics:**
36+
37+- Later calls replace the previous title set by the app.
38+- `title` is treated as plain text. Control characters are stripped before writing the sequence.
39+- The framework does **not** automatically restore the previous terminal title on `cel.stop()`.
40+
2441 ### Measurement Helpers
2542
2643 ```ts