oh-my-tui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oh My TUI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,6 @@
+Third-Party Notices
+
+Pitago
+Portions of Oh My TUI are adapted from Pitago (https://github.com/cavaldos/pitago).
+Copyright (c) 2026 cavaldos.
+Licensed under the MIT License; see LICENSE for the license terms.

package/README.md

@@ -1,3 +1,231 @@
-# Temporary Holding Version
+<h1 align="center">Oh My TUI</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  A new look for Pi. The same native agent underneath.
+</p>
+
+<p align="center">
+  <a href="https://github.com/minkhoaa/oh-my-tui/actions/workflows/ci.yml"><img src="https://github.com/minkhoaa/oh-my-tui/actions/workflows/ci.yml/badge.svg" alt="Verification status"></a>
+  <a href="https://pi.dev"><img src="https://img.shields.io/badge/Pi-extension-blue?style=flat-square" alt="Pi extension"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%3E%3D22.19.0-green?style=flat-square" alt="Node.js 22.19.0 or newer"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-purple?style=flat-square" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Install</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#showcase">Showcase</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="#contributing">Contribute</a>
+</p>
+
+![Oh My TUI Signature interface with a framed composer, session dashboard, and animated companion](media/01-hero-signature.png)
+
+**Oh My TUI (OMT)** is a presentation-focused extension for [Pi](https://pi.dev). It brings visual presets, a session dashboard, richer tool output, and interactive navigation to your terminal—without replacing Pi's agent runtime.
+
+## Features
+
+- **Make it yours.** Choose from six presentation presets, color palettes, surface styles, and optional animated backgrounds.
+- **Keep your session in view.** A right dock shows model details, token usage, workspace status, and an animated companion. Its Agents tab displays available subagent activity.
+- **Read less noise.** Styled messages, folded tool cards, diff previews, and expandable reasoning make long sessions easier to scan.
+- **Find what you need.** Open settings, search the command palette, inspect tool execution, browse Git changes, or navigate saved sessions and conversation branches.
+- **Stay native.** Pi owns execution, model context, tools, sessions, and keybindings. OMT adds no model-facing prompts, tool definitions, or model requests.
+
+## Installation
+
+### Requirements
+
+- [Pi](https://pi.dev) 1.5.0 or newer, installed separately.
+- [Node.js](https://nodejs.org) 22.19.0 or newer.
+- An interactive terminal for OMT's visual interfaces. True-color support is recommended.
+- Optional: `ffmpeg` on `PATH` for importing custom backgrounds. Built-in scenes and bundled backgrounds do not require it.
+
+### From source
+
+To try OMT from a local checkout:
+
+```sh
+git clone https://github.com/minkhoaa/oh-my-tui.git
+cd oh-my-tui
+npm ci --ignore-scripts
+npm run pi:dev
+```
+
+`pi:dev` launches Pi with `extensions/omt/index.ts` loaded for that run. Do not load an installed copy of OMT alongside it.
+
+### From npm
+
+The npm installation command will be available once the package is published:
+
+```sh
+pi install npm:oh-my-tui
+```
+
+To remove an npm-installed copy:
+
+```sh
+pi remove npm:oh-my-tui
+```
+
+## Quick start
+
+Inside Pi, start with:
+
+```text
+/omt settings
+```
+
+Use the settings hub to explore themes, surfaces, and sidebar preferences. Then try:
+
+```text
+/omt palette
+/omt sidebar
+/omt git
+```
+
+OMT starts with the **Signature** preset. To switch presets or try one without changing your saved default:
+
+```text
+/omt theme clean
+/omt theme ember --session
+```
+
+Saved configuration lives in `omt.json` inside Pi's agent directory. Preset commands save the selected preset by default; `--session` makes the change temporary. Use `/omt save` to persist current configuration overrides.
+
+## Showcase
+
+Screenshots show a configured Pi environment. Installed extensions, model names, workspace data, and available integrations will vary with your setup.
+
+### Settings and live themes
+
+Open `/omt settings` to browse configuration and installed resources. The Theme section previews color palettes and background surfaces as you browse.
+
+| Settings hub | Themes and surfaces |
+| :---: | :---: |
+| ![Settings hub showing sections, plugins, and details](media/02-settings-hub.png) | ![Theme settings with color palette and surface choices](media/03-settings-palettes.png) |
+
+<details>
+<summary>Watch live palette browsing</summary>
+
+![Browsing color palettes with live interface previews](media/omt-palette-browsing.gif)
+
+</details>
+
+### Dashboard and companions
+
+Open `/omt sidebar` for a scrollable session dashboard, or `/omt sidebar on` to enable the persistent companion view. Signature uses a right dock in supported fullscreen layouts and a compact companion otherwise.
+
+Choose a companion with `/omt pet`, or press `p` in the dashboard to cycle pets.
+
+| Session dashboard | Companion animation |
+| :---: | :---: |
+| ![Dashboard with session details, token metrics, and workspace information](media/04-sidebar-dashboard.png) | ![Cycling animated companions in the dashboard](media/omt-pet-animation.gif) |
+
+### Command palette and Git explorer
+
+Use `/omt palette` to search OMT actions. Open `/omt git` to inspect working tree changes and unified diffs without leaving Pi.
+
+| Command palette | Git explorer |
+| :---: | :---: |
+| ![Searchable command palette with OMT actions](media/05-command-palette.png) | ![Git explorer showing changed files and a unified diff](media/06-git-explorer.png) |
+
+## Presets
+
+Switch with `/omt theme <name>`. Short aliases such as `clean`, `ember`, and `rail` are also accepted.
+
+| Preset | Style |
+| :--- | :--- |
+| `omt-signature` | Default OMT presentation with a framed composer, dashboard dock, and companion. |
+| `omt-clean` | Clean, restrained styling. |
+| `omt-ember` | Warm, retro-inspired colors. |
+| `omt-rail` | Gutter rails and structured visual accents. |
+| `minimal` | Compact presentation with fewer visual elements. |
+| `native` | Restore native Pi presentation. |
+
+Presets control the overall presentation; Signature palettes and surfaces customize its colors and background. Use `/omt theme` to open theme selection.
+
+## Commands
+
+Enter these commands inside Pi, not your shell. Use `/omt palette` or command completion to discover more actions.
+
+| Command | Action |
+| :--- | :--- |
+| `/omt settings` | Open the settings hub. |
+| `/omt palette` | Search OMT actions. |
+| `/omt theme [name]` | Open theme selection or switch presets. |
+| `/omt save` | Save current configuration overrides as defaults. |
+| `/omt on` / `/omt off` | Enable or disable OMT presentation. |
+| `/omt <component> on` / `/omt <component> off` | Toggle `editor`, `messages`, `tools`, `footer`, or `thinking`. |
+| `/omt sidebar` | Open the scrollable dashboard. |
+| `/omt sidebar on` / `/omt sidebar off` | Show or hide the dock or compact companion. |
+| `/omt pet` | Choose a companion and its visual style. |
+| `/omt inspect` | Inspect session trajectory and tool execution. |
+| `/omt git` | Browse working tree changes and diffs. |
+| `/omt session` | Browse and search saved sessions. |
+| `/omt tree` | Navigate conversation branches. |
+| `/omt model` | Open the model picker using Pi's model registry. |
+| `/omt queue` | Open the prompt queue manager. |
+| `/omt notifications` | View session notification history. |
+| `/omt shortcuts` | Show shortcut help. |
+| `/omt doctor` | Inspect environment and compatibility diagnostics. |
+| `/omt background off` | Disable background effects. |
+
+## Native behavior and compatibility
+
+OMT changes presentation, not the agent contract:
+
+- **Pi retains ownership** of prompt construction, model streaming, tool schemas, complete tool output, context calculations, and session storage. Native editing, paste, autocomplete, attachments, and keybindings remain Pi's responsibility.
+- **Presentation does not rewrite history.** Tool folding and reasoning previews affect display, not the content sent to the model or stored in sessions. Grouped tool cards can expand to show individual calls.
+- **Other extensions keep their surfaces.** OMT avoids replacing an editor, footer, tool renderer, or layout owned by another extension. Cleanup restores only hooks OMT owns; callbacks become inert when ownership is lost.
+- **Layout support is detected at runtime.** The Signature dock uses Pi's exported `HStack` and `setLayoutRoot` APIs, preserving the native root as its left child and reserving 34 columns on the right when supported and wide enough. Unsupported layouts fall back rather than replacing native rendering.
+- **Integrations are optional.** MCP, LSP, and subagent information reflects available host state and telemetry; OMT does not install or run those services. Floating notifications keep their history in `/omt notifications` without shifting the conversation layout.
+
+If a view is unavailable, run `/omt doctor`. For a simpler interface, try `/omt theme minimal`; use `/omt theme native` to return to Pi's presentation.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+npm run verify
+npm pack --dry-run
+```
+
+- `npm run verify` runs TypeScript checking and the test suite.
+- `npm pack --dry-run` checks the publishable package contents.
+- `npm run pi:dev` launches the local extension for interactive development.
+
+### Isolated terminal checks
+
+For presentation changes, also run the offline PTY smoke workflow on a Unix-like system with Python 3 and Pi on `PATH`:
+
+```sh
+python3 test/isolated-ui.py --output /tmp/omt-ui-captures
+```
+
+The script uses temporary home, agent, and session directories with offline mode enabled. It exercises regular and fullscreen layouts, session transitions, dashboard scrolling, pets, resizing, preset switching, draft input, and shutdown without submitting model prompts. ANSI captures, plain text, and JSON summaries are written to the output directory.
+
+### Screenshot capture
+
+`npm run capture` regenerates the showcase assets in `media/`. This is a desktop-specific helper, not a headless test: it requires a running Pi session in a remote-control-enabled Kitty terminal, Hyprland, `grim`, and `ffmpeg`.
+
+The helper sends commands to the live session, changes presets, starts new sessions, switches workspace focus, and overwrites existing captures. Use a dedicated capture session and review [`scripts/capture-screens.mjs`](scripts/capture-screens.mjs) before running it. The target socket and workspaces can be configured through `KITTY_SOCKET`, `TARGET_WORKSPACE`, and `RETURN_WORKSPACE`.
+
+## Contributing
+
+Bug reports, fixes, themes, and accessibility improvements are welcome.
+
+1. [Open an issue](https://github.com/minkhoaa/oh-my-tui/issues) to discuss larger changes before implementing them.
+2. Fork the repository and create a focused branch.
+3. Keep changes in the presentation layer. Do not modify Pi core, installed dependencies, native prompts, or session formats.
+4. Add or update tests, run the development checks above, and include isolated terminal evidence for UI changes.
+5. Open a pull request explaining the change, how it was tested, and any compatibility limitations. Include screenshots or a short recording for visible changes.
+
+For bug reports, include your OMT, Pi, and Node.js versions; terminal and operating system; active preset; relevant extensions; reproduction steps; and `/omt doctor` output. Redact credentials, private paths, and conversation content before sharing captures.
+
+See the [changelog](CHANGELOG.md) for release notes.
+
+## License and acknowledgments
+
+[MIT](LICENSE) © Oh My TUI contributors.
+
+Built for [Pi](https://pi.dev). Portions are adapted from [Pitago](https://github.com/cavaldos/pitago) by cavaldos, also licensed under MIT. See [NOTICE](NOTICE) for attribution.

package/extensions/omt/backgrounds/catalog.json

@@ -0,0 +1,214 @@
+{
+  "version": 1,
+  "backgrounds": [
+    {
+      "alias": "moonlit",
+      "source": "docs/moonlit.gif",
+      "framesSha256": "84ad6dfa33e790aefdaa298a3ef388f7cdf999ad38b7fd8b64910495d8ebe6f1",
+      "metadata": {
+        "version": 1,
+        "id": "ffcac98ac467e5ae84a4a591b0eb74b9dab42da3b11a922f7a948b0763e45e31",
+        "name": "Moonlit",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 558715,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "cloud-drift",
+      "source": "docs/cloud-drift.gif",
+      "framesSha256": "9e17bf6ea75694e952f4d9523303df513bafb96d2254355c3c277b42f1cec90f",
+      "metadata": {
+        "version": 1,
+        "id": "0e510bdcc47eb90cf2fa0f5570a86ed2a3f551e18d0b08ca45a293a154adf812",
+        "name": "Cloud Drift",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 1142629,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "honu-lagoon",
+      "source": "docs/honu-lagoon.gif",
+      "framesSha256": "9a696273411ab8d9ef4a5fa6e337c68a58b4956f9e2dd705edf13f1e67977188",
+      "metadata": {
+        "version": 1,
+        "id": "682d774668506b1a94362fa33f7ac58ba5b97707a487df72aad1754c87d77a83",
+        "name": "Honu Lagoon",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 345786,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "koi-pond",
+      "source": "docs/koi-pond.gif",
+      "framesSha256": "62ed52ce716199304efc4f0a0326a92bd8d5e7b605a4ecaf3bd16fa5b10eb727",
+      "metadata": {
+        "version": 1,
+        "id": "66146b9165c65e4023e9b52f9c4b8a27c01122e73b8aa3a8341075426715da8b",
+        "name": "Koi Pond",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 584054,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "jellyfish",
+      "source": "docs/jellyfish.gif",
+      "framesSha256": "4b9f59dcb60b7bef101286ad110074cefe491de794b2265cafcb1f04cd46e464",
+      "metadata": {
+        "version": 1,
+        "id": "222ac02b85615211803ec625cbf6a3fd4154375f369e605acf13e5e40f6e36d1",
+        "name": "Jellyfish",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 783902,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "lantern-night",
+      "source": "docs/lantern-night.gif",
+      "framesSha256": "60d134778e268a7380f5f8da86c5a98fe0a7238ddd90262c475026ac0d256a81",
+      "metadata": {
+        "version": 1,
+        "id": "7bbff9f7013843e297b7d100ea44d201f8075f97f7585fed40e718c8c7454648",
+        "name": "Lantern Night",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 1016391,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "fireflies",
+      "source": "docs/fireflies.gif",
+      "framesSha256": "590256aab1c20a0b135dbf189f1de9f1ee4e0da87b9e9dd8d89a7f21ea45d9ac",
+      "metadata": {
+        "version": 1,
+        "id": "cb25b2f915f3f24aa32c6da01290ac7378e37f69caa6577f8ba7a6ef1c6e788a",
+        "name": "Fireflies",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 1182918,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "neon-rain",
+      "source": "docs/neon-rain.gif",
+      "framesSha256": "25e537a2a05c5584515f34535f64d36f8a6bec29b09024c2279af64665bcecef",
+      "metadata": {
+        "version": 1,
+        "id": "bc0d2be67532f411ab30669311c5ba6bf829de5912cec14566eff354314e1df4",
+        "name": "Neon Rain",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 334446,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "sakura-dusk",
+      "source": "docs/sakura-dusk.gif",
+      "framesSha256": "f1f3c521fd1902ddbaa8d5f1fbc50ed0b4bce0d1fc5fc796545bbc272870926e",
+      "metadata": {
+        "version": 1,
+        "id": "844b6f6ae3eea05d8dea45f27c60dfc6da48f70add065e95bb1c4d57009d6079",
+        "name": "Sakura Dusk",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 453135,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "snow-cabin",
+      "source": "docs/snow-cabin.gif",
+      "framesSha256": "c7adffa45a30b6ec0701dbf18e485b48ecc0b4279a04c5290814618450e7b2e9",
+      "metadata": {
+        "version": 1,
+        "id": "3255c23dc6a8ddba0ab0dfa8ac60fab4853e9415c36fe3b15d6a5f505bb996f5",
+        "name": "Snow Cabin",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 198710,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    },
+    {
+      "alias": "star-voyage",
+      "source": "docs/star-voyage.gif",
+      "framesSha256": "8d0201efb222e38612fb0ec4dcfd4b3240d039786168ab996d19a69ef0545851",
+      "metadata": {
+        "version": 1,
+        "id": "3d09c99598f43cdd2bbd9ce0e2bd769df6e6189477873f30a33660d9824a317b",
+        "name": "Star Voyage",
+        "kind": "animation",
+        "format": "gif",
+        "sourceBytes": 193901,
+        "width": 160,
+        "height": 90,
+        "frameCount": 40,
+        "frameMs": 100,
+        "loops": 0,
+        "importedAt": "2026-11-09T10:08:07+07:00"
+      }
+    }
+  ]
+}