v2.3.0 — Telemetry, Funnel Fixes & Foundation Hardening

Funnel telemetry to find drop-off, friction fixes in the question flow, security/CSP modernization, and a major dep refresh (TypeScript 6, Astro 6.2).

What's Changed

• refactor(types): centralize dataSource resolution via discriminated union (#14)
• feat(foundation): rate-limit share, modernize CSP, SHA-pin workflows (#15)
• feat(telemetry): fire question_arrived + question_abandoned events (#16)
• fix(create): query progress bar by class (#17)
• feat(ux): funnel fixes — Q2 optional, Enter advances, Back hides on Q1 (#18)
• chore(ux): footer on /create, JSON-LD on home, rel=noopener on GitHub link (#19)

Dependencies

• chore(deps): bump cloudflare/wrangler-action 3.14.1 → 3.15.0 (#10)
• chore(deps): bump actions/setup-node (#11)
• chore(deps): bump actions/checkout (#12)
• chore(deps): TypeScript 5.9.3 → 6.0.3, Astro 6.0.5 → 6.2.2, wrangler 4.74.0 → 4.87.0, prettier, vitest, +3 patch bumps (#13)

Full Changelog: v2.2.1...v2.3.0

v2.2.1 — Dependency Updates

Dependency Updates

Upgrades 6 dependencies via Dependabot:

Package	From	To
astro	5.18.0	6.0.5
@astrojs/sitemap	3.7.0	3.7.1
@astrojs/check	0.9.6	0.9.8
@cloudflare/workers-types	4.20260305.0	4.20260316.1
vitest	4.0.18	4.1.0
wrangler	4.69.0	4.74.0

Astro 6 major bump verified — no breaking changes affect this project (static output, no content collections, no getStaticPaths). 186 tests passing.

v2.2.0 — Usability Audit Fixes

What's New

Addresses findings from a comprehensive usability audit (2026-03-28).

Accessibility

• WCAG AA contrast — --color-text-muted darkened to meet 4.5:1 ratio (light and dark mode)
• Progressbar — added aria-label="Question progress"
• Dynamic next-hint — screen reader hint varies by question type (text input vs pick-one)
• Optional field indicators — (optional) tag on non-required form fields

UX Improvements

• 3 questions now skippable — usage-frequency, device-target, page-count (reduces minimum from 11 → 8 questions)
• Question counter — shows "Question 3 of ~11" with "Almost done!" at 75%+
• Share button — loading state ("Creating link…") with double-click prevention
• 404 page — site header + "Create your spec" secondary CTA
• CTA copy — "Answer a few questions, get a build-ready spec."

Trust & Security

• Privacy page — new /privacy page explaining data practices
• Security headers — HSTS, X-Frame-Options: DENY, Permissions-Policy
• Sitemap — /admin excluded
• llms.txt — AI discoverability file

Tests

• 182 → 186 tests (skip defaults, optional question invariants)

v2.1.1 — Fix empty scroll space on spec page

Fix

• Eliminated ~6500px of invisible scroll space below the feedback section
• Root cause: hidden clipboard fallback <pre> element and unconstrained spec body expanding document height
• Clipboard fallback now uses position: fixed + clip: rect(0,0,0,0) — no scroll contribution
• Tightened section padding for feedback and start-over sections

v2.1.0 — KV-backed share links & spec scroll

What's New

KV-Backed Share Links

Share links now use Worker KV storage instead of client-side URL encoding. URLs are short (gist.1mb.dev/spec#aBcDeF) with 6-char alphanumeric IDs and 90-day TTL.

• POST /api/share — store answers, get short ID
• GET /api/share/:id — retrieve answers
• 4KB payload limit, JSON validation, ID format validation

Spec Scroll Container

Spec preview is now wrapped in a 60vh scrollable container with a bottom fade gradient that disappears when you reach the end. No more infinitely long page.

Accessibility

• Scroll container: role="region", aria-label, tabindex="0", focus-visible outline
• Action buttons: aria-label descriptions, role="group" on button bar

Resilience Fixes

• 5-second fetch timeout on share link load (prevents blank page if worker is down)
• Fixed 3 analytics events silently rejected by worker (shared_spec_viewed, spec_and_prompt_copied, spec_shared added to ALLOWED_EVENTS)
• Extracted TTL_90_DAYS constant (was duplicated magic number)
• Wrapped sessionStorage.removeItem in try-catch per project convention

Stats

• 182 tests (was 174), all passing
• 3 files changed, +254/-45 lines
• Lint clean, build clean

v2.0.0 — Specs That Work, Flow That Converts

What's New

v2.0 addresses two fundamental problems: specs that were wrong in specific ways (Linus review, 6.5/10) and 74% question-flow abandonment (Maya review, prod data).

Spec Correctness (Linus P0s)

• Worker proxy is conditional, not prescribed — AI assistant decides based on API auth requirements
• Error handling is context-aware per data source (API failures vs form validation vs storage)
• npm run dev only for standard/full tier; minimal gets npx serve .
• CSP rewritten: connect-src branches correctly, style-src 'self' (no unsafe-inline), script-src explicit

Spec Completeness (Linus P1s)

• File/folder structure table for all tiers
• Worker API Design section with route table
• Cron is mechanism-agnostic (Cloudflare Cron Trigger or GitHub Actions — AI decides)
• script-src added to CSP

Spec Cleanup (Linus P2s)

• Removed Development Stages (Implementation Order is the single source of truth)
• Mock data uses real values, TypeScript interfaces for standard/full
• Conditional sections: humans.txt removed, Locale conditional, .gitignore tier-aware
• Audience drives accessibility and design guidance

Question Flow UX (Maya P0s)

• Counter shows "Question 3" (no "of N" — total no longer increases)
• Progress bar never visually decreases
• headlineValue optional for new-builders with helper text
• Back button on Q1 returns to persona selection
• Save signal visible: "✓ Progress saved"

Spec Page & Landing (Maya P1s)

• Spec preview uncapped (no 600px scroll prison)
• "Ready to build?" with prompt elevated, combined "Copy spec + prompt" button
• Copy is primary CTA, Download is secondary
• Plain-language stack confirmation for new-builders
• New landing page subtitle

New: Shareable Spec URLs

• Share button compresses answers to URL fragment (CompressionStream + base64url)
• Recipients see full spec immediately — no account, no backend
• Feedback hidden for shared specs; analytics tracked

Footer

• "Generated by Gist — create your own build-ready spec" (CTA, not attribution)

Infrastructure

• Dependabot: actions/checkout v6, npm deps updated
• Worker: rate limiting, token exposure protection, unreachable code removed
• Tests: 174 total (was 148), all passing
• Build: 5 pages, 14.59 KB gzipped spec page

---

Full changelog: v1.3.1...v2.0.0

v1.3.1 - Localhost-First Development

What's New

Specs now guide AI assistants to build locally-testable apps through three major improvements:

1. Development Stages (All Specs)

Progressive 3-stage pattern for development:

• Stage 1: Local — Mock data only, build UI immediately on localhost
• Stage 2: Integration — Wire real APIs after UI is approved
• Stage 3: Polish — Analytics, caching, advanced features (optional)

2. Mock Data Templates (External-Data Specs)

Context-aware guides for common API types:

• Weather APIs — location, temp, condition, forecast fields
• Stock APIs — ticker, price, change, change_percent fields
• News APIs — title, description, source, publishedAt fields
• Generic APIs — Field names, types, and sample values

3. Local Development Checklist (Data-Dependent Specs)

Pre-flight validation before external integration:

• App builds and runs locally with mock data
• All UX states testable (loading, error, success, empty)
• Design approved by user before wiring real API
• Data structure verified against real API

Analytics Enhancement (Bonus)

• Worker generates composite persona:tier KV keys for segmentation analysis
• Dashboard adds "Persona × Tier matrix" panel showing user combinations

Why This Matters

The Problem: When generated specs are handed to Claude for building, they might guide implementation with hard external dependencies from day 1. This blocks local testing—developers can't run the app without setting up APIs first.

The Solution: Specs now explicitly signal the "mock-first, integrate-later" pattern:

1. Build with mock data first
2. Get user approval on design with mock data
3. Then integrate real APIs

Result: AI-assisted development becomes smoother, more testable, and follows best practices for progressive development.

Quality Metrics

• ✅ 139 tests passing (128 → 139, +11 new)
• ✅ Linting clean
• ✅ Build successful
• ✅ No regressions
• ✅ Service worker cache bumped to gist-v8

Full Changelog

See CHANGELOG.md for complete list of changes.

v1.3.0 — Spec Generator Quality Pass

What's Changed

The spec is the product — this release makes generated specs correct, coherent, and actionable across all app types.

Highlights

• User-content paths fixed — simple-form and user-saves-data apps now get correct Data Flows, UX States, Implementation Order steps, CSP, and Budget Math
• Agentic execution quality — verification checkpoints, agent guidance in Summary, Pre-Ship Checklist reference in Polish step
• Section coherence — reordered for top-to-bottom readability, deduplicated Summary/Idea, actionable Post-Deployment checklist
• New-builder persona — subtle, positive hints reassuring non-technical users that the AI assistant handles technical details
• Architecture accuracy — health endpoint scoped to Worker apps, tinyrouter scoped to minimal tier

Review Status

• Linus (technical authority): Blessed — all 5 spec variants technically sound
• Maya (product strategy): Blessed — after persona fix

Stats

Metric	Before	After
Tests	100	119
Issues fixed	—	20
Spec variants validated	0	5

Full Changelog: v1.2.1...v1.3.0

v1.2.1 — Calm design polish

Summary

UX polish pass applying calm design principles — reduce unnecessary delays, surface silent failures, improve accessibility.

Fixed

• UX: reduced spec-navigation delay from 1200ms to 500ms for natural pacing
• UX: saveProgress() failures now surface an inline note instead of failing silently
• UX: downloadSpec() failures show "Download failed — try again" on button for 3 seconds
• A11y: disabled Next button now has aria-describedby hint ("Select an option to continue")
• A11y: empty admin token field shows aria-invalid outline with clear-on-input
• Admin: loading spinner CSS no longer overrides hidden attribute
• Service worker: bumped cache version to gist-v6

v1.2.0 — UX Polish + Dashboard Redesign

What's New

Admin Dashboard Redesign

Raw tables replaced with pre-computed signal panels:

• Funnel: horizontal bars (Visited → Persona → Generated → Downloaded) with drop-off insight
• Tier split: proportional bars + persona distribution side-by-side
• Satisfaction: headline percentage + conic-gradient donut ring + breakdown bars
• After download: action bars (downloaded/copied/prompt copied) with top-action insight
• Period selector: 24h / 7d / 30d pill buttons filter data client-side

Question Flow

• Removed auto-advance — users now click Next manually (less jarring)
• Added new-builder persona overlays for Q6a, Q10, Q8a (jargon-free wording)

Worker

• page_viewed tracking event for funnel analysis
• 90-day TTL on all KV writes (auto-cleanup of stale data)

Fixes

• Admin: loading guard prevents double-submit
• Admin: button state properly reset on success and retry
• Admin: period-aware empty state messages

Stats

• 100 tests passing (93 → 100)
• 0 lint errors, 5 pages build
• SW cache bumped to gist-v5