# Changelog

All notable changes to `@zyvra-labs/pi-stitch-tools` are documented here.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.4.1] — 2026-06-11

### Fixed

- **Extension startup crash**: replaced the immutable top-level `piContext` binding with shared mutable extension state, fixing `Assignment to constant variable.` during `session_start`.
- **Status bar state access**: `refreshStatusBar()` now reads `piContext`, `stitchTools`, and `skillRegistry` from shared extension state instead of relying on reassigned outer bindings.

### Tests

- Added a regression test that verifies the extension source uses mutable shared state for session context and status refresh.

## [0.4.0] — 2026-06-11

### Added

- **Skill categories**: skills are now typed as `foundation` (always on), `domain` (opt-in), `style` (opt-in), or `workflow`. Foundation skills (generate-screen, design-system) stay on by default. Domain (mobile-app, dashboard, ecommerce) and style skills are opt-in to keep prompt enhancement focused.
- **Four new style skills**: `style-glassmorphism`, `style-brutalist`, `style-editorial`, `style-minimal-swiss`. Each ships production-grade visual direction in ~600 chars of prompt text.
- **Smart activation cap**: at most 3 skills are injected per prompt (1 foundation + up to 2 matched). Style category takes priority over domain when both match, preventing prompt bloat.
- **Prompt deduplication**: when two skills share overlapping guidance (e.g. spacing/contrast rules in mobile + dashboard), repeated lines are collapsed to the first occurrence. Keeps the injected prompt tight.
- **Skill presets**: YAML files in `skills/presets/` define named groups. `/stitch-skill preset list` and `/stitch-skill preset apply <name>` enable or disable a coordinated set. Bundled presets: `mobile-saas`, `ecommerce`, `admin-panel`, `brand-landing`.
- **New commands**: `/stitch-skill preview <name>`, `/stitch-skill recommend`, `/stitch-skill preset list`, `/stitch-skill preset apply <name>`, `/stitch-setup`, `/stitch-write-key <key>`, and `/stitch-reload`.
- **Skills applied banner**: generation responses and `/stitch-new-screen` now report which skills fired, e.g. `✨ Skills applied: generate-screen, ecommerce, style-glassmorphism`.
- **Minimal dynamic status bar**: compact palette-first status strings like `🎨 stitch: 14·2`, `🎨⚡ stitch: 14·2`, `🎨⏳ stitch: 14·2 4m`, and `⚠️ stitch: 14·2`.
- **Proactive API key onboarding**: missing-key installs now surface `🎨 stitch: ⚠ setup needed` on session start, with guided setup and validation commands.
- **Improved diagnostics**: `/stitch-status` now explains exactly where the package looked for the key and gives contextual hints for invalid credentials, permission problems, and network failures.
- **Local package icon support**: the Stitch favicon is now shipped as `assets/favicon.png` and exposed via `pi.icon`.
- **`composesWith` and `priority` fields** in skill YAML for richer composition and tie-breaking.

### Changed

- Domain skills (`mobile-app`, `dashboard`, `ecommerce`) now default to `enabledByDefault: false`. Users opt in via `/stitch-skill enable`, presets, or matching triggers.
- `/stitch-skill list` groups skills by category with category icons, trigger tags, and a presets summary.
- `/stitch-skill stats` returns per-category counts and preset count.
- The package tarball now includes `assets/` so the shipped `pi.icon` path resolves correctly after install.

### Tests

- 87 unit tests cover category validation, opt-in defaults, smart activation cap, prompt deduplication, presets, preview, recommend, style skill loading, dynamic status states, diagnostics, and setup command surface.
- Existing tests for YAML parsing, key sanitization, retry logic, and prompt enhancement are unchanged.

## [0.3.5] — 2026-05-31

### Added

- **Dynamic Stitch skill registry** for runtime skill enable/disable, trigger matching, usage stats, and production UI prompt enhancement.
- **Production-grade default skill definitions** for base screen generation, design systems, mobile apps, dashboards, and e-commerce flows.
- **Prompt enhancement pipeline** for `generate_screen_from_text`, `edit_screens`, and `generate_variants`, preserving the original user request while prepending professional UI quality criteria.
- **Generation cooldown and usage tracking** to reduce duplicate screens after timeouts and improve `/stitch-status` visibility.

