pi-theme-trio

Ba theme cho Pi: Catppuccin Frappé, Dracula, One Monokai, kèm input skin và đồng bộ màu của phiên Windows Terminal.

Prerequisites

• Hợp đồng public API được đối chiếu với Pi 1.0.0.
• Windows Terminal hỗ trợ query/change foreground/background bằng OSC 10/11.
• Node.js 22.19.0+. Không cần Nerd Font.
• Extension chỉ custom UI trong mode tui; không custom terminal trong print/JSON/RPC.

Installation

Cài package public từ npm bằng package manager của Pi:

pi install npm:@sabo/pi-theme-trio

Pi sẽ thêm package vào cấu hình cá nhân hiện có; không cần tự thay toàn bộ settings.json. Sau khi cài, chạy /reload nếu Pi đang mở.

Khi phát triển từ source checkout, có thể đăng ký trực tiếp thư mục package:

Set-Location "path\to\pi-theme-trio"
pi install .

Không cần bước compile hoặc cài dependency riêng cho runtime extension: Pi nạp TypeScript trực tiếp và cung cấp các host packages được khai báo trong peerDependencies.

Configuration

Thao tác tích hợp chỉ thêm package; không tự đổi theme, model, footer, widget hoặc padding hiện tại.

Sau khi thêm package, trong Pi chạy:

/reload
/theme-trio frappe

Có thể chọn ba tên trio-* qua /settings. Pi lưu lựa chọn theme bằng cơ chế settings của chính nó. Khi đang bật, skin tự theo theme được chọn qua /settings; theme ngoài bộ làm terminal/editor quay về trạng thái trước khi skin áp.

Các JSON trong themes/ là nguồn màu duy nhất. vars.terminalBg, vars.terminalFg, vars.inputBg dùng cho extension; colors chỉ chứa các role thật của Pi. Thay file package cần /reload, không dựa vào hot reload của user themes.

Usage

Tên theme đầy đủ như /theme-trio trio-dracula cũng được chấp nhận.

• Input giữ layout, phím tắt, cursor/IME, autocomplete và paste của CustomEditor; chỉ paint nền/chữ và giữ viền ngang mảnh.
• User/custom message có nền panel; tool output có màu pending/success/error, Markdown/code/diff theo palette.
• Assistant dùng nền chung, không có bubble riêng. Màu chữ thường của terminal được đồng bộ cùng nền.
• Không thay header/footer/widget hiện có; observer của package không render hàng nào. Không polling, animation hoặc network request trong runtime extension.

Khôi phục và fallback

Extension query cả foreground/background trước khi ghi OSC. Query timeout sau 250 ms hoặc thiếu màu: không đổi màu terminal, cảnh báo một lần; input/palette vẫn hoạt động. /theme-trio on hoặc chọn trực tiếp theme cho phép thử lại.

Một snapshot gốc được giữ khi chuyển qua lại giữa ba theme. Snapshot được khôi phục khi chọn theme ngoài bộ, off, quit/reload/session replacement bình thường. Chỉ thay màu của phiên terminal hiện tại; không sửa profile/settings Windows Terminal hoặc bảng màu ANSI.

Nếu có custom editor khác, package không chiếm nó. Nếu extension khác thay editor trong lúc đang dùng skin, cleanup không ghi đè editor mới. Disable custom editor đó rồi /theme-trio on để thử lại input skin.

off là session-only: reload/khởi động lại sẽ bật skin nếu theme lưu hiện tại thuộc bộ. Không ghi file cấu hình riêng.

Verification và publishing

Từ thư mục chứa package.json, kiểm tra tests và nội dung tarball trước khi publish:

npm test
npm pack --dry-run --ignore-scripts

npm test dùng Node built-in test runner và strip-types; bốn test files chỉ import pure modules/node built-ins, mock host APIs. Không cần npm install các peer packages để chạy chúng. Kỳ vọng tests pass; package preview mang tên @sabo/pi-theme-trio và chỉ chứa manifest, ba theme, extension cùng tài liệu, không chứa tests/.

Đăng nhập và publish bằng:

npm login
npm whoami
npm publish

publishConfig.access đã đặt package scoped này ở chế độ public. Tài khoản npm phải có quyền publish trong scope @sabo; mỗi version chỉ có thể publish một lần. Sau khi publish thành công, cài bằng lệnh trong phần Installation.

Trong Pi:

/reload
/theme-trio frappe
/theme-trio dracula
/theme-trio one-monokai
/theme-trio off
/theme-trio on

Nghiệm thu thủ công:

1. Kiểm tra nền/chữ assistant, input, user/custom panels, Markdown/code/diff và tool pending/success/error trên cả ba theme.
2. Đổi qua /settings, đổi nhanh liên tục, cancel picker; không có render/query loop.
3. Nhập tiếng Việt/emoji, multiline, Shift+Enter, paste dài, autocomplete, undo/history, resize hẹp/rộng; cursor và mouse không lệch.
4. Off/chọn theme ngoài bộ/quit bình thường khôi phục foreground/background gốc; prompt, footer/widget hiện có không mất.
5. Reload không nhân đôi observer/editor; theme chọn được giữ qua restart. Kiểm tra hành vi off session-only.
6. Query thất bại hoặc editor conflict không bị ghi đè; cảnh báo không lặp mỗi render.

Assumptions / Not documented

• Unit tests và npm pack --dry-run chỉ kiểm chứng logic thuần cùng nội dung package; chúng không phải bằng chứng runtime trong Pi/Windows Terminal.
• Không cam kết tương thích các Pi/terminal khác ngoài hợp đồng đã đối chiếu. Terminal cần trả lại cả hai màu gốc để được đồng bộ.
• Crash, force-kill hoặc đóng process không có shutdown bình thường không bảo đảm restore. Đóng tab hoặc reset color scheme của terminal nếu màu còn giữ lại.
• Nền panel ANSI là đục; không có alpha, nên che wallpaper/acrylic bên trong panel. Extension không đổi opacity của terminal.
• Giữ instance editor khi đổi giữa ba theme; bật/tắt giữ prompt text theo Pi, không migrate private undo/history giữa các loại editor.
• Việc publish thực tế do maintainer thực hiện bằng tài khoản có quyền với scope @sabo. Nguồn palette và các màu UI được thích nghi ghi ở ATTRIBUTION.md.