pi-sprite 1.0.0

package/skills/pi-sprite-authoring/references/petdex-reference-to-custom-pet.md

@@ -0,0 +1,155 @@
+# Petdex Reference to Custom Pet
+
+Use this workflow when the user wants a custom pet inspired by Boba, Petdex, Sprite Mart, or another existing sprite.
+
+## Contents
+
+- Discover reference pets
+- Reference-image binding
+- Direction-card stage
+- Character lock
+- State set
+- Character cohesion review
+- Packaging loop
+
+## Discover reference pets
+
+In Pi:
+
+```text
+/pet gallery
+/pet search boba
+/pet preview <slug>
+/pet install <slug>
+```
+
+For local reference files without installing in the active session:
+
+```bash
+node skills/pi-sprite-authoring/scripts/download-petdex-examples.mjs \
+  --query boba \
+  --limit 5 \
+  --out /tmp/pi-sprite-petdex-refs
+```
+
+Downloaded Petdex files are local reference material. Do not commit or redistribute third-party assets unless their licenses are verified.
+
+## Reference-image binding
+
+Before generating images, bind each reference to an explicit role and instruction. Do not pass vague instructions like "use this image".
+
+Good binding:
+
+```json
+{
+  "id": "boba-petdex",
+  "path": "/tmp/pi-sprite-petdex-refs/boba/spritesheet.webp",
+  "role": "style_reference",
+  "instruction": "Use for compact pixel-art scale, outline thickness, simple pose language, and terminal readability. Do not copy the exact character identity, costume, or sprite frames."
+}
+```
+
+Reference roles:
+
+- `style_reference` — palette, outline, pixel density, pose simplicity.
+- `scale_reference` — canvas size, silhouette size, padding.
+- `character_reference` — user-owned character identity that should be preserved.
+- `mood_reference` — emotional target only.
+- `negative_reference` — what to avoid.
+
+For unclear-license Petdex assets, use `style_reference` or `scale_reference`, not `character_reference`.
+
+## Direction-card stage
+
+Turn the user brief and references into 3-5 direction cards before generating. Each card should be a concrete pet concept, not just a style adjective.
+
+```markdown
+1. **Sleepy Tapioca Familiar**
+   - Character: round boba-pearl creature with a tiny straw sprout
+   - Mood: cozy, drowsy, lightly mischievous
+   - Visual lock: cream/caramel/brown palette, dark chunky outline, dot eyes, centered 128x128 canvas
+   - Why it fits: round silhouette stays readable in terminal size
+   - Risk: could look like a generic boba mascot unless the straw/ears are distinctive
+```
+
+Ask the user to choose, combine, or revise directions. If the user says to proceed autonomously, state the chosen direction and why.
+
+## Character lock
+
+After direction selection, write a stable character lock and repeat it in every state prompt.
+
+```text
+Canonical character lock:
+A tiny original boba-tea terminal companion. Rounded milk-tea body, two large tapioca-pearl ear shapes, small straw sprout tilted left, sleepy dot eyes, tiny paws, cream/brown/caramel palette, bold dark pixel outline. Always centered on a transparent 128x128 canvas with 8px padding. No text, logo, cup branding, background, shadow, or watermark.
+```
+
+## State set
+
+Do not generate all states independently from only a style reference. First generate 3-6 `idle` candidates, choose one canonical anchor, and then generate the remaining states as edits that preserve that anchor's character identity.
+
+Generate or select one image for each `pi-sprite` state:
+
+- `idle` — neutral/resting pose.
+- `thinking` — pondering, curious, tilted, or looking upward; no question-mark text.
+- `working` — focused/active/typing; keep props large and simple.
+- `success` — celebratory/happy; no text.
+- `error` — confused/worried but still cute; no text.
+
+Prefer five separate state images for first-time custom pets. Use spritesheets only after the five-state identity works.
+
+## Character cohesion review
+
+After generating state images, compare each state to the canonical anchor before packaging.
+
+```markdown
+## Character cohesion review
+
+Canonical anchor: /tmp/boba-inspired/anchor/idle.png
+
+| State | Identity | Silhouette | Face | Ears/props | Palette/outline | State readability | Verdict |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| thinking | same | same | minor drift | same | same | clear | accept |
+| working | major drift | changed body | changed face | missing straw | same | clear | regenerate |
+```
+
+Reject states with major drift in identity, silhouette, face, signature props, palette, or outline. Regeneration prompts should say exactly what to preserve from the anchor and only change pose/expression. Use `character-cohesion-review.md` for a reusable review prompt and table format.
+
+If accepted images lack alpha, run `scripts/remove_sprite_background.py` and package the cleaned images, not the raw generated files.
+
+## Packaging loop
+
+Create a pet template:
+
+```bash
+node skills/pi-sprite-authoring/scripts/create-pet-template.mjs \
+  --id boba-inspired \
+  --name "Boba Inspired" \
+  --out /tmp/boba-inspired-pet
+```
+
+Copy or rename selected outputs:
+
+```text
+/tmp/boba-inspired-pet/idle.png
+/tmp/boba-inspired-pet/thinking.png
+/tmp/boba-inspired-pet/working.png
+/tmp/boba-inspired-pet/success.png
+/tmp/boba-inspired-pet/error.png
+```
+
+Import and test:
+
+```text
+/pet import /tmp/boba-inspired-pet
+/pet choose boba-inspired
+/pet size small
+/pet label off
+/pet show
+```
+
+If native images look stale or stuck:
+
+```text
+/pet clear-native
+/pet show
+```

