@@ -0,0 +1,100 @@
1+# Migrating from 0.8.x to 0.9.0
2+
3+`0.9.0` is a breaking minor release while cel-tui is pre-1.0. Upgrade every
4+installed `@cel-tui/*` package together:
5+
6+```bash
7+bun add @cel-tui/core@0.9.0 @cel-tui/components@0.9.0 @cel-tui/clew@0.9.0 @cel-tui/types@0.9.0
8+```
9+
10+## Required changes
11+
12+### Use only supported `TextInput` props
13+
14+`TextInputProps` now uses an explicit `TextInputBaseProps` allowlist. It no
15+longer accepts child-layout props (`gap`, `justifyContent`, `alignItems`,
16+`flexWrap`), container scroll props (`overflow`, `scrollOffset`, `scrollbar`,
17+`scrollbarStyle`, `onScroll`), or `onClick`.
18+
19+Move child layout and click handling to a wrapping `VStack` or `HStack`.
20+TextInput scrolling remains framework-managed; use `scrollStep` to customize
21+mouse-wheel movement.
22+
23+### Make controlled scrolling explicit
24+
25+Scroll ownership is now determined only by `scrollOffset`. An `onScroll`
26+callback without `scrollOffset` observes an uncontrolled container; after the
27+callback accepts the event, the framework updates its own offset.
28+
29+```ts
30+let offset = 0;
31+
32+VStack(
33+ {
34+ overflow: "scroll",
35+ scrollOffset: offset,
36+ onScroll: (nextOffset) => {
37+ offset = nextOffset;
38+ cel.render();
39+ },
40+ },
41+ children,
42+);
43+```
44+
45+Return exactly `false` from `onScroll` to reject that target and bubble to the
46+next scrollable ancestor.
47+
48+### Replace cell mutation with `CellBuffer.set()`
49+
50+`Cell` fields and `EMPTY_CELL` are readonly. Replace in-place mutation:
51+
52+```ts
53+const cell = buffer.get(x, y);
54+buffer.set(x, y, { ...cell, char: "X" });
55+```
56+
57+### Stop using private `cel` test hooks
58+
59+The public `cel` value is now typed as `Cel`; `_getBuffer()` and `_flush()` are
60+no longer part of the package API. Test through `MockTerminal`, `CellBuffer`,
61+and the public emitter functions. Use `cel.redraw()` for a forced full frame
62+and `cel.setTheme()` for runtime palette changes.
63+
64+## Behavior to review
65+
66+- `onKeyPress` now receives `(key, event)`. Existing one-argument handlers are
67+ valid. If Kitty event-type reporting is enabled, release events reach handlers
68+ but never trigger framework editing, focus, activation, or blur actions.
69+- If enabling `kittyKeyboard.reportAllKeys`, also enable
70+ `reportAssociatedText` when TextInputs must insert typed text. Associated-text
71+ reporting implies all-key reporting.
72+- `FocusChangeReason` includes `"auto"`. Add it to exhaustive switches when
73+ using `autoFocus`.
74+- `TextInput({ focusable: false })` now prevents both Tab traversal and mouse
75+ focus. Remove the prop if the previous ignored behavior was intentional.
76+- Focus belongs to the active topmost layer. Add a unique `stateKey` to
77+ stateful nodes that can reorder or recreate callbacks so focus, scroll, and
78+ TextInput state follow the logical node.
79+- `Select` is now backed by `TextInput`: queries preserve exact case and spaces,
80+ cursor editing is grapheme-aware, and Home/End move the query cursor instead
81+ of jumping through results. The callable `select()` form and one-argument
82+ `onSelect(value)` callbacks remain valid; the callback may also receive the
83+ normalized item.
84+- Syntax theme registrations are readonly values. Replace a theme object to
85+ change it rather than mutating it. Direct `SyntaxHighlight()` calls remain
86+ valid; use one `createSyntaxHighlight()` instance per append-heavy snippet
87+ and call `.dispose()` when it is no longer needed.
88+- `ClewToken.start` and `.end` are UTF-16 code-unit offsets. They can be passed
89+ directly to JavaScript `slice()` and `substring()`. Corrected stable patches
90+ and Bash tokenization may also update exact token snapshots.
91+- Low-level ANSI and layout snapshots may change: full frames establish an SGR
92+ reset baseline, and corrected wrapping, clipping, and wide-cell handling can
93+ alter previously invalid output. Rebaseline only after checking the rendered
94+ result.
95+
96+Custom `Terminal` adapters may accept the new optional third argument to
97+`start(onInput, onResize, options)` and forward `options.kittyKeyboard` when
98+they support Kitty progressive-enhancement flags. `ProcessTerminal` now cleans
99+up and then terminates normally on SIGINT/SIGTERM; use an app-owned shutdown
100+path with `cel.stop()` when graceful work must finish first.