Metadata-Version: 2.4
Name: cjm-substrate-tui-kit
Version: 0.0.2
Summary: Shared TUI components for cjm-substrate workflow frontends: manifest-driven config forms from capability config schemas, cursor-windowed viewport math, sidecar state store, audio chunk playback, and repaint governance — extracted demand-driven from the transcription and transcript-correction TUIs. Born on-graph.
Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/cj-mills/cjm-substrate-tui-kit
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: sounddevice
Requires-Dist: soundfile

# cjm-substrate-tui-kit

<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->

_No purpose recorded on-graph yet — author it with_ `assert ee2dd69f-1e52-5079-a6e6-a529cec821e7 purpose "…"` _(or by the repo's entity key)._

## Modules

- **`cjm_substrate_tui_kit`**
- **`cjm_substrate_tui_kit.audio`** — VAD-chunk audio playback for TUI frontends — a persistent-output-stream
- **`cjm_substrate_tui_kit.form`** — Manifest-driven config form model — the tui-kit keystone (work item
- **`cjm_substrate_tui_kit.repaint`** — Repaint coalescing for event-driven TUIs — throttle paint bursts to a
- **`cjm_substrate_tui_kit.state`** — JSON sidecar for TUI view-state — settings and bookmarks that persist
- **`cjm_substrate_tui_kit.viewport`** — Cursor-windowed viewport math for flat list panes — the tui-kit's first

## API

### `cjm_substrate_tui_kit.audio`

- `ChunkPlayer` _class_ — Persistent-output-stream VAD-chunk player — the focus-walk auto-play engine.
- `load_chunk` _function_ — Read one VAD chunk's samples from the model-input WAV — frame-sliced, sample-accurate.
- `stretch` _function_ — Pitch-preserving time-stretch (WSOLA, numpy-only) — the playback-speed engine.

### `cjm_substrate_tui_kit.form`

- `ConfigField` _class_ — One schema property as an editable form row.
- `ConfigForm` _class_ — A capability's editable config, derived from its manifest config_schema.

### `cjm_substrate_tui_kit.repaint`

- `RepaintThrottle` _class_ — Leading-edge paint + trailing-tick flush inside a fixed window.

### `cjm_substrate_tui_kit.state`

- `SidecarState` _class_ — One JSON sidecar file: never-raise load, merge-on-save, best-effort write.

### `cjm_substrate_tui_kit.viewport`

- `tail` _function_ — Clamp a string to width keeping its END.
- `visible_slice` _function_ — Clamped cursor-centered window over a flat list: paint rows[start:end].

## Dependencies

**Depends on:** `numpy`, `sounddevice`, `soundfile`
**Used by:** `cjm-transcript-correction-tui`, `cjm-transcript-decomp-tui`, `cjm-transcription-tui`, `cjm-workflow-hub-tui`
