@codexstar/pi-pompom 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.1.0] - 2026-03-14
+
+### Added
+- Dance state with sparkle particles (`/pompom dance`, Alt+x)
+- Treat command with extra hunger boost (`/pompom treat`, Alt+t)
+- Hug command with energy restore (`/pompom hug`, Alt+h)
+- `/pompom help` with full command reference and platform-aware shortcut labels
+- `/pompom status` showing mood, hunger/energy bars, active theme
+- Random idle speech (12 phrases) for personality
+- Kitty keyboard protocol support (Ghostty, Kitty, WezTerm)
+- Ghostty keybind configuration for reliable macOS shortcuts
+- Cross-platform status bar labels (Option on macOS, Alt on Windows/Linux)
+- Crash isolation: all rendering and input handling wrapped in try/catch
+- Namespaced widget ID (`codexstar-pompom-companion`) to prevent conflicts
+- Dark body outline for better visibility against backgrounds
+- Larger eyes, nose, mouth for clarity at low resolution
+
+### Changed
+- Upgraded anti-aliasing from 2x2 to 4x4 supersampling (16 samples per pixel)
+- Compact single-line status bar (was 4-line box)
+- Descriptive state messages ("Pompom is starving! Drop a treat with ⌥f")
+- Moved creature closer to ground (posY 0 → 0.15)
+- Camera offset (VIEW_OFFSET_Y 0.1 → 0.18) for better framing
+- Replaced emoji particle characters with ASCII to prevent TUI width overflow
+- Speech bubble strips multi-width characters before rendering to grid
+
+### Fixed
+- "Rendered line exceeds terminal width" crash from emoji in particles/speech
+- Extension dropped on other package installs (now published to npm)
+
+## [1.0.0] - 2026-03-14
+
+### Added
+- 3D raymarched virtual pet with physics simulation
+- 10 interactive states: idle, walk, flip, sleep, excited, chasing, fetching, singing, offscreen, peek
+- Keyboard shortcuts via macOS Option key and Windows/Linux Alt key
+- `/pompom` command with on/off/pet/feed/ball/music/color/sleep/wake/flip/hide
+- Day/night sky cycle based on system clock
+- Particle effects: sparkles, music notes, rain, crumbs, sleep Zs
+- Speech bubbles with contextual messages
+- Firefly companion, ball fetch physics, food dropping
+- Hunger and energy needs system
+- 4 color themes: Cloud, Cotton Candy, Mint Drop, Sunset Gold
+- Floor with wood grain pattern and character reflections

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codexstar69
+
+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/README.md

@@ -1,58 +1,128 @@
-# pi-lumo
+<p align="center">
+  <img src="docs/images/hero.png" alt="pi-pompom" width="720">
+</p>
 