package/skills/pi-sprite-authoring/references/wumpus-sprite-prompts.md

@@ -0,0 +1,54 @@
+# Wumpus Sprite Prompts
+
+Use these prompts with an image generator plus 2-5 reference sprites for scale and pixel-art treatment.
+
+## Single idle sprite
+
+```text
+Create a transparent PNG pixel-art sprite of Wumpus, Discord's friendly mascot creature, for a terminal companion.
+
+Canvas and style:
+- 64x64 or 128x128 square canvas
+- transparent background
+- cute front-facing or slight 3/4 idle pose
+- rounded body, small horns, friendly face
+- bold dark outline
+- limited Discord-inspired palette
+- readable when scaled down to tiny terminal size
+- no text, no logo, no background, no shadow
+- leave 4-8px transparent padding around the character
+
+Use attached reference sprites only for scale, outline thickness, pose simplicity, and pixel-art treatment. Do not copy their character design.
+```
+
+## Full pi-sprite state set
+
+```text
+Create five matching transparent PNG pixel-art sprites of the same Wumpus character for a terminal companion.
+
+Required files/states:
+1. idle — relaxed neutral smile
+2. thinking — curious head tilt or small question-mark mood, no text
+3. working — focused typing or tiny laptop pose
+4. success — happy celebratory sparkle, no text
+5. error — confused or worried, no text
+
+Consistency requirements:
+- same canvas size for every image, preferably 64x64 or 128x128
+- same character proportions
+- same outline thickness
+- same color palette
+- transparent background
+- centered with consistent feet/baseline
+- simple readable silhouette
+```
+
+## If the model struggles with pixel-perfect output
+
+Ask for a larger clean pixel-art source, then downscale with nearest-neighbor:
+
+```text
+Create this as crisp pixel art on a 512x512 transparent canvas, with large blocky pixels and no anti-aliased painterly texture. Keep the character centered and simple so it can be downscaled to 64x64.
+```
+
+Then crop/downscale to 64x64 or 128x128 with nearest-neighbor in an image editor.

