pi-sprite 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0 - First pi-sprite release
+
+- Added the `pi-sprite` Pi package with `/pet`, `/sprite`, `/context`, `/recap`, and `/btw` commands.
+- Added passive terminal sprite rendering with ANSI fallback and Kitty/Ghostty/WezTerm native placeholder support.
+- Added Petdex and local pet workflows: `/pet gallery`, `/pet preview`, `/pet install`, `/pet import`, and `/pet import-url`.
+- Added the packaged `pi-sprite-authoring` skill and starter scripts for custom pet creation.
+- Added explicit side-session generation for recap, BTW replies, turn status, and live status, reusing Pi's active model/provider where possible.
+- Added README, MkDocs, WendyBot3000 release demo, package smoke tests, and release validation guidance.
+
+This project began as a slimmed derivative of `pi-pokepet`; `NOTICE.md` retains attribution for the original MIT-licensed work.

package/LICENSE

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

@@ -0,0 +1,7 @@
+# Notices
+
+`pi-sprite` began as a slimmed derivative of [`djdiptayan1/pi-pokepet`](https://github.com/djdiptayan1/pi-pokepet), which is licensed under the MIT License.
+
+The original MIT copyright notice is preserved in `LICENSE` and must remain in all substantial copies or distributions that include derived `pi-pokepet` code.
+
+References used for design research include `pi-btw`, `pi-recap`, `pi-context`, `pi-context-viz`, and `pi-pompom`; those projects are not vendored unless explicitly noted in source files or package metadata.

package/README.md

@@ -0,0 +1,353 @@
+# pi-sprite
+
+`pi-sprite` is a small Pi package that adds a terminal sprite, a context visualizer, a recap bubble, and a side-question thread to [Pi](https://pi.dev).
+
+It is intentionally not a pet simulator or desktop companion. The sprite is there to make agent state easier to read without adding another dashboard.
+
+![pi-sprite WendyBot3000 demo](https://safurrier.github.io/pi-sprite/assets/wendybot3000-demo.gif)
+
+The demo shows real Pi slash commands: importing a pet, opening `/context`, asking `/btw`, running `/recap`, and watching the bottom footer status update.
+
+## Quick start
+
+Install from GitHub today:
+
+```bash
+pi install git:github.com/safurrier/pi-sprite@main
+pi
+```
+
+After the npm release, the install path becomes:
+
+```bash
+pi install npm:pi-sprite
+pi
+```
+
+If you are developing from a checkout, run the local package without installing it:
+
+```bash
+cd /path/to/pi-sprite
+pi -e .
+```
+
+Once Pi opens, get to a useful first sprite:
+
+```text
+/pet status
+/pet gallery
+/pet preview <id-from-gallery>
+/pet install <id-from-gallery>
+/context
+/btw what should I look at next?
+```
+
+`/pet install` selects the installed Petdex sprite automatically. If you already imported pets, use `/pet list` and `/pet choose <id>` instead.
+
+If you already have a local pet folder, import it with an absolute path:
+
+```text
+/pet import /absolute/path/to/my-pet
+/pet choose my-pet
+```
+
+To author a new sprite with agent help, start the guided workflow:
+
+```text
+/pet create tiny desk cat with cozy pixel-art vibes
+```
+
+For deeper custom-pet guidance, read the hosted [Sprite Authoring Guide](https://safurrier.github.io/pi-sprite/tutorials/authoring-sprites/).
+
+If native images ever get stuck after changing renderers or restarting tmux, clean the terminal image layer and redraw:
+
+```text
+/pet clear-native
+/pet show
+```
+
+## What you get
+
+| Command | Use it for |
+| --- | --- |
+| `/pet` | Show, hide, choose, import, author, and configure the sprite. |
+| `/sprite` | Package-specific alias for `/pet`, useful when another package also owns pet-like commands. |
+| `/context` | Open a Claude-style context usage visualizer. |
+| `/recap` | Generate a compact recap of the current session in a speech bubble. |
+| `/btw` | Ask side questions without adding normal messages to the main thread, or generate a recap into the side thread. |
+
+The extension also updates the sprite automatically during agent turns:
+
+- `thinking` while the agent is reasoning
+- `working` while tools run
+- `success` or `error` after turn/tool outcomes
+- compact footer status after turns, with provisional live status during long-running turns
+
+## Sprite behavior
+
+By default the sprite is compact, right-aligned, and label-free. The pet/state label lives in Pi's footer status line instead of taking more space in the widget.
+
+Useful `/pet` commands:
+
+```text
+/pet status
+/pet list
+/pet choose <id>
+/pet import <path>
+/pet import-url <url>
+/pet create [brief]
+/pet author [brief]
+/pet hide
+/pet show
+/pet size tiny|small|medium|large
+/pet label on|off
+/pet align left|right
+/pet turn-status on|off|clear
+/pet live-status on|off|clear
+/pet clear-native
+```
+
+Pets live under:
+
+```text
+~/.pi/agent/pi-sprite/pets/<id>/
+```
+
+`turn-status` and `live-status` are both on by default. Turn status is final and replaces provisional live status when the agent turn ends. Live status waits five minutes into a long-running turn before showing a compact in-progress footer such as `🟣 running tests…`.
+
+## Native image rendering
+
+In Kitty/Ghostty-capable terminals, `pi-sprite` uses Kitty Unicode placeholders by default. Frames are uploaded quietly, while the visible sprite is rendered as placeholder text cells. That keeps tmux in charge of moving and clearing the pane grid, which avoids the ghosted native image placements caused by direct Kitty/Ghostty passthrough.
+
+For tmux, allow passthrough:
+
+```tmux
+set -g allow-passthrough on
+```
+
+To force the ANSI half-block fallback:
+
+```bash
+PI_SPRITE_NATIVE_IMAGES=0 pi
+```
+
+## Custom pets
+
+The simplest local pet has one image per state:
+
+```text
+pet.json
+idle.png
+thinking.png
+working.png
+success.png
+error.png
+```
+
+Minimal `pet.json`:
+
+```json
+{
+	"id": "boba",
+	"name": "Boba",
+	"sprites": {
+		"idle": "idle.png",
+		"thinking": "thinking.png",
+		"working": "working.png",
+		"success": "success.png",
+		"error": "error.png"
+	}
+}
+```
+
+Optional `personality` text gives the selected pet a bounded voice in explicit `/btw` side conversations:
+
+```json
+{
+	"id": "boba",
+	"name": "Boba",
+	"personality": "Warm, concise, lightly mischievous, and practical. Keep answers short.",
+	"sprites": {
+		"idle": "idle.png"
+	}
+}
+```
+
+The personality is not injected into normal main-agent turns. It only guides `/btw` and `/btw:ask` answers.
+
+Import and select a local pet folder:
+
+```text
+/pet import /path/to/pet-folder
+```
+
+Codex/Petdex `pet.json + spritesheet.webp` compatibility is also supported. `pi-sprite` cycles multi-frame spritesheets and infers standard Petdex 8x9 atlases for `spritesheet.*`.
+
+### Author a sprite effectively
+
+This package ships the `pi-sprite-authoring` skill. Use it when you want an agent to turn references, generated art, or hand-drawn frames into an importable pet without losing character consistency across states.
+
+Start the guided flow from Pi:
+
+```text
+/pet create tiny desk cat with cozy pixel-art vibes
+```
+
+You can also invoke the skill directly:
+
+```text
+/skill:pi-sprite-authoring
+```
+
+The recommended authoring loop is:
+
+1. Write a short character brief and gather any local references.
+2. Pick a direction card before generating images.
+3. Create or choose one canonical `idle` image as the identity anchor.
+4. Generate `thinking`, `working`, `success`, and `error` from that anchor.
+5. Review all states for shared silhouette, face, palette, outline, canvas size, and scale.
+6. Add optional simple motion strips only after the static states work.
+7. Add bounded BTW-only `personality` metadata if the pet should affect explicit side replies.
+8. Import the expanded folder with `/pet import <path>`.
+
+Create a starter folder:
+
+```bash
+node skills/pi-sprite-authoring/scripts/create-pet-template.mjs --id desk-cat --name "Desk Cat" --out /tmp/desk-cat-sprite
+```
+
+Add bounded BTW-only personality metadata when desired:
+
+```bash
+node skills/pi-sprite-authoring/scripts/create-pet-template.mjs \
+  --id desk-cat \
+  --name "Desk Cat" \
+  --personality "Warm, concise, lightly mischievous, and practical. Keep BTW answers short." \
+  --out /tmp/desk-cat-sprite
+```
+
+Third-party reference sprites should stay local unless their licenses are verified. This helper downloads Petdex examples into a gitignored folder with provenance notes:
+
+```bash
+node skills/pi-sprite-authoring/scripts/download-petdex-examples.mjs --limit 12 --out /tmp/petdex-downloads
+```
+
+For the full workflow, read the hosted [Sprite Authoring Guide](https://safurrier.github.io/pi-sprite/tutorials/authoring-sprites/). For a deterministic release-demo pet, see the [WendyBot3000 demo guide](https://safurrier.github.io/pi-sprite/tutorials/wendybot3000-demo/) and the repo-only [demo source](https://github.com/safurrier/pi-sprite/tree/main/demos/wendybot3000).
+
+## `/context`
+
+```text
+/context
+/context all
+/sprite:context
+```
+
+`/context` opens a TUI overlay with the active model, context window, token total, estimated category breakdown, and remaining free space. `/sprite:context` is the package-specific alias for setups that already have another `/context` command.
+
+## `/recap`
+
+```text
+/recap
+```
+
+`/recap` generates a short executive-summary recap near the sprite:
+
+```text
+TL;DR: ...
+Recent work: ...
+Current status: ...
+Next: ...
+```
+
+Recap generation first uses an isolated, no-tools Pi side session with the current model, so it does not add messages to the main thread. Direct API-key completion is only a fallback. Use arrow keys, `j/k`, `space/d`, or `u` to scroll longer recaps.
+
+## `/btw`
+
+```text
+/btw <message>
+/btw
+/btw:ask <question>
+/btw:new [message]
+/btw:clear
+/btw:recap
+/btw recap
+/btw:inject
+/btw:summarize
+```
+
+`/btw` is a continuing side conversation outside the main thread. Use `/btw <message>` for follow-ups and `/btw` to reopen the current side thread. Use `/btw:ask <question>` for a one-off aside that does not append to the thread. Use `/btw:recap` or `/btw recap` to generate the normal session recap inside the BTW thread.
+
+Answers appear in an interactive speech bubble that points toward the sprite. Nothing is injected back into the main conversation unless you explicitly run `/btw:inject` or `/btw:summarize`.
+
+## Documentation
+
+Start with the hosted docs; these links work from GitHub, npm, and installed package readers:
+
+- [Docs home](https://safurrier.github.io/pi-sprite/) for the user and contributor index
+- [Sprite Authoring Guide](https://safurrier.github.io/pi-sprite/tutorials/authoring-sprites/) for custom pet authoring
+- [Configuration Reference](https://safurrier.github.io/pi-sprite/reference/configuration/) for default pet state and sprite home setup
+
+From a source checkout, durable docs live under `docs/` and are published with MkDocs Material through GitHub Pages. Build them locally with:
+
+```bash
+uvx --with mkdocs-material mkdocs build --strict
+```
+
+## Development
+
+Install dependencies:
+
+```bash
+mise run setup
+```
+
+Run the usual local gate:
+
+```bash
+mise run check
+```
+
+Run the full verification path, including e2e smoke helpers:
+
+```bash
+mise run verify
+```
+
+Release publishing uses the hosted [Release Checklist](https://safurrier.github.io/pi-sprite/reference/release/).
+
+Equivalent npm commands:
+
+```bash
+npm run check
+npm run test:e2e
+```
+
+Optional e2e variants:
+
+```bash
+PI_SPRITE_E2E_TUI=1 npm run test:e2e
+PI_SPRITE_E2E_MODEL=1 npm run test:e2e
+node tests/e2e/package-smoke.mjs --isolated
+node tests/e2e/package-smoke.mjs --full-config
+```
+
+TUI smoke artifacts are written under:
+
+```text
+artifacts/e2e/
+```
+
+## Non-features
+
+`pi-sprite` deliberately does not include:
+
+- Electron or native floating windows
+- voice, TTS, sounds, songs, or ambient weather
+- hunger, feeding, bonding, XP, accessories, treats, or pet economy
+- autonomous pet commentary or main-thread personality injection
+- 3D/raymarched rendering
+- large always-visible dashboards
+
+## Attribution
+
+`pi-sprite` began as a slimmed derivative of [`djdiptayan1/pi-pokepet`](https://github.com/djdiptayan1/pi-pokepet), licensed under MIT. See `NOTICE.md` and `LICENSE`.

package/examples/README.md

@@ -0,0 +1,15 @@
+# pi-sprite examples
+
+## Custom pet template
+
+`custom-pets/wumpus-template/` contains a ready-to-fill `pet.json` for a Wumpus sprite set.
+
+## Petdex reference downloads
+
+Do not commit third-party sprite downloads without license review. To fetch temporary local references:
+
+```bash
+node skills/pi-sprite-authoring/scripts/download-petdex-examples.mjs --limit 12 --out examples/petdex-downloads
+```
+
+The download directory is gitignored and includes provenance notes.

package/examples/custom-pets/wumpus-template/README.md

@@ -0,0 +1,21 @@
+# Wumpus custom pet template
+
+Add transparent pixel-art images next to `pet.json`:
+
+```text
+idle.png
+thinking.png
+working.png
+success.png
+error.png
+```
+
+Then import in Pi:
+
+```text
+/pet import examples/custom-pets/wumpus-template
+/pet choose wumpus
+/pet show
+```
+
+See `skills/pi-sprite-authoring/references/wumpus-sprite-prompts.md` for image-generation prompts.

package/examples/custom-pets/wumpus-template/pet.json

@@ -0,0 +1,14 @@
+{
+	"id": "wumpus",
+	"name": "Wumpus",
+	"author": "Alex",
+	"description": "A tiny Wumpus companion for pi-sprite.",
+	"personality": "Warm, concise, lightly mischievous, and practical. Keep BTW answers short.",
+	"sprites": {
+		"idle": "idle.png",
+		"thinking": "thinking.png",
+		"working": "working.png",
+		"success": "success.png",
+		"error": "error.png"
+	}
+}

package/extensions/index.ts

@@ -0,0 +1,104 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { registerPiSpriteContextFilter } from "../src/agent/session-entries.ts";
+import { registerBtwCommands } from "../src/btw/index.ts";
+import { registerContextCommand } from "../src/context/index.ts";
+import { registerRecapCommand } from "../src/recap/index.ts";
+import { classifyLiveTurnStatus } from "../src/sprite/live-status.ts";
+import { createSpriteRuntime } from "../src/sprite/runtime.ts";
+import { classifyTurnStatus } from "../src/sprite/turn-status.ts";
+
+export const LIVE_STATUS_INTERVAL_MS = 5 * 60 * 1000;
+
+export default function piSpriteExtension(pi: ExtensionAPI) {
+	registerPiSpriteContextFilter(pi);
+	const sprite = createSpriteRuntime();
+	let turnStatusRun = 0;
+	let liveStatusTimer: ReturnType<typeof setTimeout> | undefined;
+	let liveStatusInFlight = false;
+
+	function clearLiveStatusTimer(): void {
+		if (liveStatusTimer) clearTimeout(liveStatusTimer);
+		liveStatusTimer = undefined;
+	}
+
+	function scheduleLiveStatus(ctx: ExtensionContext, run: number): void {
+		clearLiveStatusTimer();
+		if (!sprite.isLiveStatusEnabled()) return;
+		liveStatusTimer = setTimeout(() => {
+			void updateLiveStatus(ctx, run);
+		}, LIVE_STATUS_INTERVAL_MS);
+	}
+
+	async function updateLiveStatus(ctx: ExtensionContext, run: number): Promise<void> {
+		liveStatusTimer = undefined;
+		if (run !== turnStatusRun || !sprite.isLiveStatusEnabled()) return;
+		if (liveStatusInFlight) return scheduleLiveStatus(ctx, run);
+		liveStatusInFlight = true;
+		const liveGeneration = sprite.setLiveStatusPending();
+		let status: Awaited<ReturnType<typeof classifyLiveTurnStatus>>;
+		try {
+			status = await classifyLiveTurnStatus(ctx);
+		} catch {
+			status = undefined;
+		} finally {
+			liveStatusInFlight = false;
+		}
+		if (run === turnStatusRun) sprite.setLiveStatus(status, liveGeneration);
+		if (run === turnStatusRun) scheduleLiveStatus(ctx, run);
+	}
+
+	pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+		await sprite.start(ctx);
+	});
+	pi.on("agent_start", async (_event: unknown, ctx: ExtensionContext) => {
+		const run = ++turnStatusRun;
+		clearLiveStatusTimer();
+		sprite.clearTurnStatus();
+		sprite.clearLiveStatus();
+		sprite.setState("thinking");
+		scheduleLiveStatus(ctx, run);
+	});
+	pi.on("message_update", async (event: unknown) => {
+		const type = (event as { assistantMessageEvent?: { type?: string } })?.assistantMessageEvent?.type ?? "";
+		if (/^thinking/u.test(type)) sprite.setState("thinking");
+		else if (/^toolcall/u.test(type)) sprite.setState("working");
+	});
+	pi.on("tool_execution_start", async () => sprite.setState("working"));
+	pi.on("tool_result", async (event: unknown) => {
+		const e = event as { isError?: boolean; result?: { isError?: boolean }; error?: unknown };
+		if (e?.isError || e?.result?.isError || e?.error) sprite.setState("error", { resetMs: 2500 });
+	});
+	pi.on("agent_end", async (event: unknown, ctx: ExtensionContext) => {
+		const run = ++turnStatusRun;
+		clearLiveStatusTimer();
+		sprite.clearLiveStatus();
+		sprite.setState("success", { resetMs: 1800 });
+		if (!sprite.isTurnStatusEnabled()) return;
+		sprite.setTurnStatusPending();
+		const status = await classifyTurnStatus(ctx, (event as { messages?: unknown[] }).messages ?? []);
+		if (run === turnStatusRun) sprite.setTurnStatus(status);
+	});
+	pi.on("session_shutdown", async () => {
+		turnStatusRun++;
+		clearLiveStatusTimer();
+		sprite.clearLiveStatus();
+		sprite.shutdown();
+	});
+
+	sprite.registerCommands(pi);
+	registerContextCommand(pi);
+	registerRecapCommand(pi, {
+		setState: (state, options) => sprite.setState(state, options),
+		setRecapStatus: (status) => sprite.setRecapStatus(status),
+		getBubblePlacement: () => sprite.getBubblePlacement(),
+		getSpriteName: () => sprite.getSpriteName(),
+	});
+	registerBtwCommands(pi, {
+		setState: (state, options) => sprite.setState(state, options),
+		setBtwStatus: (status, count) => sprite.setBtwStatus(status, count),
+		setRecapStatus: (status) => sprite.setRecapStatus(status),
+		getBubblePlacement: () => sprite.getBubblePlacement(),
+		getSpriteName: () => sprite.getSpriteName(),
+		getSpritePersonality: () => sprite.getSpritePersonality(),
+	});
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+	"name": "pi-sprite",
+	"version": "1.0.0",
+	"description": "A slim Codex-style sprite companion for Pi with /context, /recap, and /btw.",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"sprite",
+		"petdex",
+		"codex-pets",
+		"context",
+		"recap",
+		"btw"
+	],
+	"license": "MIT",
+	"author": "Alex Furrier",
+	"homepage": "https://github.com/safurrier/pi-sprite#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/safurrier/pi-sprite.git"
+	},
+	"bugs": {
+		"url": "https://github.com/safurrier/pi-sprite/issues"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/index.ts"
+		],
+		"skills": [
+			"./skills"
+		],
+		"image": "https://safurrier.github.io/pi-sprite/assets/wendybot3000-demo.gif"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"scripts": {
+		"setup": "npm install",
+		"fmt": "biome check --write .",
+		"fmt:check": "biome check .",
+		"lint": "biome lint .",
+		"typecheck": "tsc --noEmit",
+		"test": "mkdir -p test-results && node --test --import tsx tests/*.test.ts",
+		"test:e2e": "node tests/e2e/run-e2e.mjs",
+		"build": "npm pack --dry-run",
+		"check": "npm run fmt:check && npm run lint && npm run typecheck && npm test && npm run build",
+		"ci": "npm run check",
+		"verify": "npm run check && npm run test:e2e"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.16",
+		"@earendil-works/pi-ai": "^0.80.3",
+		"@earendil-works/pi-coding-agent": "^0.80.3",
+		"@earendil-works/pi-tui": "^0.80.3",
+		"@types/adm-zip": "^0.5.8",
+		"@types/node": "^22.0.0",
+		"tsx": "^4.22.3",
+		"typescript": "^5.9.0"
+	},
+	"files": [
+		"extensions",
+		"src",
+		"skills",
+		"examples",
+		"README.md",
+		"LICENSE",
+		"NOTICE.md",
+		"CHANGELOG.md"
+	],
+	"dependencies": {
+		"adm-zip": "^0.5.17",
+		"sharp": "^0.33.5"
+	}
+}