@chantier/tui 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes are documented in the root
+[CHANGELOG.md](../../CHANGELOG.md).
+
+## 0.3.0 — 2026-09-16
+
+- Approval card with inline diff previews before every mutation.
+- Remembered grants ("always allow") persist for the session.
+- Screen-reader mode, labeled lines, NO_COLOR, and an ASCII fallback.
+
+See the root changelog for the full list.

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      4. (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 DASHLEA × MLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,11 @@
+# @chantier/tui
+
+Ink-based interactive terminal UI for the [chantier](https://github.com/mlcassociation/chantier)
+coding agent: streaming transcript, approval cards with diff previews,
+remembered grants, screen-reader mode, and NO_COLOR/ASCII fallbacks.
+
+```ts
+import { createTuiStore, startTui } from "@chantier/tui";
+```
+
+License: Apache-2.0.

package/dist/index.d.mts

@@ -0,0 +1,387 @@
+import { ApprovalDecision, ApprovalRequest } from "@chantier/permissions";
+//#region ../../node_modules/cli-boxes/index.d.ts
+/**
+Style of the box border.
+*/
+type BoxStyle = {
+  readonly topLeft: string;
+  readonly top: string;
+  readonly topRight: string;
+  readonly right: string;
+  readonly bottomRight: string;
+  readonly bottom: string;
+  readonly bottomLeft: string;
+  readonly left: string;
+};
+/**
+All box styles.
+*/
+type Boxes = {
+  /**
+	@example
+	```
+	┌────┐
+	│    │
+	└────┘
+	```
+	*/
+  readonly single: BoxStyle;
+  /**
+	@example
+	```
+	╔════╗
+	║    ║
+	╚════╝
+	```
+	*/
+  readonly double: BoxStyle;
+  /**
+	@example
+	```
+	╭────╮
+	│    │
+	╰────╯
+	```
+	*/
+  readonly round: BoxStyle;
+  /**
+	@example
+	```
+	┏━━━━┓
+	┃    ┃
+	┗━━━━┛
+	```
+	*/
+  readonly bold: BoxStyle;
+  /**
+	@example
+	```
+	╓────╖
+	║    ║
+	╙────╜
+	```
+	*/
+  readonly singleDouble: BoxStyle;
+  /**
+	@example
+	```
+	╒════╕
+	│    │
+	╘════╛
+	```
+	*/
+  readonly doubleSingle: BoxStyle;
+  /**
+	@example
+	```
+	+----+
+	|    |
+	+----+
+	```
+	*/
+  readonly classic: BoxStyle;
+  /**
+	@example
+	```
+	↘↓↓↓↓↙
+	→    ←
+	↗↑↑↑↑↖
+	```
+	*/
+  readonly arrow: BoxStyle;
+};
+//#endregion
+//#region ../../node_modules/ansi-styles/index.d.ts
+type CSPair = {
+  // eslint-disable-line @typescript-eslint/naming-convention
+  /**
+	The ANSI terminal control sequence for starting this style.
+	*/
+  readonly open: string;
+  /**
+	The ANSI terminal control sequence for ending this style.
+	*/
+  readonly close: string;
+};
+type ForegroundColor = {
+  readonly black: CSPair;
+  readonly red: CSPair;
+  readonly green: CSPair;
+  readonly yellow: CSPair;
+  readonly blue: CSPair;
+  readonly cyan: CSPair;
+  readonly magenta: CSPair;
+  readonly white: CSPair;
+  /**
+	Alias for `blackBright`.
+	*/
+  readonly gray: CSPair;
+  /**
+	Alias for `blackBright`.
+	*/
+  readonly grey: CSPair;
+  readonly blackBright: CSPair;
+  readonly redBright: CSPair;
+  readonly greenBright: CSPair;
+  readonly yellowBright: CSPair;
+  readonly blueBright: CSPair;
+  readonly cyanBright: CSPair;
+  readonly magentaBright: CSPair;
+  readonly whiteBright: CSPair;
+};
+/**
+Basic foreground color names.
+
+[More colors here.](https://github.com/chalk/chalk/blob/main/readme.md#256-and-truecolor-color-support)
+*/
+type ForegroundColorName = keyof ForegroundColor;
+//#endregion
+//#region ../../node_modules/type-fest/source/primitive.d.ts
+/**
+Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Type
+*/
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+//#endregion
+//#region ../../node_modules/type-fest/source/literal-union.d.ts
+/**
+Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+
+Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
+
+This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
+
+@example
+```
+import type {LiteralUnion} from 'type-fest';
+
+// Before
+
+type Pet = 'dog' | 'cat' | string;
+
+const petWithoutAutocomplete: Pet = '';
+// Start typing in your TypeScript-enabled IDE.
+// You **will not** get auto-completion for `dog` and `cat` literals.
+
+// After
+
+type Pet2 = LiteralUnion<'dog' | 'cat', string>;
+
+const petWithAutoComplete: Pet2 = '';
+// You **will** get auto-completion for `dog` and `cat` literals.
+```
+
+@category Type
+*/
+type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>);
+//#endregion
+//#region src/store.d.ts
+type TuiMode = "input" | "running";
+/** Optional attachment for an approval ask; pre-wired for diff previews. */
+interface TuiPromptDetail {
+  readonly diff?: string;
+}
+interface TuiState {
+  readonly mode: TuiMode;
+  /** Finalized transcript lines (rendered once, never re-rendered). */
+  readonly lines: readonly string[];
+  /** In-progress model text, replaced by lines once finalized. */
+  readonly streamText: string;
+  /** Transient status line (e.g. "thinking…"); "" hides it. */
+  readonly status: string;
+  /** Pending approval request; null while the model is streaming. */
+  readonly prompt: ApprovalRequest | null;
+  /** Optional diff attachment for the pending ask; null when absent. */
+  readonly promptDetail: TuiPromptDetail | null;
+  /** Text typed at the task prompt (input mode only). */
+  readonly inputText: string;
+  /** True once the owner called finish(); App exits after the final render. */
+  readonly finished: boolean;
+}
+type TuiStore = {
+  readonly state: TuiState;
+  /** React-side subscription; returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+  /** Appends one finalized transcript line. */
+  pushLine(line: string): void;
+  /** Appends in-flight model text; flushStream() finalizes it. */
+  appendStream(text: string): void;
+  /** Moves buffered stream text (if any) into finalized lines. */
+  flushStream(): void;
+  /** Shows a transient status (e.g. "thinking…"); "" hides it. */
+  setStatus(status: string): void;
+  /** Enters task-input mode; resolves the previous task signal if still open. */
+  awaitTask(defaultText?: string): Promise<string | null>;
+  /** Submits the typed task text; null = user quit. */
+  submitTask(text: string): void;
+  /** Backspace one character at the task prompt. */
+  backspaceInput(): void;
+  /** Types one printable character at the task prompt. */
+  typeInput(char: string): void;
+  /** Renders the approval prompt and waits for a keypress decision. */
+  ask(req: ApprovalRequest, detail?: TuiPromptDetail): Promise<ApprovalDecision>;
+  decide(decision: ApprovalDecision): void;
+  /**
+   * Esc aborts the current work (deny pending prompt + notify); Ctrl-C quits
+   * the app with a nonzero exit signal.
+   */
+  abort(kind: AbortKind): void;
+  /** Marks the store finished; App unmounts on the next render. */
+  finish(): void;
+};
+type AbortKind = "escape" | "ctrl-c";
+export declare function createTuiStore(handlers: {
+  onAbort: (kind: AbortKind) => void;
+}, isQuitCommand?: (text: string) => boolean): TuiStore;
+//#endregion
+//#region src/app.d.ts
+export declare function TuiApp({ store }: {
+  store: TuiStore;
+}): import("react").FunctionComponentElement<{
+  readonly position?: "absolute" | "relative" | "static" | undefined;
+  readonly top?: number | string | undefined;
+  readonly right?: number | string | undefined;
+  readonly bottom?: number | string | undefined;
+  readonly left?: number | string | undefined;
+  readonly columnGap?: number | undefined;
+  readonly rowGap?: number | undefined;
+  readonly gap?: number | undefined;
+  readonly margin?: number | undefined;
+  readonly marginX?: number | undefined;
+  readonly marginY?: number | undefined;
+  readonly marginTop?: number | undefined;
+  readonly marginBottom?: number | undefined;
+  readonly marginLeft?: number | undefined;
+  readonly marginRight?: number | undefined;
+  readonly padding?: number | undefined;
+  readonly paddingX?: number | undefined;
+  readonly paddingY?: number | undefined;
+  readonly paddingTop?: number | undefined;
+  readonly paddingBottom?: number | undefined;
+  readonly paddingLeft?: number | undefined;
+  readonly paddingRight?: number | undefined;
+  readonly flexGrow?: number | undefined;
+  readonly flexShrink?: number | undefined;
+  readonly flexDirection?: "row" | "column" | "row-reverse" | "column-reverse" | undefined;
+  readonly flexBasis?: number | string | undefined;
+  readonly flexWrap?: "nowrap" | "wrap" | "wrap-reverse" | undefined;
+  readonly alignItems?: "flex-start" | "center" | "flex-end" | "stretch" | "baseline" | undefined;
+  readonly alignSelf?: "flex-start" | "center" | "flex-end" | "auto" | "stretch" | "baseline" | undefined;
+  readonly alignContent?: "flex-start" | "flex-end" | "center" | "stretch" | "space-between" | "space-around" | "space-evenly" | undefined;
+  readonly justifyContent?: "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly" | "center" | undefined;
+  readonly width?: number | string | undefined;
+  readonly height?: number | string | undefined;
+  readonly minWidth?: number | string | undefined;
+  readonly minHeight?: number | string | undefined;
+  readonly maxWidth?: number | string | undefined;
+  readonly maxHeight?: number | string | undefined;
+  readonly aspectRatio?: number | undefined;
+  readonly display?: "flex" | "none" | undefined;
+  readonly borderStyle?: (keyof Boxes | BoxStyle) | undefined;
+  readonly borderTop?: boolean | undefined;
+  readonly borderBottom?: boolean | undefined;
+  readonly borderLeft?: boolean | undefined;
+  readonly borderRight?: boolean | undefined;
+  readonly borderColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderTopColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderBottomColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderLeftColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderRightColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderDimColor?: boolean | undefined;
+  readonly borderTopDimColor?: boolean | undefined;
+  readonly borderBottomDimColor?: boolean | undefined;
+  readonly borderLeftDimColor?: boolean | undefined;
+  readonly borderRightDimColor?: boolean | undefined;
+  readonly borderBackgroundColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderTopBackgroundColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderBottomBackgroundColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderLeftBackgroundColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly borderRightBackgroundColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+  readonly overflow?: "visible" | "hidden" | undefined;
+  readonly overflowX?: "visible" | "hidden" | undefined;
+  readonly overflowY?: "visible" | "hidden" | undefined;
+  readonly backgroundColor?: LiteralUnion<ForegroundColorName, string> | undefined;
+} & {
+  readonly 'aria-label'?: string;
+  readonly 'aria-hidden'?: boolean;
+  readonly 'aria-role'?: "button" | "checkbox" | "combobox" | "list" | "listbox" | "listitem" | "menu" | "menuitem" | "option" | "progressbar" | "radio" | "radiogroup" | "tab" | "tablist" | "table" | "textbox" | "timer" | "toolbar";
+  readonly 'aria-state'?: {
+    readonly busy?: boolean;
+    readonly checked?: boolean;
+    readonly disabled?: boolean;
+    readonly expanded?: boolean;
+    readonly multiline?: boolean;
+    readonly multiselectable?: boolean;
+    readonly readonly?: boolean;
+    readonly required?: boolean;
+    readonly selected?: boolean;
+  };
+} & {
+  children?: React.ReactNode | undefined;
+} & import("react").RefAttributes<import("ink").DOMElement>>;
+/** Screen-reader label for the approval card (ink serializes it as the button name). */
+export declare function approvalLabel(tool: string, input: unknown): string;
+/** Maps a prompt keypress to a decision; null = key not handled by the prompt. */
+export declare function keypressToDecision(key: string): ApprovalDecision | null;
+interface TuiOptions {
+  /** Opt-in screen-reader rendering (also honored: CHANTIER_SCREEN_READER=1). */
+  readonly screenReader?: boolean;
+}
+interface TuiInstance {
+  waitUntilExit(): Promise<void>;
+}
+/** Mounts the TUI. The store drives everything; the caller drives the agent. */
+export declare function startTui(store: TuiStore, options?: TuiOptions): TuiInstance;
+//#endregion
+//#region src/diff.d.ts
+/**
+ * Minimal unified-diff summarization for approval prompts. The TUI shows a
+ * capped preview with add/del coloring and announces the change size to
+ * screen readers via an aria-label, so raw diffs never reach the buffer
+ * unbounded.
+ */
+type DiffLineKind = "add" | "del" | "meta" | "context";
+/** Classifies one unified-diff line for rendering (add=green, del=red, meta=dim). */
+export declare function classifyUnifiedDiffLine(line: string): DiffLineKind;
+interface DiffPreview {
+  /** Lines to display, capped at maxLines. */
+  readonly lines: readonly string[];
+  readonly additions: number;
+  readonly deletions: number;
+  /** Lines beyond the display cap; the "+N more lines" tail count. */
+  readonly hiddenLines: number;
+}
+/** Counts add/del lines across the whole diff and caps the displayed lines. */
+export declare function summarizeUnifiedDiff(diff: string, maxLines?: number): DiffPreview;
+//#endregion
+//#region src/screen-reader.d.ts
+/**
+ * Screen-reader mode: ink serializes the tree to plain linear text (no
+ * borders, no colors), keeps `<Static>` append-only, and rewrites the dynamic
+ * region only when it changes. Enabled by the `--screen-reader` flag or the
+ * CHANTIER_SCREEN_READER=1 environment alias.
+ */
+export declare function resolveScreenReader(flag: boolean | undefined, env: string | undefined): boolean;
+//#endregion
+//#region src/symbols.d.ts
+/**
+ * Decorative characters and box borders used by the TUI. Screen readers skip
+ * or garble ornamental unicode (arrows, checkmarks, middle dots), and border
+ * glyphs pollute magnified review, so everything resolves to ASCII-safe
+ * variants when ASCII mode is requested. All TUI call sites gate through
+ * `resolveSymbols` so the fallback can never leak (gemini-cli #18298).
+ */
+interface TuiSymbols {
+  /** Box border style: "round" normally, "single" in ASCII mode. */
+  readonly border: "round" | "single";
+  /** Separator inside hint lines: "·" normally, "|" in ASCII mode. */
+  readonly hintSeparator: string;
+  /** Truncation ellipsis: "…" normally, "..." in ASCII mode. */
+  readonly ellipsis: string;
+}
+export declare function resolveSymbols(ascii: boolean): TuiSymbols;
+/** CHANTIER_ASCII=1 requests the ASCII-safe rendering. */
+export declare function isAsciiEnv(env: string | undefined): boolean;
+//#endregion
+export type { AbortKind, DiffLineKind, DiffPreview, TuiInstance, TuiOptions, TuiPromptDetail, TuiState, TuiStore, TuiSymbols };

package/dist/index.mjs

@@ -0,0 +1,373 @@
+import { Box, Static, Text, render, useApp, useInput, useIsScreenReaderEnabled } from "ink";
+import { createElement, useEffect, useSyncExternalStore } from "react";
+//#region src/diff.ts
+const META_PREFIXES = [
+	"diff --git ",
+	"--- ",
+	"+++ ",
+	"index ",
+	"@@"
+];
+/** Classifies one unified-diff line for rendering (add=green, del=red, meta=dim). */
+function classifyUnifiedDiffLine(line) {
+	for (const prefix of META_PREFIXES) if (line.startsWith(prefix)) return "meta";
+	if (line.startsWith("+")) return "add";
+	if (line.startsWith("-")) return "del";
+	return "context";
+}
+/** Counts add/del lines across the whole diff and caps the displayed lines. */
+function summarizeUnifiedDiff(diff, maxLines = 10) {
+	const split = diff.split("\n");
+	if (split.length > 0 && split[split.length - 1] === "") split.pop();
+	let additions = 0;
+	let deletions = 0;
+	for (const line of split) {
+		const kind = classifyUnifiedDiffLine(line);
+		if (kind === "add") additions += 1;
+		else if (kind === "del") deletions += 1;
+	}
+	return {
+		lines: split.slice(0, maxLines),
+		additions,
+		deletions,
+		hiddenLines: Math.max(0, split.length - maxLines)
+	};
+}
+//#endregion
+//#region src/screen-reader.ts
+/**
+* Screen-reader mode: ink serializes the tree to plain linear text (no
+* borders, no colors), keeps `<Static>` append-only, and rewrites the dynamic
+* region only when it changes. Enabled by the `--screen-reader` flag or the
+* CHANTIER_SCREEN_READER=1 environment alias.
+*/
+function resolveScreenReader(flag, env) {
+	return flag === true || env === "1";
+}
+//#endregion
+//#region src/symbols.ts
+const UNICODE_SYMBOLS = {
+	border: "round",
+	hintSeparator: "·",
+	ellipsis: "…"
+};
+const ASCII_SYMBOLS = {
+	border: "single",
+	hintSeparator: "|",
+	ellipsis: "..."
+};
+function resolveSymbols(ascii) {
+	return ascii ? ASCII_SYMBOLS : UNICODE_SYMBOLS;
+}
+/** CHANTIER_ASCII=1 requests the ASCII-safe rendering. */
+function isAsciiEnv(env) {
+	return env === "1";
+}
+//#endregion
+//#region src/app.ts
+const PROMPT_HINT_PARTS = [
+	"y allow",
+	"a always",
+	"n deny",
+	"esc abort"
+];
+const INPUT_HINT_PARTS = [
+	"type a task",
+	"enter run",
+	"q quit"
+];
+function TuiApp({ store }) {
+	const state = useSyncExternalStore(store.subscribe, () => store.state);
+	const screenReader = useIsScreenReaderEnabled();
+	const symbols = resolveSymbols(screenReader || isAsciiEnv(process.env.CHANTIER_ASCII));
+	const { exit } = useApp();
+	useInput((input, key) => {
+		const { mode, prompt } = store.state;
+		if (key.ctrl) {
+			store.abort("ctrl-c");
+			return;
+		}
+		if (key.escape) {
+			store.abort("escape");
+			return;
+		}
+		if (mode === "input" && prompt === null) {
+			if (key.backspace || key.delete) {
+				store.backspaceInput();
+				return;
+			}
+			const bundledReturn = /[\r\n]/.test(input ?? "");
+			if (input !== void 0 && input.length > 0) {
+				for (const char of input) if (char !== "\r" && char !== "\n") store.typeInput(char);
+			}
+			if (key.return || bundledReturn) store.submitTask(store.state.inputText);
+			return;
+		}
+		if (prompt !== null) {
+			const decision = keypressToDecision(input.replace(/[\r\n]/g, ""));
+			if (decision !== null) store.decide(decision);
+		}
+	});
+	useEffect(() => {
+		if (!store.state.finished) return;
+		const timer = setTimeout(exit, 50);
+		return () => clearTimeout(timer);
+	});
+	const children = [createElement(Static, {
+		items: [...state.lines],
+		children: (item, index) => createElement(Text, { key: index }, String(item))
+	})];
+	if (state.streamText.length > 0) children.push(createElement(Text, {
+		color: "cyan",
+		"aria-hidden": screenReader
+	}, state.streamText));
+	if (state.status.length > 0) children.push(createElement(Text, { dimColor: true }, state.status));
+	if (state.prompt !== null) {
+		const { tool, input } = state.prompt;
+		children.push(createElement(Box, {
+			flexDirection: "column",
+			borderStyle: symbols.border,
+			borderColor: "yellow",
+			paddingX: 1,
+			"aria-role": "button"
+		}, createElement(Text, {
+			bold: true,
+			color: "yellow",
+			"aria-label": approvalLabel(tool, input)
+		}, `approve ${tool}?`), createElement(Text, { dimColor: true }, summarizeInput(input, symbols.ellipsis)), diffCard(state.promptDetail, symbols), createElement(Text, null, PROMPT_HINT_PARTS.join(` ${symbols.hintSeparator} `))));
+	}
+	if (state.mode === "input" && !state.finished) children.push(createElement(Box, {
+		borderStyle: symbols.border,
+		borderColor: "green",
+		paddingX: 1
+	}, createElement(Text, { color: "green" }, "> "), createElement(Text, null, state.inputText), createElement(Text, { dimColor: true }, `  ${INPUT_HINT_PARTS.join(` ${symbols.hintSeparator} `)}`)));
+	return createElement(Box, { flexDirection: "column" }, ...children);
+}
+/** The unified-diff attachment card, or null when the ask carries no diff. */
+function diffCard(detail, symbols) {
+	if (detail === null) return null;
+	if (typeof detail.diff !== "string" || detail.diff.length === 0) return null;
+	const preview = summarizeUnifiedDiff(detail.diff);
+	return createElement(Box, {
+		flexDirection: "column",
+		borderStyle: symbols.border,
+		borderColor: "cyan",
+		paddingX: 1,
+		"aria-label": `proposed change: ${preview.additions} ${preview.additions === 1 ? "addition" : "additions"}, ${preview.deletions} ${preview.deletions === 1 ? "deletion" : "deletions"}`
+	}, createElement(Text, { dimColor: true }, "proposed change"), ...preview.lines.map((line, index) => createElement(Text, {
+		key: index,
+		...diffTextStyle(classifyUnifiedDiffLine(line))
+	}, line)), preview.hiddenLines > 0 ? createElement(Text, { dimColor: true }, `+${preview.hiddenLines} more lines`) : null);
+}
+function diffTextStyle(kind) {
+	if (kind === "add") return { color: "green" };
+	if (kind === "del") return { color: "red" };
+	if (kind === "meta") return { dimColor: true };
+	return {};
+}
+function summarizeInput(input, ellipsis) {
+	const json = JSON.stringify(input);
+	return json.length > 160 ? `${json.slice(0, 160)}${ellipsis}` : json;
+}
+/** Screen-reader label for the approval card (ink serializes it as the button name). */
+function approvalLabel(tool, input) {
+	const subject = inputSubject(input);
+	return subject.length > 0 ? `approve ${tool} of ${subject}` : `approve ${tool}`;
+}
+function inputSubject(input) {
+	if (typeof input !== "object" || input === null) return "";
+	const record = input;
+	for (const key of [
+		"path",
+		"file_path",
+		"file"
+	]) {
+		const value = record[key];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return "";
+}
+/** Maps a prompt keypress to a decision; null = key not handled by the prompt. */
+function keypressToDecision(key) {
+	const clean = key.replace(/[\r\n]/g, "");
+	if (clean === "y") return { approved: true };
+	if (clean === "a") return {
+		approved: true,
+		remember: true
+	};
+	if (clean === "n") return {
+		approved: false,
+		reason: "user denied"
+	};
+	return null;
+}
+/** Mounts the TUI. The store drives everything; the caller drives the agent. */
+function startTui(store, options = {}) {
+	const screenReader = resolveScreenReader(options.screenReader, process.env.CHANTIER_SCREEN_READER);
+	const instance = render(createElement(TuiApp, { store }), {
+		exitOnCtrlC: false,
+		...screenReader ? { isScreenReaderEnabled: true } : {}
+	});
+	return { waitUntilExit: () => instance.waitUntilExit().then(() => void 0) };
+}
+//#endregion
+//#region src/store.ts
+function createTuiStore(handlers, isQuitCommand = (text) => /^(q|exit|quit)$/i.test(text.trim())) {
+	let state = {
+		mode: "input",
+		lines: [],
+		streamText: "",
+		status: "",
+		prompt: null,
+		promptDetail: null,
+		inputText: "",
+		finished: false
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const pendingTasks = [];
+	let pendingPrompt = null;
+	const set = (patch) => {
+		state = {
+			...state,
+			...patch
+		};
+		for (const listener of listeners) listener();
+	};
+	const STREAM_COALESCE_MS = 20;
+	let pendingStream = "";
+	let streamTimer = null;
+	const disarmStreamTimer = () => {
+		if (streamTimer !== null) {
+			clearTimeout(streamTimer);
+			streamTimer = null;
+		}
+	};
+	const armStreamTimer = () => {
+		if (streamTimer !== null) return;
+		streamTimer = setTimeout(() => {
+			streamTimer = null;
+			if (pendingStream.length === 0) return;
+			const chunk = pendingStream;
+			pendingStream = "";
+			set({ streamText: state.streamText + chunk });
+		}, STREAM_COALESCE_MS);
+	};
+	/** Normalizes an ask detail: only a non-empty string diff survives. */
+	const normalizeDetail = (detail) => {
+		if (typeof detail?.diff === "string" && detail.diff.length > 0) return { diff: detail.diff };
+		return null;
+	};
+	return {
+		get state() {
+			return state;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		pushLine(line) {
+			set({ lines: [...state.lines, line] });
+		},
+		appendStream(text) {
+			pendingStream += text;
+			if (pendingStream.length > 0) armStreamTimer();
+		},
+		flushStream() {
+			disarmStreamTimer();
+			const buffered = `${state.streamText}${pendingStream}`;
+			pendingStream = "";
+			if (buffered.length === 0) return;
+			set({
+				lines: [...state.lines, ...buffered.split("\n")],
+				streamText: ""
+			});
+		},
+		setStatus(status) {
+			set({ status });
+		},
+		backspaceInput() {
+			set({ inputText: state.inputText.slice(0, -1) });
+		},
+		typeInput(char) {
+			set({ inputText: state.inputText + char });
+		},
+		awaitTask() {
+			const { promise, resolve } = Promise.withResolvers();
+			pendingTasks.push({ resolve });
+			set({
+				mode: "input",
+				inputText: "",
+				status: "",
+				prompt: null,
+				promptDetail: null
+			});
+			return promise;
+		},
+		submitTask(text) {
+			if (state.mode !== "input") return;
+			if (isQuitCommand(text)) {
+				for (const task of pendingTasks.splice(0)) task.resolve(null);
+				set({
+					finished: true,
+					inputText: ""
+				});
+				return;
+			}
+			for (const task of pendingTasks.splice(0)) task.resolve(text);
+			set({
+				mode: "running",
+				inputText: ""
+			});
+		},
+		async ask(req, detail) {
+			const { promise, resolve } = Promise.withResolvers();
+			pendingPrompt = { resolve };
+			set({
+				prompt: req,
+				promptDetail: normalizeDetail(detail)
+			});
+			return promise;
+		},
+		decide(decision) {
+			const pending = pendingPrompt;
+			if (pending === null) return;
+			pendingPrompt = null;
+			set({
+				prompt: null,
+				promptDetail: null
+			});
+			pending.resolve(decision);
+		},
+		abort(kind) {
+			if (pendingPrompt !== null) {
+				const pending = pendingPrompt;
+				pendingPrompt = null;
+				set({
+					prompt: null,
+					promptDetail: null
+				});
+				pending.resolve({
+					approved: false,
+					reason: "user aborted"
+				});
+			}
+			if (kind === "ctrl-c") {
+				set({
+					finished: true,
+					mode: "input"
+				});
+				for (const task of pendingTasks.splice(0)) task.resolve(null);
+			}
+			handlers.onAbort(kind);
+		},
+		finish() {
+			set({
+				finished: true,
+				mode: "input"
+			});
+			for (const task of pendingTasks.splice(0)) task.resolve(null);
+		}
+	};
+}
+//#endregion
+export { TuiApp, approvalLabel, classifyUnifiedDiffLine, createTuiStore, isAsciiEnv, keypressToDecision, resolveScreenReader, resolveSymbols, startTui, summarizeUnifiedDiff };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@chantier/tui",
+  "version": "0.3.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Ink-based interactive terminal UI for the chantier coding agent",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mlcassociation/chantier.git"
+  },
+  "homepage": "https://github.com/mlcassociation/chantier#readme",
+  "bugs": {
+    "url": "https://github.com/mlcassociation/chantier/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --clean --out-dir dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@chantier/core": "^0.3.0",
+    "@chantier/permissions": "^0.3.0",
+    "ink": "7.1.1",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "ink-testing-library": "4.0.0",
+    "tsdown": "0.23.0",
+    "@types/react": "^19.2.0"
+  }
+}