@narumitw/pi-statusline 0.25.0 → 0.28.0

package/README.md

@@ -1,18 +1,32 @@
-# ✨ pi-statusline — Configurable Tokyo Night Footer for Pi
+# ✨ pi-statusline — A Beautiful, Practical Footer for Pi
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-statusline)](https://www.npmjs.com/package/@narumitw/pi-statusline) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-statusline` is a native [Pi coding agent](https://pi.dev) extension that replaces Pi's footer with a configurable Tokyo Night powerline statusline.
+`@narumitw/pi-statusline` gives [Pi](https://pi.dev) an opinionated powerline footer that looks good
+without setup and keeps useful context visible as the terminal narrows.
+
+A representative uncolored layout:
+
+```text
+░▒▓ 🤖 sonnet-4 🧠 high 📁 pi-extensions 🌿 main ~2 🪟 ctx 42% 💸 $0.184
+```
 
 ## ✨ Features
 
-- Shows provider, model, thinking, directory, Git/PR state, tools, context, tokens, cost, time, and extension statuses.
-- Uses one Starship-inspired `░▒▓` / `` Tokyo Night layout.
-- Configures segment order, visibility, multiline breaks, surrounding text, palette, density, separators, and extension icons through JSON.
-- Creates a complete editable default configuration on first session start.
-- Applies validated `/statusline settings` edits immediately after an atomic save.
-- Caches Git state outside footer rendering and guards stale session results.
-- Wraps extension statuses safely at narrow terminal widths.
+- **Zero-config default:** model, thinking, workspace, Git/PR state, context use, and cost.
+- **Responsive:** removes lower-priority segments before important information gets clipped.
+- **Quiet when idle:** activity appears only while Pi is streaming or running tools.
+- **Easy choices:** three information levels and seven previewable color presets.
+- **Still flexible:** custom layouts, multiline rows, colors, labels, separators, and status icons stay
+  available under **Advanced**.
+
+> **Need more customization?** See
+> [`pi-starship`](https://github.com/narumiruna/pi-extensions/tree/main/extensions/pi-starship)
+> ([npm](https://www.npmjs.com/package/@narumitw/pi-starship)). It uses a
+> [Starship-inspired](https://starship.rs/) TOML format and style syntax for deeper control over
+> layout, modules, and colors. Choose `pi-statusline` for practical defaults and quick setup.
+>
+> Do not enable both extensions at the same time because both own Pi's footer.
 
 ## 📦 Install
 
@@ -20,176 +34,258 @@
 pi install npm:@narumitw/pi-statusline
 ```
 
-Try it once or from a checkout:
+Try it without installing, or load it from this repository:
 
 ```bash
 pi -e npm:@narumitw/pi-statusline
 pi -e ./extensions/pi-statusline
 ```
 
-Do not enable this together with `@narumitw/pi-starship`: both extensions own Pi's footer. Use `pi-starship` instead when you need full Starship-style format/style grammar.
+For the best result, use a terminal font that includes Powerline glyphs and emoji.
 
-## ⚙️ Configuration
+## 🚀 Quick start
 
-The only configuration source is:
+1. Install the extension and start Pi.
+2. Run `/statusline`.
+3. Choose an appearance or information level; changes apply immediately.
+
+```text
+Appearance (tokyo-night)
+Information (balanced)
+Advanced
+Status
+Help
+```
+
+| Menu item | What it does |
+| --- | --- |
+| **Appearance** | Preview palettes with Up/Down; Enter applies and Escape cancels |
+| **Information** | Preview and apply a curated set of segments |
+| **Advanced** | Open Custom layout or Edit settings JSON |
+| **Status** | Show the effective source, path, appearance, layout, and diagnostics |
+| **Help** | Show command and schema guidance |
+
+### Information levels
+
+Selecting a level replaces only the `segments` array. Unknown and unrelated JSON fields are
+preserved.
+
+| Level | Included segments |
+| --- | --- |
+| **Minimal** | `model cwd branch context` |
+| **Balanced** (default) | `model thinking cwd branch tools context cost` |
+| **Detailed** | `provider model thinking cwd branch tools context tokens cost time` |
+| **Custom** | Any other segment order, including explicit line breaks |
+
+The `tools` segment takes no space while idle.
+
+## 💬 Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/statusline` | Open Appearance, Information, Advanced, Status, and Help |
+| `/statusline settings` | Open the JSON editor in TUI mode |
+| `/statusline status` | Show the effective settings and diagnostics |
+| `/statusline help` | Show command and schema guidance |
+
+The direct `settings`, `status`, and `help` routes remain for compatibility. RPC receives observable
+notifications instead of TUI-only controls. Unknown subcommands and trailing arguments are rejected.
+
+## 📐 Runtime behavior
+
+### Responsive fitting
+
+Each row keeps its configured segment order. If it is too wide, pi-statusline removes the
+lowest-priority segment, recomputes the powerline transitions, and repeats until the row fits.
+Retention priority is highest to lowest:
+
+```text
+context model branch tools cwd thinking cost provider tokens time turn brand
+```
+
+Explicit `line_break` entries remain row boundaries. A single segment that is still too wide is
+ANSI-safely truncated.
+
+### Activity, Git, and PR state
+
+- During active work, `tools` shows `💭 thinking` or `⚙ <tool>` with parallel counts.
+- Activity disappears after the agent settles and resets across session replacement or shutdown.
+- Clean repositories show no Git counters.
+- Dirty counters are `⇡` ahead, `⇣` behind, `+` staged, `~` modified/deleted, `?` untracked, and `!`
+  conflicts.
+- A linked GitHub PR appears with the branch when possible, avoiding a duplicate extension status.
+- Context color changes to warning at 70% and error at 90%.
+- Git state is cached outside footer rendering and stale session results are ignored.
+
+## ⚙️ Settings
+
+The extension uses one user-level file:
 
 ```text
 <getAgentDir()>/pi-statusline.json
 ```
 
-On first session start, the extension atomically creates the complete default document. It never overwrites an existing malformed or unreadable file. A valid legacy `pi-statusline-settings.json` is migrated by preserving its original bytes; the canonical filename wins when both exist.
+There are no project or environment overrides. On first session start, pi-statusline atomically
+creates a complete editable default. It never overwrites malformed or unreadable settings. Settings
+reload on startup, `/reload`, and session replacement.
+
+A valid legacy `pi-statusline-settings.json` is migrated without rewriting its contents. If both files
+exist, `pi-statusline.json` wins.
 
-There are no project overrides or environment-variable overrides.
+### Settings reference
 
-### Default JSON
+| Field | Accepted values | Purpose |
+| --- | --- | --- |
+| `palettePreset` | `tokyo-night`, `ocean`, `sunset`, `forest`, `candy`, `neon`, `mono`, `custom` | Select the active color preset |
+| `palette` | Per-segment `fg`/`bg` `#RRGGBB` colors | Define colors used by `custom` |
+| `density` | `compact`, `cozy` | Control horizontal padding |
+| `separator` | `none`, `dot`, `bar`, `powerline`, `round` | Separate adjacent segments in one color block |
+| `segments` | Ordered unique segment names and `line_break` | Control visibility, order, and rows |
+| `segmentText` | Per-segment `prefix` and `suffix` | Wrap Pi-owned dynamic values |
+| `extensionStatusIcons` | Raw status key or `namespace:*` to icon string | Customize extension status icons |
+
+All fields are optional in an existing document. Missing fields use defaults. Unknown fields produce a
+warning but are preserved by menu saves. Invalid recognized values block saving, leaving the previous
+file and live footer unchanged.
+
+A compact customization example:
 
 ```json
 {
-  "palette": "tokyo-night",
+  "palettePreset": "ocean",
   "density": "compact",
-  "separator": "none",
-  "segments": [
-    "brand",
-    "provider",
-    "model",
-    "thinking",
-    "cwd",
-    "branch",
-    "tools",
-    "context",
-    "tokens",
-    "cost",
-    "time"
-  ],
+  "separator": "dot",
+  "segments": ["model", "thinking", "cwd", "branch", "context", "cost"],
   "segmentText": {
-    "brand": { "prefix": "", "suffix": "" },
-    "provider": { "prefix": "🔌 ", "suffix": "" },
-    "model": { "prefix": "🤖 ", "suffix": "" },
-    "thinking": { "prefix": "🧠 ", "suffix": "" },
-    "cwd": { "prefix": "📁 ", "suffix": "" },
-    "branch": { "prefix": "🌿 ", "suffix": "" },
-    "tools": { "prefix": "", "suffix": "" },
-    "context": { "prefix": "🪟 ctx ", "suffix": "" },
-    "tokens": { "prefix": "🔢 ", "suffix": "" },
-    "cost": { "prefix": "💸 $", "suffix": "" },
-    "time": { "prefix": "🕒 ", "suffix": "" },
-    "turn": { "prefix": "🔁 #", "suffix": "" }
+    "context": { "prefix": "ctx ", "suffix": "" }
   },
   "extensionStatusIcons": {
-    "chrome-devtools": "🌐",
-    "codex-usage": "📊",
-    "usage": "📊",
-    "caffeinate": "💊",
-    "firecrawl": "🔥",
-    "github-pr": "🔎",
-    "goal": "🎯",
-    "lsp": "🧰",
-    "plan-mode": "📝",
-    "pisync": "🔄",
-    "subagents": "🧑‍🤝‍🧑",
-    "unknown-error-retry": "🔁"
+    "goal": "◎",
+    "foo:*": "🧪"
   }
 }
 ```
 
-All fields are optional in an existing document. Missing fields use defaults.
-
-### Appearance
-
-- `palette`: `tokyo-night`, `ocean`, `sunset`, `forest`, `candy`, `neon`, or `mono`.
-- `density`: `compact` or `cozy`.
-- `separator`: `none`, `dot`, `bar`, `powerline`, or `round`.
+Use **Advanced → Edit settings JSON** or `/statusline settings` to edit, validate, atomically save, and
+apply the file.
 
-The separator applies only between adjacent segments in the same color block. Color-block transitions always use ``. Extension statuses remain on separate wrapped lines with their own palette-colored separator.
+## 🎨 Appearance
 
-### Segments
+Named palettes provide contrast-checked color ramps. Appearance previews update while the picker
+moves, but save only when Enter is pressed; Escape restores the saved palette.
 
-`segments` is an ordered list containing:
+When `palettePreset` is `custom`, `palette` maps segment names to foreground/background colors:
 
-```text
-brand provider model thinking cwd branch tools context tokens cost time turn line_break
+```json
+{
+  "palettePreset": "custom",
+  "palette": {
+    "model": { "fg": "#090c0c", "bg": "#a3aed2" },
+    "context": { "fg": "#c0caf5", "bg": "#1d2230" }
+  }
+}
 ```
 
-The array controls visibility and actual rendering order. Data segments must remain unique. The special `line_break` segment starts another footer row and may repeat when another segment separates each occurrence; consecutive `line_break` entries are invalid. Each row receives its own powerline start and end. `line_break` has no `segmentText` entry.
+- Selecting `custom` without a palette copies the active named preset as a starting point.
+- A manually authored `"palettePreset": "custom"` without `palette` uses Tokyo Night colors.
+- Named presets ignore but preserve an existing custom palette.
+- A `palette` object without `palettePreset` selects `custom`.
+- Legacy string palettes such as `"palette": "ocean"` remain accepted.
+- Missing custom colors remain unstyled instead of inheriting Tokyo Night.
+- Adjacent segments with identical colors share one block; transitions use ``.
 
-An empty array hides the main powerline while still allowing extension statuses to render. `turn` is available but omitted by default.
+`segmentText` values must be single-line text without terminal control characters. Use `line_break`
+for another row rather than inserting a newline into a prefix or suffix.
 
-Example multiline layout:
+## 🧩 Advanced layout
 
-```json
-{
-  "segments": ["model", "line_break", "cwd", "line_break", "branch"]
-}
-```
+Open **Advanced → Custom layout** when the curated levels are not enough.
 
-This is valid because the `line_break` entries are separated. `["model", "line_break", "line_break", "cwd"]` is invalid.
+| Key | Action |
+| --- | --- |
+| Up/Down | Navigate |
+| Page Up/Page Down | Move by one viewport |
+| Enter/Space | Show or hide the selected segment |
+| `M` | Enter or leave Move mode |
+| Up/Down in Move mode | Reorder the selected visible segment |
+| `Alt+Up` / `Alt+Down` | Reorder without entering Move mode |
+| `B` | Add or remove a line break after the selected segment |
+| Escape | Leave Move mode first, then close the screen |
 
-### Segment text
+Every successful change saves and applies immediately; closing the screen does not roll it back.
 
-Each visible segment renders as:
+Available data segments:
 
 ```text
-prefix + Pi-owned dynamic value + suffix
+brand provider model thinking cwd branch tools context tokens cost time turn
 ```
 
-Override either string independently:
+Data segments must be unique. `line_break` may repeat when data segments separate occurrences, but
+consecutive breaks are invalid. It has no `segmentText` entry. The menu cleans up leading, trailing,
+and newly consecutive breaks after visibility changes. Manually authored leading/trailing breaks
+represent empty rows.
 
 ```json
 {
-  "segmentText": {
-    "provider": { "prefix": "Provider: " },
-    "context": { "prefix": "[", "suffix": "]" },
-    "cost": { "prefix": "Cost $", "suffix": " USD" }
-  }
+  "segments": ["model", "line_break", "cwd", "branch", "context"]
 }
 ```
 
-Prefix and suffix values must be single-line text without terminal control characters; use the `line_break` segment for additional rows.
+An empty `segments` array hides the main powerline while extension statuses can still render. The
+extension intentionally has no variable or format language; use `pi-starship` when you need one.
 
-This structured model intentionally does not provide variables or a format language. Dynamic Git, PR, activity, usage, token, and cost formatting remains owned by the extension.
+## 🔌 Extension statuses and icons
 
-### Extension status icons
+Other extension statuses appear below the main powerline, wrap to terminal width, and are limited to
+five items. Icons resolve in this order:
 
-`extensionStatusIcons` preserves these rules:
+1. Exact configured raw key, such as `goal` or `foo:server`.
+2. Longest configured colon wildcard, such as `foo:*` or `foo:server:*`.
+3. Unambiguous installed-package alias, such as `@vendor/pi-foo`, `pi-foo`, or `foo`.
+4. Leading emoji supplied by the status text.
+5. Built-in icon.
+6. Generic `🔌` fallback.
 
-- An exact status key wins, such as `goal` or `foo:server`.
-- Installed package aliases such as `@vendor/pi-foo`, `npm:@vendor/pi-foo@1.2.3`, `pi-foo`, or `foo` can configure namespaced statuses.
-- An empty string hides the icon but keeps the status text.
-- A missing key uses the built-in icon or `🔌` for an unknown key.
-- Ambiguous package aliases require an exact status key.
+Set an icon to `""` to hide only the icon. Wildcards match colon namespaces, not slash-delimited keys;
+configure slash keys exactly. Compatibility fallbacks retain `codex-usage`, `pisync`, and
+`unknown-error-retry`; an explicit canonical key wins.
 
-Statuses from other extensions appear below the main powerline. The linked GitHub PR status is hidden from that line when the branch segment already renders it.
+For interoperable extensions, prefer one aggregated key or a stable coexistence slot:
 
-## 💬 Commands
-
-| Command | Purpose |
-| --- | --- |
-| `/statusline settings` | Edit raw JSON in TUI, validate, atomically save, and apply immediately |
-| `/statusline status` | Show settings path/source, effective appearance, segments, and diagnostics |
-| `/statusline help` | Show command and schema guidance |
-
-Invalid or cancelled edits leave both the previous file and effective runtime configuration unchanged. The editor is TUI-only; status and help are safe in TUI, print, JSON, and RPC modes.
+```text
+<extension-id>
+<extension-id>:<stable-slot>
+```
 
-## 🌿 Git and activity details
+Put transient activity in the value and always clear the same complete key.
 
-Git status tokens are hidden for clean repositories. When present, they mean `⇡` ahead, `⇣` behind, `+` staged, `~` modified/deleted, `?` untracked, and `!` conflicts.
+## 🛠️ Troubleshooting
 
-The tools segment distinguishes active tools, streaming/thinking, the last completed tool, and idle state. Parallel calls are summarized without running subprocesses during footer rendering.
+- **Powerline symbols look wrong:** use a font with Powerline glyphs; emoji support is also recommended.
+- **The footer reports settings warnings:** run `/statusline status`, then `/statusline settings` to fix
+  invalid recognized fields.
+- **The footer appears to be replaced:** disable `pi-starship` or another extension that also calls
+  Pi's `setFooter()`.
+- **A custom segment disappears on a narrow terminal:** check the responsive priority above or add an
+  explicit `line_break`.
 
 ## 🗂️ Package layout
 
 ```text
 extensions/pi-statusline/
 ├── src/
-│   ├── ansi.ts
+│   ├── index.ts
+│   ├── statusline.ts
+│   ├── render.ts
+│   ├── powerline.ts
+│   ├── information-profiles.ts
 │   ├── commands.ts
+│   ├── settings.ts
 │   ├── extension-status.ts
 │   ├── git-status.ts
-│   ├── render.ts
-│   ├── settings.ts
-│   ├── statusline.ts
-│   ├── tokyo-night.ts
-│   └── types.ts
+│   ├── ansi.ts
+│   ├── types.ts
+│   └── presets/
 ├── test/
 ├── README.md
 ├── LICENSE
@@ -197,11 +293,12 @@ extensions/pi-statusline/
 └── package.json
 ```
 
-Only `src/statusline.ts` is a Pi entrypoint. Other modules are package-internal.
+`src/index.ts` is the thin Pi entrypoint; all other modules are package-internal.
 
 ## 🔎 Keywords
 
-Pi extension, Pi coding agent, configurable statusline, Tokyo Night, terminal footer, token usage, context window, model status, TypeScript Pi package.
+Pi extension, Pi coding agent, statusline, Tokyo Night, powerline, responsive terminal footer,
+context usage, model status.
 
 ## 📄 License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-statusline",
-	"version": "0.25.0",
+	"version": "0.28.0",
 	"description": "Pi extension that replaces the footer with an information-rich statusline.",
 	"type": "module",
 	"license": "MIT",
@@ -19,7 +19,7 @@
 	],
 	"pi": {
 		"extensions": [
-			"./src/statusline.ts"
+			"./src/index.ts"
 		]
 	},
 	"scripts": {