@akonwi/kit 0.3.4 → 0.4.0

package/dist/plugin.d.ts

@@ -2,11 +2,38 @@ export { Type } from "typebox";
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { Api, Model, Static, TSchema } from "@earendil-works/pi-ai";
+import type {
+	SyntaxPalette,
+	ThemeConfig,
+	ThemeColorTokens as ThemeTokens,
+} from "./themes";
 import type { ToastInput } from "./toasts";
 
+export type { SyntaxPalette, ThemeConfig, ThemeTokens };
+
 export type Disposer = () => void;
 
+export type KitTextStyle = {
+	fg?: string;
+	bg?: string;
+	bold?: boolean;
+	dim?: boolean;
+	italic?: boolean;
+	underline?: boolean;
+	strikethrough?: boolean;
+};
+
+export type KitText = {
+	readonly __kitText: true;
+	readonly text: string;
+	readonly style?: KitTextStyle;
+};
+
+export type KitTextContent = string | KitText | readonly (string | KitText)[];
+
 interface UI {
+	text: (text: string, style?: KitTextStyle) => KitText;
+	theme: () => ThemeConfig;
 	toast: (toast: ToastInput) => void;
 	select(input: {
 		title: string;
@@ -161,6 +188,26 @@ type ModelAPI = {
 	getCurrent: () => Model<Api> | undefined;
 };
 
+export type ChromeContributionSide = "left" | "right";
+
+export type ChromeContributionOptions = {
+	side?: ChromeContributionSide;
+	onClick?: () => void | Promise<void>;
+};
+
+type ChromeContributionAPI = {
+	set: (
+		id: string,
+		content: KitTextContent,
+		options?: ChromeContributionOptions,
+	) => void;
+	clear: (id: string) => void;
+	hide: (id: string) => Disposer;
+};
+
+type FooterAPI = ChromeContributionAPI;
+type HeaderAPI = ChromeContributionAPI;
+
 type SystemAPI = {
 	readonly cwd: string;
 	open: (url: string | URL) => Promise<void>;
@@ -172,6 +219,8 @@ export type EventContext = {
 	session: SessionAPI;
 	settings: SettingsAPI;
 	model: ModelAPI;
+	footer: FooterAPI;
+	header: HeaderAPI;
 	system: SystemAPI;
 };
 
@@ -201,6 +250,8 @@ export interface PluginAPI {
 	session: SessionAPI;
 	settings: SettingsAPI;
 	model: ModelAPI;
+	footer: FooterAPI;
+	header: HeaderAPI;
 	system: SystemAPI;
 	on(handler: EventHandler): Disposer;
 	on<Type extends string>(type: Type, handler: EventHandler<Type>): Disposer;

package/dist/themes.d.ts

@@ -0,0 +1,137 @@
+import type { RGBA } from "@opentui/core";
+
+/** All color tokens consumed by shell components. */
+export type ThemeTokens = {
+	// Backgrounds
+	bg: string;
+	bgSurface: string;
+	bgMuted: string;
+	bgAccent: string;
+	bgTransparent: string;
+	modalBackdrop: RGBA;
+
+	// Borders
+	borderDefault: string;
+	borderFocused: string;
+	borderAccent: string;
+	borderDebug: string;
+	borderStatus: string;
+	composerBashBorder: string;
+	composerBashExcludedBorder: string;
+
+	// Text
+	textPrimary: string;
+	textSecondary: string;
+	textMuted: string;
+	textPlaceholder: string;
+	textDebug: string;
+
+	// Semantic (message roles)
+	userText: string;
+	userTextFocused: string;
+	userBorder: string;
+	assistantText: string;
+	toolText: string;
+	reviewText: string;
+	errorText: string;
+	warningText: string;
+	debugLabel: string;
+
+	// Secondary
+	metaText: string;
+	attachmentText: string;
+
+	// Cursor
+	cursor: string;
+
+	// Picker
+	pickerBg: string;
+	pickerBorder: string;
+	pickerFocusedBg: string;
+	pickerFocusedText: string;
+	pickerItemText: string;
+	pickerScrollThumb: string;
+	pickerScrollTrack: string;
+
+	// Scrollbar
+	scrollbarFg: string;
+	scrollbarBg: string;
+
+	// Spinner / panel
+	panelText: string;
+
+	// Progress bar
+	progressNormal: string;
+	progressWarning: string;
+	progressCritical: string;
+
+	// Toggle
+	toggleOn: string;
+
+	// Diff
+	diffAddedBg: string;
+	diffRemovedBg: string;
+	diffAddedContentBg: string;
+	diffRemovedContentBg: string;
+	diffAddedLineNumberBg: string;
+	diffRemovedLineNumberBg: string;
+	diffCursorBg: string;
+	diffCursorGutterBg: string;
+	diffCursorAddedBg: string;
+	diffCursorRemovedBg: string;
+};
+
+/** Named color slots for syntax highlighting rules. */
+export type SyntaxPalette = {
+	text: string;
+	heading: string;
+	bold: string;
+	italic: string;
+	link: string;
+	list: string;
+	quote: string;
+	codeInline: string;
+	codeBlock: string;
+	strikethrough: string;
+	conceal: string;
+	comment: string;
+	string: string;
+	escape: string;
+	number: string;
+	keyword: string;
+	keywordType: string;
+	function: string;
+	operator: string;
+	variable: string;
+	member: string;
+	builtin: string;
+	type: string;
+	punctuation: string;
+	tag: string;
+	tagAttribute: string;
+	tagDelimiter: string;
+	attribute: string;
+	label: string;
+};
+
+/** Color tokens safe to expose outside the shell. */
+export type ThemeColorTokens = Omit<ThemeTokens, "modalBackdrop">;
+
+/** A fully resolved theme with all tokens filled in (except modalBackdrop). */
+export type ResolvedTheme = {
+	tokens: ThemeColorTokens;
+	syntaxPalette: SyntaxPalette;
+};
+
+/** Public resolved theme config exposed to plugins. */
+export type ThemeConfig = ResolvedTheme & { name: string };
+
+/**
+ * A partial theme definition for overrides.
+ * User themes provide partial overrides
+ * that get merged on top of the system theme.
+ */
+export type ThemeDefinition = {
+	tokens?: Partial<ThemeColorTokens>;
+	syntaxPalette?: Partial<SyntaxPalette>;
+};

package/docs/features/plugins.md

@@ -123,7 +123,51 @@ const ok = await kit.ui.confirm({
 });
 ```
 
-These helpers use Kit-owned dialogs and return `undefined` when selection/input is cancelled. `confirm` returns `false` for cancel/escape. The public plugin UI API is intentionally limited to `toast`, `select`, `input`, and `confirm` so Kit can keep ownership of rendering, focus, theme, and compatibility.
+These helpers use Kit-owned dialogs and return `undefined` when selection/input is cancelled. `confirm` returns `false` for cancel/escape. The public plugin UI API is intentionally limited to `toast`, `select`, `input`, `confirm`, and the `text`/`theme` helpers so Kit can keep ownership of rendering, focus, theme, and compatibility.
+
+## Header and footer status contributions
+
+Plugins can contribute short text items to the header and bottom footer. Kit owns the rendering and layout; plugins provide text or styled text chunks.
+
+```ts
+kit.footer.set("build", "build: passing", { side: "right" });
+kit.footer.set("mode", "watching", { side: "left" });
+kit.header.set("branch", "main", { side: "right" });
+
+const theme = kit.ui.theme();
+
+kit.footer.set(
+	"ci",
+	[
+		kit.ui.text("✓", { fg: theme.tokens.toolText, bold: true }),
+		" tests ",
+		kit.ui.text("passing", { fg: theme.tokens.toolText }),
+	],
+	{
+		side: "right",
+		onClick: () => kit.system.open("https://github.com/org/repo/actions"),
+	},
+);
+
+// Clear an item
+kit.footer.clear("build");
+kit.header.clear("branch");
+
+// Hide a known item contributed by another plugin or built-in.
+// The disposer restores it.
+const showDefaultLocation = kit.footer.hide("VcsStatusPlugin:location");
+const showDefaultModel = kit.header.hide("HeaderBar:model");
+showDefaultLocation();
+showDefaultModel();
+```
+
+Header/footer item IDs passed to `set`/`clear` are scoped to the plugin and are cleaned up automatically when the plugin is disposed or reloaded. `hide` accepts the full item ID to support replacing known built-in contributions.
+
+Use `kit.ui.text(text, style)` to style part or all of a contribution. Supported style fields are `fg`, `bg`, `bold`, `dim`, `italic`, `underline`, and `strikethrough`. Use `kit.ui.theme()` when setting or updating contributions to read the current resolved theme config (`name`, `tokens`, and `syntaxPalette`) and blend with Kit's colors. `onClick` is a whole-contribution action; Kit maps it to terminal mouse events and does not expose raw mouse events to plugins.
+
+Built-in header item IDs are `HeaderBar:title`, `HeaderBar:model`, `HeaderBar:bell`, and `HeaderBar:speech`.
+
+Built-in internal plugins may use additional app-owned capabilities that are not part of the public plugin SDK. For example, built-ins can read VCS state while the public SDK only exposes chrome contribution rendering.
 
 ## Tool approval hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@akonwi/kit",
-	"version": "0.3.4",
+	"version": "0.4.0",
 	"author": "Akonwi Ngoh <akonwi@gmail.com>",
 	"description": "A TUI coding agent",
 	"license": "MIT",