package/skills/pi-sprite-authoring/scripts/assemble_sprite_strip.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Assemble normalized pi-sprite frames into a horizontal animation strip."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Assemble pi-sprite frame PNGs into a horizontal animation strip.")
+    parser.add_argument("--frame", type=Path, action="append", required=True, help="Input frame image path; repeat in animation order")
+    parser.add_argument("--output", type=Path, required=True, help="Output strip PNG path")
+    parser.add_argument("--metadata", type=Path, help="Optional metadata JSON path")
+    parser.add_argument("--frame-width", type=int, default=128, help="Frame width in pixels")
+    parser.add_argument("--frame-height", type=int, default=128, help="Frame height in pixels")
+    parser.add_argument("--fit", choices=["contain", "cover"], default="contain", help="Resize mode for each input frame")
+    parser.add_argument("--dry-run", action="store_true", help="Write metadata only; do not write the strip")
+    return parser.parse_args()
+
+
+def process(args: argparse.Namespace) -> dict[str, Any]:
+    if args.frame_width <= 0 or args.frame_height <= 0:
+        raise ValueError("--frame-width and --frame-height must be positive")
+    if not args.frame:
+        raise ValueError("at least one --frame is required")
+    for frame in args.frame:
+        if not frame.exists():
+            raise ValueError(f"frame image missing: {frame}")
+        if not frame.is_file():
+            raise ValueError(f"frame image is not a file: {frame}")
+
+    from PIL import Image
+
+    normalized: list[Image.Image] = []
+    input_sizes: list[list[int]] = []
+    for frame in args.frame:
+        image = Image.open(frame).convert("RGBA")
+        input_sizes.append([image.width, image.height])
+        if args.fit == "contain":
+            image.thumbnail((args.frame_width, args.frame_height), Image.Resampling.LANCZOS)
+            canvas = Image.new("RGBA", (args.frame_width, args.frame_height), (0, 0, 0, 0))
+            canvas.alpha_composite(image, ((args.frame_width - image.width) // 2, (args.frame_height - image.height) // 2))
+        else:
+            scale = max(args.frame_width / image.width, args.frame_height / image.height)
+            resized = image.resize((round(image.width * scale), round(image.height * scale)), Image.Resampling.LANCZOS)
+            left = (resized.width - args.frame_width) // 2
+            top = (resized.height - args.frame_height) // 2
+            canvas = resized.crop((left, top, left + args.frame_width, top + args.frame_height))
+        normalized.append(canvas)
+
+    output_size = [args.frame_width * len(normalized), args.frame_height]
+    if not args.dry_run:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        strip = Image.new("RGBA", tuple(output_size), (0, 0, 0, 0))
+        for index, frame in enumerate(normalized):
+            strip.alpha_composite(frame, (index * args.frame_width, 0))
+        strip.save(args.output, format="PNG")
+
+    metadata = {
+        "dry_run": args.dry_run,
+        "output": str(args.output),
+        "frames": [str(frame) for frame in args.frame],
+        "frame_count": len(args.frame),
+        "frame_width": args.frame_width,
+        "frame_height": args.frame_height,
+        "fit": args.fit,
+        "input_sizes": input_sizes,
+        "output_size": output_size,
+        "manifest_frame": {"width": args.frame_width, "height": args.frame_height},
+    }
+    if args.metadata:
+        args.metadata.parent.mkdir(parents=True, exist_ok=True)
+        args.metadata.write_text(json.dumps(metadata, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return metadata
+
+
+def main() -> int:
+    try:
+        args = parse_args()
+        metadata = process(args)
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+    print(f"output: {metadata['output']}")
+    print(f"dry_run: {metadata['dry_run']}")
+    print(f"frame_count: {metadata['frame_count']}")
+    print(f"frame_size: {metadata['frame_width']}x{metadata['frame_height']}")
+    print(f"output_size: {metadata['output_size']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/pi-sprite-authoring/scripts/create-pet-template.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+function arg(name, fallback = "") {
+	const index = process.argv.indexOf(`--${name}`);
+	return index >= 0 ? (process.argv[index + 1] ?? fallback) : fallback;
+}
+
+function normalizeId(value) {
+	return value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/gu, "-")
+		.replace(/^-+|-+$/gu, "")
+		.slice(0, 80);
+}
+
+const id = normalizeId(arg("id", "wumpus"));
+const name = arg("name", "Wumpus").trim() || id;
+const author = arg("author", "").trim();
+const personality = arg("personality", "").trim();
+const out = arg("out", `./${id}-sprite`);
+
+if (!id) {
+	console.error("Missing valid --id");
+	process.exit(1);
+}
+
+mkdirSync(out, { recursive: true });
+const manifest = {
+	id,
+	name,
+	...(author ? { author } : {}),
+	description: `A tiny ${name} companion for pi-sprite.`,
+	...(personality ? { personality } : {}),
+	sprites: {
+		idle: "idle.png",
+		thinking: "thinking.png",
+		working: "working.png",
+		success: "success.png",
+		error: "error.png",
+	},
+};
+writeFileSync(join(out, "pet.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+writeFileSync(
+	join(out, "README.md"),
+	`# ${name} pi-sprite pet\n\nAdd these transparent PNG/WebP files next to \`pet.json\`:\n\n- idle.png\n- thinking.png\n- working.png\n- success.png\n- error.png\n\nImport with:\n\n\`\`\`text\n/pet import ${out}\n/pet choose ${id}\n/pet show\n\`\`\`\n`,
+);
+console.log(`Created ${out}`);
+console.log(`Next: add sprite images, then run /pet import ${out}`);

package/skills/pi-sprite-authoring/scripts/create_motion_strip.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Create a simple motion-loop strip from one pi-sprite state image."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+PRESETS: dict[str, list[tuple[int, int]]] = {
+    "bob": [(0, 1), (0, -2), (0, -1), (0, 1)],
+    "thinking-bob": [(0, 1), (-1, -2), (0, -1), (1, 1)],
+    "working-tap": [(0, 1), (0, -1), (1, 0), (0, -1), (-1, 0), (0, 1)],
+    "success-bounce": [(0, 1), (0, -3), (0, -1), (0, -3), (0, 1)],
+    "error-droop": [(0, 0), (0, 2), (-1, 1), (0, 2)],
+}
+
+
+def parse_offset(value: str) -> tuple[int, int]:
+    try:
+        x_text, y_text = value.split(",", 1)
+        return int(x_text), int(y_text)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("offsets must be X,Y pixel pairs, e.g. 0,-2") from exc
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Create a simple pi-sprite motion strip from a single frame image.")
+    parser.add_argument("--input", type=Path, required=True, help="Input state image")
+    parser.add_argument("--output", type=Path, required=True, help="Output strip PNG path")
+    parser.add_argument("--metadata", type=Path, help="Optional metadata JSON path")
+    parser.add_argument("--frame-width", type=int, default=128, help="Frame width in pixels")
+    parser.add_argument("--frame-height", type=int, default=128, help="Frame height in pixels")
+    parser.add_argument("--preset", choices=sorted(PRESETS), default="bob", help="Built-in motion preset")
+    parser.add_argument(
+        "--offset",
+        type=parse_offset,
+        action="append",
+        default=[],
+        help="Custom X,Y pixel offset; repeat to override --preset",
+    )
+    parser.add_argument("--dry-run", action="store_true", help="Write metadata only; do not write the strip")
+    return parser.parse_args()
+
+
+def process(args: argparse.Namespace) -> dict[str, Any]:
+    if args.frame_width <= 0 or args.frame_height <= 0:
+        raise ValueError("--frame-width and --frame-height must be positive")
+    if not args.input.exists():
+        raise ValueError(f"input image missing: {args.input}")
+    if not args.input.is_file():
+        raise ValueError(f"input image is not a file: {args.input}")
+
+    from PIL import Image
+
+    offsets = args.offset or PRESETS[args.preset]
+    source = Image.open(args.input).convert("RGBA")
+    source.thumbnail((args.frame_width, args.frame_height), Image.Resampling.LANCZOS)
+    centered = Image.new("RGBA", (args.frame_width, args.frame_height), (0, 0, 0, 0))
+    centered.alpha_composite(source, ((args.frame_width - source.width) // 2, (args.frame_height - source.height) // 2))
+
+    output_size = [args.frame_width * len(offsets), args.frame_height]
+    if not args.dry_run:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        strip = Image.new("RGBA", tuple(output_size), (0, 0, 0, 0))
+        for index, (dx, dy) in enumerate(offsets):
+            frame = Image.new("RGBA", (args.frame_width, args.frame_height), (0, 0, 0, 0))
+            frame.alpha_composite(centered, (dx, dy))
+            strip.alpha_composite(frame, (index * args.frame_width, 0))
+        strip.save(args.output, format="PNG")
+
+    metadata = {
+        "dry_run": args.dry_run,
+        "input": str(args.input),
+        "output": str(args.output),
+        "preset": args.preset,
+        "offsets": [[x, y] for x, y in offsets],
+        "frame_count": len(offsets),
+        "frame_width": args.frame_width,
+        "frame_height": args.frame_height,
+        "output_size": output_size,
+        "manifest_frame": {"width": args.frame_width, "height": args.frame_height},
+    }
+    if args.metadata:
+        args.metadata.parent.mkdir(parents=True, exist_ok=True)
+        args.metadata.write_text(json.dumps(metadata, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return metadata
+
+
+def main() -> int:
+    try:
+        args = parse_args()
+        metadata = process(args)
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+    print(f"input: {metadata['input']}")
+    print(f"output: {metadata['output']}")
+    print(f"dry_run: {metadata['dry_run']}")
+    print(f"preset: {metadata['preset']}")
+    print(f"frame_count: {metadata['frame_count']}")
+    print(f"output_size: {metadata['output_size']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/pi-sprite-authoring/scripts/download-petdex-examples.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+
+function arg(name, fallback = "") {
+	const index = process.argv.indexOf(`--${name}`);
+	return index >= 0 ? (process.argv[index + 1] ?? fallback) : fallback;
+}
+
+const manifestUrl = arg(
+	"manifest",
+	process.env.PI_SPRITE_PETDEX_MANIFEST_URL || "https://petdex.crafter.run/api/manifest",
+);
+const out = arg("out", "examples/petdex-downloads");
+const query = arg("query", "").toLowerCase();
+const limit = Math.max(1, Math.min(50, Number.parseInt(arg("limit", "12"), 10) || 12));
+function safeSlug(value) {
+	const slug = String(value ?? "")
+		.trim()
+		.toLowerCase();
+	return /^[a-z0-9][a-z0-9-]{0,79}$/u.test(slug) ? slug : "";
+}
+
+const slugs = arg("slugs", "")
+	.split(",")
+	.map((slug) => safeSlug(slug))
+	.filter(Boolean);
+
+async function download(url) {
+	const res = await fetch(url, { headers: { accept: "*/*", "user-agent": "pi-sprite-authoring" } });
+	if (!res.ok) throw new Error(`download failed for ${url} (${res.status})`);
+	return Buffer.from(await res.arrayBuffer());
+}
+
+function spriteNameFromUrl(url) {
+	const ext = extname(new URL(url).pathname).toLowerCase();
+	return ext === ".png" ? "spritesheet.png" : "spritesheet.webp";
+}
+
+const manifestRes = await fetch(manifestUrl, {
+	headers: { accept: "application/json", "user-agent": "pi-sprite-authoring" },
+});
+if (!manifestRes.ok) throw new Error(`manifest fetch failed (${manifestRes.status})`);
+const manifest = await manifestRes.json();
+const pets = (Array.isArray(manifest.pets) ? manifest.pets : [])
+	.map((pet) => ({ ...pet, safeSlug: safeSlug(pet.slug) }))
+	.filter((pet) => pet.safeSlug && pet.displayName && pet.petJsonUrl && pet.spritesheetUrl)
+	.filter((pet) => !slugs.length || slugs.includes(pet.safeSlug))
+	.filter((pet) => !query || `${pet.safeSlug} ${pet.displayName} ${pet.kind ?? ""}`.toLowerCase().includes(query))
+	.slice(0, limit);
+
+mkdirSync(out, { recursive: true });
+const provenance = [
+	"# Petdex example downloads",
+	"",
+	`Downloaded from: ${manifestUrl}`,
+	`Downloaded at: ${new Date().toISOString()}`,
+	"",
+	"These files are local reference material. Do not commit or redistribute third-party sprite assets unless their licenses are verified.",
+	"",
+	"## Assets",
+];
+
+for (const pet of pets) {
+	const dir = join(out, pet.safeSlug);
+	mkdirSync(dir, { recursive: true });
+	const [petJsonBytes, spriteBytes] = await Promise.all([download(pet.petJsonUrl), download(pet.spritesheetUrl)]);
+	const spriteName = spriteNameFromUrl(pet.spritesheetUrl);
+	writeFileSync(join(dir, "pet.json"), petJsonBytes);
+	writeFileSync(join(dir, spriteName), spriteBytes);
+	writeFileSync(
+		join(dir, "PROVENANCE.md"),
+		`# ${pet.displayName}\n\n- slug: ${pet.safeSlug}\n- kind: ${pet.kind ?? "unknown"}\n- submittedBy: ${pet.submittedBy ?? "unknown"}\n- petJsonUrl: ${pet.petJsonUrl}\n- spritesheetUrl: ${pet.spritesheetUrl}\n\nLicense was not verified by this script. Use as temporary reference only unless separately cleared.\n`,
+	);
+	provenance.push(`- ${pet.safeSlug} — ${pet.displayName} (${pet.kind ?? "unknown"})`);
+}
+
+writeFileSync(join(out, "THIRD_PARTY_ASSETS.md"), `${provenance.join("\n")}\n`);
+console.log(`Downloaded ${pets.length} Petdex example(s) into ${out}`);