Release 1.3.0

The kit now teaches hot reload. blit386@1.4.0 (See the release notes) has been sitting on npm with the Vite plugin and the swap tiers, and this release is the scaffolder and kit finally catching up – new games get it for free, old ones get a polite migrate path, and nobody's assistant should invent an API that isn't there yet.

Hot reload

Gated on the engine the same way audio was: ship the engine first, then the kit that talks about it.

• New content/docs/hot-reload.md, plus updates to AGENTS.md, basics, and troubleshooting for the tiered swap model (prototype swap vs re-init vs full reload).
• New use-hot-reload and loading-screen game-author skills.
• Fresh scaffolds ship blit386() in vite.config and a commented onHotReload example in Catcher (JS and TS).
• blit386.engineRange (kit) and BLIT386_RANGE (scaffolder) move from ^1.3.0 to ^1.4.0 – again not cosmetic; blit doctor compares engineRange against an already-installed engine.
• Existing games: npx blit upgrade or npx blit migrate --write can wire the Vite plugin on a normal defineConfig. Fresh scaffolds already have it.

Agents and kit CLI

• Scaffold and blit agents sync / add share one adapter module (@blit386/kit/adapters).
• Claude now gets settings.json hooks so the guardrails roughly match what Cursor already had.
• Project blit386-docs MCP for Claude and Cursor; maintainer Cursor commands stay in parity with Claude skills.

Tooling

• Publishing stays manual-only (no CI publish, no NPM_TOKEN) – PUBLISHING.md is in the public repo and is the checklist.
• Lockstep bump via pnpm run bump -- <x.y.z> so the two packages stop drifting by accident.
• CI, Renovate, CodeRabbit, issue forms, and assorted preflight hygiene.

Existing games: run npx blit upgrade (or npx blit migrate) if you want the hot-reload Vite plugin. Docs alone sync with npx blit agents sync; the plugin change is opt-in on purpose.

Full Changelog: 1.2.1...1.3.0

Release 1.2.1

The kit now teaches audio. blit386@1.3.0 (see the release notes) shipped the audio subsystem on npm a few weeks ago; this release is the kit catching up to it, plus a stale engine-range bug fix and some tooling hygiene.

Audio

The kit ships its first audio content, gated on the engine release so nobody's assistant hallucinates an API that doesn't exist yet.