### Fixed

- **Nested object serialization workaround** for Stitch parameters that may arrive stringified from Pi tool calls.
- **Skill YAML parsing** now preserves block scalar prompts and nested config/list values instead of dropping prompt content.

### Tests

- Added coverage for skill YAML parsing, bundled skill validation, prompt enhancement, trigger matching, and nested object serialization handling.

## [0.3.4] — 2026-05-28

### Fixed

- **Timeout de 30s era insuficiente** para generación de screens. Las tools de generación (`generate_screen_from_text`, `edit_screens`, `generate_variants`, `create_design_system_from_design_md`) ahora tienen 180s de timeout. Las tools rápidas (`list_projects`, `get_screen`, etc.) mantienen 30s.
- **Retry en timeout empeoraba las cosas**: las gen tools ya no retryan en timeout (respeta el spec de Stitch "DO NOT RETRY"). Pero siguen retryando en errores de red transitorios (500, network blip).
- **Mensajes de error genéricos**: ahora detectan cuándo el timeout es por el parámetro `designSystem` y sugieren el workaround (generar sin design system → aplicar después).
- **`apply_design_system`** removido de la lista de tools lentas — es una operación rápida.

### Added

- **Skill `stitch-generate-screen`**: documentación del approach en dos pasos como método recomendado, más sección "Known Issues".
- **Hallazgo documentado**: `deviceType: "AGNOSTIC"` es más confiable que `"DESKTOP"` cuando Stitch está bajo carga.

## [0.3.0] — 2026-05-27

### Added

- **Retry logic** in `stitchRequest` — up to 3 retries with exponential backoff and jitter (±25%) on network errors, 5xx responses, and 429 rate limits.
- **Convenience commands:**
  - `/stitch-projects` — list all Stitch projects.
  - `/stitch-new-screen <projectId> <prompt>` — generate a screen from a text description.
  - `/stitch-theme <projectId>` — list design systems for a project.
- **Skills** (4 AI-guided workflows):
  - `stitch-new-project` — create and configure a new Stitch project.
  - `stitch-generate-screen` — generate UI screens from natural language.
  - `stitch-design-system` — create, update, and apply design systems.
  - `stitch-iterate` — edit screens, generate variants, and refine designs.
- **Skill registry** (`.atl/skill-registry.md`) for automatic skill-to-trigger matching.
- **Package image** (`screenshot.png`) displayed on the pi platform.
- **`.gitignore`** entries for `.pi/` (personal config) and `.atl/*` (runtime cache).

## [0.2.1] — 2026-05-27

### Fixed

- API key sanitization now strips BOM (`\uFEFF`, `\uFFFE`), null bytes (`\u0000`), and zero-width spaces — preventing cryptic auth failures from invisible characters in key strings.

## [0.2.0] — 2026-05-27

### Added

- Initial release. Dynamic registration of all Google Stitch MCP tools under the `stitch_` prefix.
- Multi-source API key resolution: environment variables, `~/.pi/stitch-api-key` file, and legacy `mcp.json` fallback.
- `/stitch-status` command to verify tool availability.
- Session status bar indicator showing loaded tool count.

[0.4.1]: https://github.com/zyvralabs/pi-stitch-tools/compare/v0.4.0...v0.4.1
[0.4.0]: https://github.com/zyvralabs/pi-stitch-tools/compare/v0.3.5...v0.4.0
[0.3.5]: https://github.com/zyvralabs/pi-stitch-tools/compare/v0.3.4...v0.3.5
[0.3.4]: https://github.com/zyvralabs/pi-stitch-tools/compare/v0.3.0...v0.3.4
[0.3.0]: https://github.com/zyvralabs/pi-stitch-tools/compare/v0.2.1...v0.3.0
[0.2.1]: https://github.com/zyvralabs/pi-stitch-tools/compare/v0.2.0...v0.2.1
[0.2.0]: https://github.com/zyvralabs/pi-stitch-tools/releases/tag/v0.2.0