@akonwi/kit 0.3.4 → 0.5.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

@@ -13,6 +13,8 @@ Discovery is non-recursive. Only direct `.ts` files in those directories are loa
 
 Project plugins load after user plugins. Built-in plugins load before both.
 
+Built-in plugins initialize during core app setup. User and project plugins load in the background after the shell is ready, so slow dependency installation or bundling does not block basic startup. Commands, tools, and chrome contributions from those external plugins become available once loading finishes.
+
 If an external plugin registers a command, tool, or debug section that already exists, Kit treats that as a plugin failure and reports it with a persistent toast.
 
 Kit does **not** load plugins from `.agents/plugins/`. Plugins execute code and are Kit-specific functionality, while `.agents/` is reserved for compatibility-oriented resources such as prompts, skills, and MCP config.
@@ -123,7 +125,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
 
@@ -155,7 +201,7 @@ kit.onToolCall(async (toolCall, ctx) => {
 
 ## Reloading
 
-Use `/reload` after editing plugin files. Kit re-discovers plugin files, re-bundles them into Kit's plugin cache, and imports the fresh bundles so changed `.ts` contents are picked up.
+Use `/reload` after editing plugin files. Kit re-discovers plugin files, re-bundles them into Kit's plugin cache, and imports the fresh bundles so changed `.ts` contents are picked up. External plugin loading continues in the background after the session reload completes.
 
 Plugin modules are loaded synchronously, so top-level `await` is not supported in plugin files. Async command, event, and tool handlers are supported.
 

package/package.json

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