• New content/docs/audio.md covering AudioClip, BT.synthPreset, buses, and the audio-unlock rule. (#56)
• New play-a-sound and design-a-sound game-author skills. (#56)
• Audio rows added to AGENTS.md, content/rules/blit-api-names.md, and audio overlay flags documented in show-debug-overlay. (#56)
• Publish order was gated on blit386@1.3.0 actually being live on npm before any of this shipped — see CREATE_BLIT386_DESIGN.md section 0.

Fixes

• blit386.engineRange (kit package.json) and BLIT386_RANGE (scaffolder) bumped from ^1.2.0 to ^1.3.0. This one is not cosmetic: engineRange feeds blit doctor's compatibility check against an already-installed engine. Left at ^1.2.0, blit doctor would report a false "compatible" for a project still on blit386@1.2.0 after syncing in the new audio docs, even though BT.soundPlay doesn't exist there yet.
• blit doctor's kit-update message corrected and reconciled with the design doc. (#55)
• Scaffolded projects now use --ignore-workspace for their npm install step, so a scaffold created inside another pnpm/npm workspace installs correctly. (#57)
• CI's publish.yml trigger corrected to match this repo's no-v tag convention (1.2.1, not v1.2.1). (#54)
• Stale @blit386/kit naming cleaned up across docs and skills that still referenced the pre-rename package names. (#55)
• blit-api-names.md deprecations link updated to point at the docs site instead of a dead path. (#44)

Tooling

• biome.json migrated to the 2.5.2 schema (recommended: true to preset: "recommended"), including the scaffolded templates/base/biome.json.tmpl so newly generated games don't inherit the same stale-schema warning.
• CI quality checks parallelized, with the build step gated on the security audit passing first. (#45)
• New american-english-spelling rule formalizing the repo's existing American-English convention. (#51)
• New cbt-kit-audit skill for re-auditing shipped kit docs and skills against the current engine API. (#42)

Full Changelog: 1.2.0...1.2.1

Release 1.2.0

The packages are renamed. create-blit-tech is now create-blit386 on npm, @blit-tech/kit is @blit386/kit, and the blitTech config key becomes blit386 – which is what it should have been called from the start, honestly. The blit agents sync migration system rewrites old blit-tech imports automatically once you run npx blit migrate. If you're still on 1.1.0, blit upgrade pulls the renamed package and that's mostly the whole story.

API Changes

The scaffolder and kit ship under new npm identities this release.

• Breaking: The scaffolder package is renamed from create-blit-tech to create-blit386 on npm. Use npm create blit386@latest going forward. (#35)
• Breaking: The kit package is renamed from @blit-tech/kit to @blit386/kit. Update devDependencies in existing projects or let blit upgrade handle it. (#35)
• Breaking: The custom config key in packages/kit/package.json is renamed from blitTech to blit386 (shape unchanged; the nested engineRange field stays the same). (#35)
• blit upgrade now removes the legacy blit-tech package if installed, then installs blit386@latest. The upgrade path is automatic. (#35)
• Engine range pinned to ^1.2.0 in scaffolded package.json files. (#39)

Migration and Codemod

The blit migrate command can rewrite old import paths automatically.

• A new migration entry 2026-06-16-package-rename is registered, rewriting blit-tech to blit386 in import/require specifiers starting from since: '1.1.0' with safety: 'auto'. Run npx blit migrate after upgrading. (#35)
• The codemod engine gained importPath as a new RenameKind, matching only inside quoted import specifier strings (ESM from '...' and CJS require('...')). Partial/substring package-name collisions are guarded against. (#35)

CI and Tooling

CI workflows and agent skills updated to match the new package identities.

• The publish.yml workflow now reads version from packages/create-blit386/package.json, targets @blit386/kit and create-blit386 for npm view checks and publish steps. (#36)
• Claude and Cursor rules and skills (cbt-format, cbt-release, cbt-review, cbt-spellcheck, cbt-test) updated to reference create-blit386 and @blit386/kit throughout. (#36)
• biome.json, cspell.json, knip.json, and markdown-link-check.json updated for the new package and directory names. (#35)
• undici transitive dependency pinned to >=8.5.0 <9 via pnpm.overrides; minimum-release-age-exclude added to .npmrc so the patch applies immediately. (#36)

Full Changelog: 1.1.0...1.2.0

Release 1.1.0

Minor release of @blit-tech/kit and create-blit-tech. Everything merged since the 1.0.0 tag: API migration
codemods and a full set of game-author AI skills for scaffolded projects.

Published packages: @blit-tech/kit@1.1.0, create-blit-tech@1.1.0
Engine compatibility: kit blitTech.engineRange stays ^1.1.1; new games still pin blit-tech ^1.1.1.

---

Highlights

blit migrate — update old Blit-Tech names in your game

Turns the engine's deprecations table into something you can run locally:

• npx blit migrate — preview renames (no file changes)
• npx blit migrate --write — apply safe renames; warns and confirms when the project is not under git
• npx blit upgrade — after a real engine version change, offers to run the same codemods automatically

Renames are split into two buckets:

• Auto — safe to rewrite: BT.buttonDown → BT.isDown, overlayEnabled → isOverlayEnabled,
  SpriteSheet.isIndexized → isIndexed, and the rest of the 1.0 naming pass
• Review — reported with a suggested fix, never auto-rewritten: .equals() (check if it's Vector2i / Rect2i /
  Color32), .tick() on Timer, and bootstrap keys like canvasId → canvasID

The migrate AI skill ships into generated games (Claude + Cursor) so an assistant can resolve the review hits by
checking receiver types.

Game-author AI skills (18 total)

Every new scaffold gets a self-contained skill library under .claude/skills/ or .cursor/commands/ — no external demo
repo references:

Skill	What it teaches
structure-a-game	configure / init / update / render; engine renders, you write game logic
draw-shapes	pixels, lines, rects
add-sprite	indexed sprite sheets
add-text	system font + .btfont
use-palette	slots, Color32, HUD presets
animate-the-palette	cycle, fade, flash, swap
move-and-time	BT.deltaSeconds, BT.ticks, Timer
scroll-with-camera	BT.cameraSet, clamp
read-keyboard	hold vs edge, repeat
read-pointer	mouse / touch / pen
read-gamepad	players, sticks, dead zone
add-crt-effect	WebGPU post-process presets
save-a-screenshot	captureFrame / downloadFrame
show-debug-overlay	overlay flags and timing chart
share-the-game	build to dist/ and static hosting
run / fix / migrate	dev workflow helpers

Claude skills keep YAML frontmatter (name + description) for discovery; Cursor commands strip it (invoked by
filename).

Other fixes

• docs/palette.md: Color32.white is a property, not a call (removed incorrect () examples)
• npx blit doctor / npx blit run: verified on npm, pnpm, and yarn (2026-06-14)

---

Upgrade an existing game

npm update @blit-tech/kit blit-tech    # or pnpm / yarn equivalent
npx blit agents sync
npx blit migrate                       # preview first
npx blit migrate --write               # apply safe renames

Then resolve any review hits by hand (or ask your AI assistant — the migrate skill is built for this).

---

New project

npm create blit-tech@latest my-game
cd my-game
npm run dev
npx blit doctor

---

Full diff: 1.0.0...1.1.0

Release 1.0.0

First stable release of the Blit-Tech scaffolder and kit.

Highlights (since 0.1.0)

• blit agents lifecycle. Full sync write path, sync --check drift detection, sync --force, and the new
  blit agents add <claude|cursor> (atomic - never clobbers existing user files; writes .new copies and aborts on
  collision).
• Ownership model. .blit/manifest.json plus pristine .blit/base/ ancestors, real three-way merge for kit-owned
  files, and the clean-merge-is-not-drift fix so --check / doctor stop reporting settled files as drifted.
• TypeScript scaffolds. templates/ts/ and the --ts flag, same Catcher starter game, typed.
• Generated assistant configs. Claude (CLAUDE.md + .claude/) and Cursor (.cursor/) generated from the kit IR
  at scaffold time and refreshed by blit agents sync.
• blit doctor engine-range compatibility check; pointer/touch input in the Catcher paddle; Node-floor and
  non-interactive run guards; optional CI workflow template; git hooks; contributing guide.

Packaging metadata (this release)

• Bumped both published packages to 1.0.0 (major).
• Added repository (with monorepo directory), bugs, and homepage; switched author to object form with a
  profile URL; broadened npm keywords on both packages.
• Aligned the JS template vite floor with the TS template (^8.0.16).

Release 0.1.0

Initial release. Both packages published to npm for the first time.

create-blit-tech

npm create blit-tech@latest scaffolds a ready-to-run JavaScript game project in seconds.

Scaffold wizard

• Prompts for a game folder name (or accepts a positional argument).
• Language choice: JavaScript (ready) or TypeScript (shown as "coming soon").
• AI assistant choice: none, Claude Code, or Cursor (assistant-specific files shown as "coming soon"; a readable AGENTS.md ships regardless).
• Flags: --yes / -y to skip all prompts, --no-install to skip dependency install, --no-git to skip git init.

Generated project contents

• src/game.js - the Catcher starter game: a paddle, falling blocks, lives, score, and a game-over screen. Beginner-friendly comments explain every block and why it is written that way.
• index.html with a Vite dev server config.
• package.json pinning blit-tech ^1.1.1 and @blit-tech/kit (for the blit CLI).
• jsconfig.json with strict checking.
• .gitignore and .editorconfig.
• AGENTS.md and a docs/ folder copied from @blit-tech/kit content (single source of truth for AI and human guidance).
• A kid-friendly README.md with next-step commands.

Post-scaffold steps (automated when possible)

• Git init, initial add, and "Initial commit from create-blit-tech".
• Dependency install via the detected package manager (npm / pnpm / yarn / bun). Falls back gracefully with a manual instruction if install fails.
• Prints the exact commands to get started.

Template system

• {{placeholder}} tokens in template files are replaced at scaffold time (project name, package name, engine version range, package manager commands).
• Unknown tokens are left visible in the output so typos are caught immediately.
• gitignore is renamed to .gitignore; .tmpl extensions are stripped.

@blit-tech/kit

@blit-tech/kit ships the blit project CLI and the canonical guidance files that every scaffolded game receives.

blit CLI commands

• blit run - starts the Vite dev server (vite) so the game opens in the browser.
• blit doctor - checks Node.js version (minimum 22.18.0), detects the game root, reports git presence, reports whether blit-tech is installed, and nudges to run blit upgrade for updates.
• blit upgrade - updates blit-tech to latest via the detected package manager. Warns before upgrading if the project has no git history. Detects major-version changes and links to the deprecations list.
• blit agents - stub command; informs that assistant-specific file generation arrives in a later version.
• blit help - prints usage.

Package manager detection

Detects npm, pnpm, yarn, and bun from lock files and packageManager fields; falls back to npm. Used by both the scaffolder and the blit upgrade command.

Kit content (shipped into every game)

• AGENTS.md - concise rules and doc routing for AI coding assistants working in a generated game.
• docs/basics.md - configure, game loop, timing getters, bootstrap flow.
• docs/drawing.md - BT.clear, primitives, text, and sprite APIs.
• docs/getting-started.md - first steps for absolute beginners.
• docs/input.md - keyboard, pointer, and gamepad input.
• docs/palette.md - palette slots, Color32, named colors.

Tech stack

• TypeScript 5.9 strict mode throughout.
• Built with tsup to ESM targeting Node 22.
• Formatted by Biome (TS/JS/JSON) and Prettier (Markdown/YAML).
• ISC license. pnpm monorepo.

Known limitations in this release

• JavaScript templates only. TypeScript templates are planned for a later version.
• No per-agent config files generated yet (Claude Code, Cursor). Both are shown as "coming soon" in the wizard; the shared AGENTS.md covers AI-assisted development in the meantime.
• blit agents is a no-op stub.