-A 3D raymarched virtual pet companion for [Pi CLI](https://github.com/mariozechner/pi-coding-agent).
+<h1 align="center">pi-pompom</h1>
+<p align="center"><strong>A 3D raymarched virtual pet that lives in your terminal.</strong></p>
+<p align="center">
+  <!-- BADGES:START -->
+  <a href="https://www.npmjs.com/package/@codexstar/pi-pompom"><img src="https://img.shields.io/npm/v/@codexstar/pi-pompom.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@codexstar/pi-pompom"><img src="https://img.shields.io/npm/dm/@codexstar/pi-pompom.svg" alt="npm downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/TypeScript-5.x-blue.svg" alt="TypeScript">
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey.svg" alt="Platform">
+  <!-- BADGES:END -->
+</p>
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#commands">Commands</a> ·
+  <a href="#keyboard-shortcuts">Shortcuts</a> ·
+  <a href="#features">Features</a>
+</p>
 
-Lumo is an interactive terminal creature that lives above your editor — it walks, sleeps, chases fireflies, plays fetch, and reacts to your commands.
+---
+
+Pompom is an interactive companion for [Pi CLI](https://github.com/mariozechner/pi-coding-agent). It renders a real-time 3D raymarched creature above your editor using Unicode half-block characters with 4x4 supersampled anti-aliasing. Pompom walks, sleeps, chases fireflies, plays fetch, dances, and reacts to your commands.
 
 ## Install
 
 ```bash
-pi install @codexstar/pi-lumo
+pi install @codexstar/pi-pompom
 ```
 
-## Usage
-
-Lumo appears automatically above the editor. Interact with single-key commands when the editor is empty:
-
-| Key | Action |
-|-----|--------|
-| `⌥p` | Pet |
-| `⌥f` | Feed |
-| `⌥b` | Ball |
-| `⌥m` | Music |
-| `⌥c` | Color |
-| `⌥s` | Sleep |
-| `⌥w` | Wake |
-| `⌥d` | Flip |
-| `⌥o` | Hide |
+## Quick Start
 
-Or use the `/lumo` command:
+Pompom appears automatically when you start Pi. Toggle it with:
 
 ```
-/lumo on       — show companion
-/lumo off      — hide companion
-/lumo pet      — pet Lumo
-/lumo feed     — drop food
-/lumo ball     — throw a ball
-/lumo music    — sing a song
-/lumo color    — cycle color theme
-/lumo sleep    — take a nap
-/lumo wake     — wake up
-/lumo flip     — do a flip
-/lumo hide     — wander offscreen
+/pompom on
+/pompom off
 ```
 
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/pompom` | Toggle companion on/off |
+| `/pompom help` | Show all commands and shortcuts |
+| `/pompom status` | Check mood, hunger, energy, theme |
+| `/pompom pet` | Pet Pompom |
+| `/pompom feed` | Drop food |
+| `/pompom treat` | Special treat (extra hunger boost) |
+| `/pompom hug` | Give a hug (restores energy) |
+| `/pompom ball` | Throw a ball |
+| `/pompom dance` | Dance with sparkle particles |
+| `/pompom music` | Sing a song |
+| `/pompom theme` | Cycle color theme |
+| `/pompom sleep` | Nap on a pillow |
+| `/pompom wake` | Wake up |
+| `/pompom flip` | Do a backflip |
+| `/pompom hide` | Wander offscreen |
+
+## Keyboard Shortcuts
+
+Pompom responds to Alt/Option + key while the companion is active.
+
+| macOS | Windows/Linux | Action |
+|-------|--------------|--------|
+| `⌥p` | `Alt+p` | Pet |
+| `⌥f` | `Alt+f` | Feed |
+| `⌥t` | `Alt+t` | Treat |
+| `⌥h` | `Alt+h` | Hug |
+| `⌥b` | `Alt+b` | Ball |
+| `⌥x` | `Alt+x` | Dance |
+| `⌥m` | `Alt+m` | Music |
+| `⌥c` | `Alt+c` | Theme |
+| `⌥s` | `Alt+s` | Sleep |
+| `⌥w` | `Alt+w` | Wake |
+| `⌥d` | `Alt+d` | Flip |
+| `⌥o` | `Alt+o` | Hide |
+
+Shortcuts work across macOS (Option key), Windows (Alt key), and Linux (Alt key). Four input methods are supported: Ghostty keybinds, ESC prefix, macOS Unicode, and Kitty keyboard protocol.
+
 ## Features
 
-- Full 3D raymarched creature with physics and lighting
-- Natural blinking, breathing, and idle animations
-- Day/night sky cycle based on system time
-- Particle effects (sparkles, music notes, rain, sleep Zs)
-- Speech bubbles with contextual messages
-- Firefly companion that Lumo chases
-- Hunger and energy needs system
-- 4 color themes (Cloud, Cotton Candy, Mint Drop, Sunset Gold)
+- 3D raymarched body with real-time lighting, shadows, and floor reflections
+- 4x4 supersampled anti-aliasing (16 samples per pixel)
+- Natural blinking, breathing, ear wiggling, and tail wagging
+- Day/night sky cycle based on system clock
+- Particle effects: sparkles, music notes, rain, crumbs, sleep Zs
+- Speech bubbles with random idle chatter (12 phrases)
+- Firefly companion that Pompom chases
+- Hunger and energy needs system with visual status bars
+- Ball physics with bouncing and fetch behavior
+- 4 color themes: Cloud, Cotton Candy, Mint Drop, Sunset Gold
+- Dark body outline for visibility against any background
+- Compact status bar with live state messages
+- Crash-isolated rendering: errors never take down the host TUI
+- Namespaced widget ID to prevent conflicts with other extensions
+
+## How It Works
+
+The renderer is a software raymarcher running in your terminal. Each frame:
+
+1. Physics simulation updates position, particles, and state machines (60fps sub-stepping)
+2. Scene objects (body, ears, paws, tail, antenna, ball, food) are built with rotation and oscillation
+3. For each character cell, 16 rays are cast (4x4 grid) and the colors averaged for anti-aliasing
+4. Object hits are shaded with diffuse + wrap lighting, ambient occlusion, specular highlights, and firefly point light
+5. The shaded pixels are encoded as ANSI true-color escape sequences using `▀` half-block characters
+6. Speech bubbles and particle overlays are composited on top
+
+The widget re-renders at ~7 FPS via a 150ms `setInterval`.
+
+## Configuration
+
+Set `POMPOM_NO_KITTY=1` to force half-block rendering on terminals that report Kitty support but don't handle it well.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
 
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE).

package/extensions/pompom.ts

@@ -650,9 +650,11 @@ function renderToBuffers() {
 	const objects = buildObjects();
 	const skyColors = getWeatherAndTime();
 
-	// 4×4 supersampling for maximum anti-aliasing on half-block fallback
-	const step = scale * 0.25;
-	const offsets = [-0.375, -0.125, 0.125, 0.375]; // 4 sub-pixel positions
+	// Hybrid renderer: quadrant blocks at edges (2× horizontal detail),
+	// half-blocks in smooth areas (better gradient color).
+	// 16 Unicode quadrant characters: 4 sub-pixels (2×2) per cell, 2 colors each.
+	const QUAD = " \u2597\u2596\u2584\u259D\u2590\u259E\u259F\u2598\u259A\u258C\u2599\u2580\u259C\u259B\u2588";
+	const halfX = scale * 0.25;
 
 	for (let cy = 0; cy < H; cy++) {
 		for (let cx = 0; cx < W; cx++) {
@@ -660,22 +662,50 @@ function renderToBuffers() {
 			const py1 = (cy * 2.0 - H) * scale + VIEW_OFFSET_Y;
 			const py2 = (cy * 2.0 + 1.0 - H) * scale + VIEW_OFFSET_Y;
 
-			// Top half: 4×4 supersample (16 samples)
-			let tr = 0, tg = 0, tb = 0;
-			for (const oy of offsets) for (const ox of offsets) {
-				const c = getPixel(px + ox * step, py1 + oy * step, objects, skyColors);
-				tr += c[0]; tg += c[1]; tb += c[2];
+			// Sample 4 quadrant centers (TL, TR, BL, BR)
+			const tl = getPixel(px - halfX, py1, objects, skyColors);
+			const tr = getPixel(px + halfX, py1, objects, skyColors);
+			const bl = getPixel(px - halfX, py2, objects, skyColors);
+			const br = getPixel(px + halfX, py2, objects, skyColors);
+
+			// Edge detection: max color difference across the 4 quadrants
+			let maxD = 0;
+			const cs = [tl, tr, bl, br];
+			for (let i = 0; i < 4; i++) for (let j = i + 1; j < 4; j++) {
+				const d = Math.abs(cs[i][0] - cs[j][0]) + Math.abs(cs[i][1] - cs[j][1]) + Math.abs(cs[i][2] - cs[j][2]);
+				if (d > maxD) maxD = d;
 			}
 
-			// Bottom half: 4×4 supersample (16 samples)
-			let br = 0, bg = 0, bb = 0;
-			for (const oy of offsets) for (const ox of offsets) {
-				const c = getPixel(px + ox * step, py2 + oy * step, objects, skyColors);
-				br += c[0]; bg += c[1]; bb += c[2];
+			if (maxD > 60) {
+				// EDGE CELL — use quadrant character for 2× horizontal detail
+				const lum0 = tl[0] * 77 + tl[1] * 150 + tl[2] * 29;
+				const lum1 = tr[0] * 77 + tr[1] * 150 + tr[2] * 29;
+				const lum2 = bl[0] * 77 + bl[1] * 150 + bl[2] * 29;
+				const lum3 = br[0] * 77 + br[1] * 150 + br[2] * 29;
+				const med = (Math.min(lum0, lum1, lum2, lum3) + Math.max(lum0, lum1, lum2, lum3)) / 2;
+
+				const b0 = lum0 >= med ? 1 : 0, b1 = lum1 >= med ? 1 : 0;
+				const b2 = lum2 >= med ? 1 : 0, b3 = lum3 >= med ? 1 : 0;
+				const pattern = (b0 << 3) | (b1 << 2) | (b2 << 1) | b3;
+
+				// Average fg (bright) and bg (dark) group colors
+				let fR = 0, fG = 0, fB = 0, fN = 0;
+				let bR = 0, bG = 0, bB = 0, bN = 0;
+				const bits = [b0, b1, b2, b3];
+				for (let i = 0; i < 4; i++) {
+					if (bits[i]) { fR += cs[i][0]; fG += cs[i][1]; fB += cs[i][2]; fN++; }
+					else { bR += cs[i][0]; bG += cs[i][1]; bB += cs[i][2]; bN++; }
+				}
+				if (!fN) { fR = bR; fG = bG; fB = bB; fN = bN; }
+				if (!bN) { bR = fR; bG = fG; bB = fB; bN = fN; }
+
+				screenChars[cy][cx] = QUAD[pattern];
+				screenColors[cy][cx] = `\x1b[38;2;${Math.round(fR / fN)};${Math.round(fG / fN)};${Math.round(fB / fN)}m\x1b[48;2;${Math.round(bR / bN)};${Math.round(bG / bN)};${Math.round(bB / bN)}m`;
+			} else {
+				// SMOOTH CELL — half-block with averaged top/bottom
+				screenChars[cy][cx] = "▀";
+				screenColors[cy][cx] = `\x1b[38;2;${(tl[0] + tr[0]) >> 1};${(tl[1] + tr[1]) >> 1};${(tl[2] + tr[2]) >> 1}m\x1b[48;2;${(bl[0] + br[0]) >> 1};${(bl[1] + br[1]) >> 1};${(bl[2] + br[2]) >> 1}m`;
 			}
-
-			screenChars[cy][cx] = "▀";
-			screenColors[cy][cx] = `\x1b[38;2;${tr >> 4};${tg >> 4};${tb >> 4}m\x1b[48;2;${br >> 4};${bg >> 4};${bb >> 4}m`;
 		}
 	}
 

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@codexstar/pi-pompom",
-  "version": "1.1.0",
-  "description": "Pompom — a 3D raymarched virtual pet companion for Pi CLI",
+  "version": "1.2.0",
+  "description": "A 3D raymarched virtual pet companion for Pi CLI",
   "type": "module",
+  "author": "codexstar69 <engazedigital@gmail.com>",
+  "license": "MIT",
   "keywords": [
     "pi-package",
     "pi",
@@ -10,9 +12,25 @@
     "pompom",
     "companion",
     "virtual-pet",
-    "terminal-pet"
+    "terminal-pet",
+    "terminal-art",
+    "raymarching",
+    "ascii-art",
+    "ansi",
+    "tui",
+    "widget",
+    "interactive",
+    "animation",
+    "coding-agent"
   ],
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codexstar69/pi-pompom.git"
+  },
+  "homepage": "https://github.com/codexstar69/pi-pompom#readme",
+  "bugs": {
+    "url": "https://github.com/codexstar69/pi-pompom/issues"
+  },
   "scripts": {
     "typecheck": "bunx tsc -p tsconfig.json",
     "check": "bun run typecheck"
@@ -32,6 +50,8 @@
   "files": [
     "extensions",
     "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
     "package.json"
   ]
 }