xonecas.io
70160
Ce

cel-tui / commit ed5430e

chore: bump version to 0.3.0, docs alignment audit

Breaking: onSubmit/submitKey replaced with onKeyPress on TextInput (done in
98d11da, this release captures the version bump).

Docs fixes:
- Add pre-release documentation audit procedure to AGENTS.md
- Fix false 256-color capability claims (actual: ANSI 16 + true color hex)
- Fix stale skill version, imprecise compatibility line
- Fix spec TextInput placeholder type (Text → TextNode)
- Fix AGENTS.md hitTest signature (missing scroll offset param)
- Add ThemeValue JSDoc warning for number range 0–15
- Fix pre-publish checklist numbering

xonecas2026-04-05 ed5430e173040ddb864e49b3ee95a43023f43df9 parent 98d11da

10 files changed

AGENTS.md+47−10
@@ -207,7 +207,7 @@ chore: scaffold monorepo with types, core, components packages
207207 - `layout.ts` — Flexbox engine. `layout(root, width, height)` → `LayoutNode` tree with absolute screen rects.
208208 - `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets (clamped to max — apps can pass `Infinity` to mean "scroll to end"), scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state (with cursor screen position export for native cursor), TextInput background fill, container bgColor fill, style inheritance threading, focusStyle resolution.
209209 - `emitter.ts` — `emitBuffer()` for full renders, `emitDiff()` for differential. Both accept an optional `Theme` for color resolution and wrap in CSI 2026 synchronized output. Exports `defaultTheme` (ANSI 16 mapping).
210-- `hit-test.ts` — `hitTest(root, x, y)` → path from root to deepest node. `findClickHandler`, `findScrollTarget`, `collectKeyPressHandlers`, `collectFocusable` walk paths.
210+- `hit-test.ts` — `hitTest(root, x, y, getScrollOffset?)` → path from root to deepest node at `(x,y)`, accounting for scroll offsets. `findClickHandler`, `findScrollTarget`, `collectKeyPressHandlers`, `collectFocusable` walk paths.
211211 - `keys.ts` — Kitty keyboard protocol parser. `parseKey(data)` handles CSI u sequences (special keys, modifier combos), CSI letter sequences (arrows, Home/End with modifiers), CSI tilde sequences (Delete, PageUp/Down, F-keys with modifiers), and raw printable bytes. Maps `" "` → `"space"`, `"+"` → `"plus"` as named keys. `isEditingKey()` identifies keys consumed by TextInput. `normalizeKey()` reorders modifiers to canonical `ctrl+alt+shift+<key>` order.
212212 - `text-edit.ts` — Pure text editing functions (`insertChar`, `deleteBackward`, `deleteForward`, `moveCursor`). Operates on `EditState` (value + cursor position). Uses `Intl.Segmenter` with grapheme granularity for cursor movement and deletion (handles emoji, ZWJ sequences, combining marks). Used by `cel.ts` to handle TextInput key events.
213213 - `width.ts` — `visibleWidth(str)` measures terminal column width. Fast ASCII path, grapheme segmentation, East Asian width, ANSI stripping, LRU cache.
@@ -267,16 +267,53 @@ cd ../components && bun publish --access public
267267
268268 If 2FA is enabled, add `--otp <code>` to each command.
269269
270+### Pre-release documentation audit
271+
272+Before every release, run a full alignment audit across all documentation surfaces. The goal is to catch stale versions, false capability claims, signature mismatches, and terminology drift between the spec, code, JSDocs, agent docs, and skill files.
273+
274+**What to read** (in this order — each layer should agree with the ones before it):
275+
276+1. `packages/types/src/index.ts` — the canonical type definitions and their JSDocs
277+2. `packages/core/src/*.ts` — implementation (public function signatures, behavior, exports)
278+3. `packages/core/src/index.ts` — what's actually exported to consumers
279+4. `packages/components/src/*.ts` — component implementations and JSDocs
280+5. `spec.md` — design spec (API tables, prop types, behavior descriptions)
281+6. `AGENTS.md` — architecture notes, module descriptions, conventions
282+7. `README.md` — user-facing overview and feature claims
283+8. `docs/skill/cel-tui/SKILL.md` — agent skill (version, compatibility, patterns, gotchas)
284+9. `docs/skill/cel-tui/references/*.md` — API reference and composing guide
285+10. `TODO.md` — verify listed bugs/violations are still present or mark resolved
286+11. `package.json` files — versions, descriptions, dependency declarations
287+
288+**What to check at each layer:**
289+
290+- **Versions** — skill metadata, package.json files, and any version references all match
291+- **Capability claims** — if docs say "supports X", verify the code actually implements X (e.g., color spaces, protocol levels, sizing strategies)
292+- **Function signatures** — parameter names, types, optional params, return types match between code and docs
293+- **Prop tables** — every prop in the type definition appears in the spec table with the correct type and description
294+- **Terminology** — consistent naming across all surfaces (e.g., `TextNode` vs `Text`, "uncontrolled" vs "framework-managed")
295+- **Behavior descriptions** — bubbling semantics, controlled/uncontrolled modes, default values all match the implementation
296+- **Exports** — what `index.ts` exports matches what docs say is available
297+- **Compatibility/requirements** — terminal requirements, runtime requirements are stated accurately
298+- **TODO.md currency** — bugs listed as open are still present in code; any that were fixed should be removed
299+
300+**After making fixes**, always verify nothing broke:
301+
302+```bash
303+bun run typecheck && bun test && bun run check && bun run format
304+```
305+
270306 ### Pre-publish checklist
271307
272-1. All tests pass: `bun test`
273-2. Types clean: `bun run typecheck`
274-3. Lint/format clean: `bun run check && bun run format`
275-4. Version bumped in all three `package.json` files
276-5. Lockfile regenerated: `rm bun.lock && bun install`
277-6. **Pre-publish check passes: `bun run prepublish-check`** (verifies lockfile versions match package.json)
278-7. Changes committed and pushed
279-8. After publishing, **verify on npm**: `npm view @cel-tui/core@<version> dependencies --json`
308+1. **Documentation audit passes** (see above)
309+2. All tests pass: `bun test`
310+3. Types clean: `bun run typecheck`
311+4. Lint/format clean: `bun run check && bun run format`
312+5. Version bumped in all three `package.json` files
313+6. Lockfile regenerated: `rm bun.lock && bun install`
314+7. **Pre-publish check passes: `bun run prepublish-check`** (verifies lockfile versions match package.json)
315+8. Changes committed and pushed
316+9. After publishing, **verify on npm**: `npm view @cel-tui/core@<version> dependencies --json`
280317
281318 ### How it works
282319
@@ -298,4 +335,4 @@ More generally: before running any command that could destroy uncommitted work (
298335 - Primitives are functions that return typed Node objects (not classes)
299336 - Components in `packages/components/` are plain functions using core primitives
300337 - Key format: all lowercase, modifiers joined by `+` (e.g., `"ctrl+shift+s"`)
301-- Colors: 16 numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default via `defaultTheme`. Custom themes can remap slots to 256-color or true color. Omit `fgColor`/`bgColor` for terminal defaults. Always pair `bgColor` with `fgColor` for contrast.
338+- Colors: 16 numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default via `defaultTheme`. Custom themes can remap slots to different ANSI indices or 24-bit true color. Omit `fgColor`/`bgColor` for terminal defaults. Always pair `bgColor` with `fgColor` for contrast.
README.md+1−1
@@ -64,7 +64,7 @@ cel.viewport(() =>
6464 - **Layers** — return an array for multi-layer compositing (modals, overlays).
6565 - **Uncontrolled by default** — focus and scroll just work. Opt into controlled mode when needed.
6666 - **Style inheritance** — containers propagate styles to descendants. `bgColor` fills the rect.
67-- **16-color palette** — numbered slots (`"color00"`–`"color15"`) mapped to ANSI 16 by default. Custom themes can remap to 256-color or true color.
67+- **16-color palette** — numbered slots (`"color00"`–`"color15"`) mapped to ANSI 16 by default. Custom themes can remap to different ANSI indices or 24-bit true color.
6868 - **Cell buffer rendering** — styled cells, differential updates, synchronized output.
6969 - **Kitty keyboard protocol** — unambiguous key input with full modifier support. Requires a [compatible terminal](https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement) (Kitty, WezTerm, Ghostty, foot, Alacritty, Windows Terminal).
7070
bun.lock+3−3
@@ -17,7 +17,7 @@
1717 },
1818 "packages/components": {
1919 "name": "@cel-tui/components",
20- "version": "0.2.1",
20+ "version": "0.3.0",
2121 "dependencies": {
2222 "@cel-tui/core": "workspace:*",
2323 "@cel-tui/types": "workspace:*",
@@ -29,7 +29,7 @@
2929 },
3030 "packages/core": {
3131 "name": "@cel-tui/core",
32- "version": "0.2.1",
32+ "version": "0.3.0",
3333 "dependencies": {
3434 "@cel-tui/types": "workspace:*",
3535 "get-east-asian-width": "^1.5.0",
@@ -40,7 +40,7 @@
4040 },
4141 "packages/types": {
4242 "name": "@cel-tui/types",
43- "version": "0.2.1",
43+ "version": "0.3.0",
4444 "peerDependencies": {
4545 "typescript": ">=5.0.0",
4646 },
docs/skill/cel-tui/SKILL.md+3−3
@@ -2,10 +2,10 @@
22 name: cel-tui
33 description: Build terminal user interfaces with cel-tui, a TypeScript TUI framework. Use when the user wants to create a TUI app, build a terminal UI, render text in the terminal, create a CLI with interactive elements, build a chat interface, text editor, or any interactive terminal application. Triggers include "build a TUI", "terminal UI", "interactive CLI", "text-based interface", "render to terminal", or any task requiring a programmatic terminal user interface.
44 license: MIT
5-compatibility: Requires Bun runtime and a terminal with SGR mouse mode support.
5+compatibility: Requires Bun runtime and a terminal supporting the Kitty keyboard protocol and SGR mouse mode.
66 metadata:
77 author: sacenox
8- version: "0.2.0"
8+ version: "0.3.0"
99 ---
1010
1111 # Building TUIs with cel-tui
@@ -75,7 +75,7 @@ The steps: `cel.init(terminal)` → `cel.viewport(() => tree)` → mutate state
7575 | `Text(content, props?)` | Leaf | Styled text, no children |
7676 | `TextInput(props)` | Container (no children) | Multi-line editable text |
7777
78-Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`, `flexWrap`), scroll (`overflow: "scroll"`, `scrollbar`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default. Custom themes can remap slots to true color via `cel.init(terminal, { theme })`.
78+Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`, `flexWrap`), scroll (`overflow: "scroll"`, `scrollbar`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default. Custom themes can remap slots to different ANSI indices or 24-bit true color via `cel …
7979
8080 Read [references/api.md](references/api.md) for the full props listing, sizing strategies, text props, and component reference.
8181
docs/skill/cel-tui/references/api.md+2−2
@@ -77,7 +77,7 @@ Text("content", {
7777 });
7878 ```
7979
80-Colors: 16 numbered palette slots — `"color00"` through `"color15"`. Mapped to ANSI 16 by default; custom themes can remap to 256-color or true color. Omit a color prop for the terminal default.
80+Colors: 16 numbered palette slots — `"color00"` through `"color15"`. Mapped to ANSI 16 by default; custom themes can remap to different ANSI indices or 24-bit true color. Omit a color prop for the terminal default.
8181
8282 ## TextInput Props
8383
@@ -243,7 +243,7 @@ Streaming works naturally — append chunks and call `cel.render()`. Unclosed bl
243243
244244 ## Theme
245245
246-The default theme maps 16 color slots to ANSI palette indices. Custom themes remap to 256-color or 24-bit hex:
246+The default theme maps 16 color slots to ANSI palette indices. Custom themes remap to different ANSI indices or 24-bit hex:
247247
248248 ```ts
249249 import { cel, ProcessTerminal, type Theme } from "@cel-tui/core";
packages/components/package.json+1−1
@@ -1,6 +1,6 @@
11 {
22 "name": "@cel-tui/components",
3- "version": "0.2.1",
3+ "version": "0.3.0",
44 "description": "Pre-made components for cel-tui — Button, Spacer, Divider, VDivider, Select, Markdown",
55 "type": "module",
66 "module": "src/index.ts",
packages/core/package.json+1−1
@@ -1,6 +1,6 @@
11 {
22 "name": "@cel-tui/core",
3- "version": "0.2.1",
3+ "version": "0.3.0",
44 "description": "Core framework engine for cel-tui — primitives, layout, rendering, input",
55 "type": "module",
66 "module": "src/index.ts",
packages/types/package.json+1−1
@@ -1,6 +1,6 @@
11 {
22 "name": "@cel-tui/types",
3- "version": "0.2.1",
3+ "version": "0.3.0",
44 "description": "Type definitions for cel-tui, a TypeScript TUI framework",
55 "type": "module",
66 "module": "src/index.ts",
packages/types/src/index.ts+3−2
@@ -30,8 +30,9 @@ export type Color =
3030 /**
3131 * A theme value for a single color slot.
3232 *
33- * - `number` (0–15) — ANSI palette index. Emitted as standard SGR codes
34- * (e.g., index 1 → fg 31, bg 41).
33+ * - `number` (0–15) — ANSI 16 palette index. Emitted as standard SGR codes
34+ * (e.g., index 1 → fg 31, bg 41). Values outside 0–15 are not supported
35+ * and will produce incorrect SGR codes.
3536 * - `string` — 24-bit hex color (e.g., `"#ff0000"`). Emitted as
3637 * true-color SGR codes (`38;2;r;g;b` / `48;2;r;g;b`).
3738 */
spec.md+2−2
@@ -557,7 +557,7 @@ Container sizing props (`width`, `height`, `flex`, `min*`, `max*`, `padding`), f
557557 | `value` | `string` | Current text content (controlled) |
558558 | `onChange` | `(value: string) => void` | Called on text change |
559559 | `onKeyPress` | `(key: string) => boolean \| void` | Key handler, fires before editing. Return `false` to prevent the default editing action. |
560-| `placeholder` | `Text` | Text node shown when value is empty |
560+| `placeholder` | `TextNode` | Text node shown when value is empty (pass a `Text()` call) |
561561
562562 Word-wrap is always on. Cursor position is framework-managed.
563563
@@ -608,7 +608,7 @@ With the default theme, the app automatically inherits whatever terminal color s
608608
609609 #### Theme override
610610
611-A **theme** is a mapping from the 16 color slots to rendering output. The default theme maps to ANSI SGR codes. A custom theme can remap any slot to 256-color indices, 24-bit hex values, or a rearranged ANSI palette:
611+A **theme** is a mapping from the 16 color slots to rendering output. The default theme maps to ANSI SGR codes. A custom theme can remap any slot to different ANSI palette indices, 24-bit hex values, or a mix of both:
612612
613613 ```ts
614614 // Custom theme — remap slots to true color