@@ -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.