feat: per-package per-version changelog + /changelog page + auto-enforce on version bumps (#49)

* feat(changelog): per-package per-version changelog + backfill from git

Introduce a changelog/ directory at the repo root with one md file
per (package, version) tuple:

  changelog/
    README.md               architecture + conventions
    core/0.6.0.md           one file per release
    server/0.7.1.md
    cli/0.7.0.md
    ts-plugin/0.4.0.md
    ui/0.2.0.md
    …

The shape (per-package per-version, not per-commit) matches the way
we publish: every change of a packages/<pkg>/package.json version
field becomes a release entry. Each entry frontmatters package,
version, date, commit_count; the body groups qualifying commits
(feat / fix / breaking / perf) under Breaking / Features /
Performance / Fixes headings with PR links and commit SHAs.

scripts/backfill-changelog.js walks every packages/<pkg>/package.json
in git history, finds the commits that changed the version field,
and writes <pkg>/<version>.md for any (package, version) tuple that
does not yet have an entry. Existing files are left alone so
hand-curation survives re-runs.

Backfilled 43 files across the 5 packages from project inception
through 0.6.0 (core), 0.7.1 (server), 0.7.0 (cli), 0.4.0 (ts-plugin),
and 0.2.0 (ui).

* feat(website): /changelog page + Changelog nav link, responsive nav

Add website/app/changelog/page.ts that reads changelog/<pkg>/*.md
at SSR time, parses YAML-ish frontmatter and the minimal markdown
shape the backfill generator emits (h1, h2, bulleted lists, links,
inline code, bold), sorts entries by date desc, and renders one
card per release with a package-coloured badge, version, date, and
commit count.

Add the Changelog link to the layout nav. The header now uses
flex-wrap with gap-y-3 and the nav itself uses flex-wrap with
gap-x-3 sm:gap-x-4 + gap-y-2 so the now-six chrome elements
(Docs, UI, Changelog, Blog Demo, GitHub, theme-toggle) wrap into a
second row on narrow viewports instead of overflowing.

Verified locally: GET /changelog returns 200 with 156 KB of
rendered HTML containing every backfilled version across all five
packages.

* feat(changelog): auto-enforce changelog when a package version bumps

Add the "version bump triggers changelog" rule to the framework
AGENTS.md and back it with two gates:

1. .hooks/pre-commit refuses any commit whose staged diff bumps a
   packages/<pkg>/package.json version field without a matching
   changelog/<pkg>/<version>.md file. Prints the exact command the
   author needs (node scripts/backfill-changelog.js && git add
   changelog/).

2. .claude/hooks/changelog-nudge.sh is a PreToolUse hook that fires
   on Bash tool calls whose command matches git commit. It runs the
   same check and emits a permissionDecision: deny JSON payload, so
   Claude Code refuses the commit before it leaves the agent's
   shell. Wired into .claude/settings.json.

Both hooks are bypassable with --no-verify for emergencies. The AI
agent rule in AGENTS.md instructs agents to run the generator in
the same commit as the version bump, review the generated file,
and edit it in place for clarity before pushing.

* fix(hooks): correct off-by-one in awk slice that picked up trailing slash in pkg name

* feat(website): mobile hamburger menu using native <details>/<summary>

The previous flex-wrap nav let the items wrap below the logo on
narrow viewports, but on iPhone XR (414px) the 5 links + theme
toggle still felt congested. Replace it with a real mobile menu.

Below md (768px): the logo, theme-toggle, and a hamburger button
sit on one row; the hamburger is a native <details>/<summary> that
pops the same 5 links into a dropdown panel. At md and up: hide the
mobile cluster, show the inline nav as before. CSS strips the
default disclosure triangle and swaps the hamburger / close icons
via .mobile-menu[open].

Progressive enhancement: native <details> works without JS, so the
menu opens / closes on every viewport even when scripts have not
yet hydrated.

* fix(website): close mobile menu when a link inside it is clicked

Native <details> stays open on inner-anchor activation, so tapping
Changelog (or any other link) on mobile kept the panel visible.
Add a delegated click listener that strips the open attribute from
the parent <details> when any link inside .mobile-menu is activated.
Covers both regular target=_blank links and the same-origin client-
router-intercepted ones.

* feat(website,blog,ui): unify mobile-menu pattern across the three apps

webjs.dev, example-blog, and ui.webjs.dev now share the same mobile
header layout: hamburger LEFT, theme-toggle RIGHT, with a native
<details>/<summary> dropdown panel anchored to the hamburger.

- webjs website: swap the order so the hamburger sits LEFT of the
  theme-toggle (was the reverse).
- example blog: drop the old fixed-drawer + body[data-menu-open]
  pattern in favour of the dropdown. Removes ~30 lines of CSS and
  matches the rest of the chrome surfaces. The mobile cluster is
  sm:hidden because the blog's existing inline nav is sm:flex.
- ui.webjs.dev: introduce the same dropdown pattern from scratch.
  The "Webjs" cross-link, previously hidden on small screens via
  hidden sm:inline, now lives in the dropdown panel where it's
  reachable on phones.

Docs site keeps its existing left-rail-drawer pattern (intentionally
untouched, since the docs UI needs a full sidebar, not a dropdown).

Same delegated click handler in every layout: any anchor activation
inside .mobile-menu strips the open attribute on the parent
<details>, so the panel auto-closes on navigation.

* fix(website,blog,ui): close mobile menu on outside click too

Tapping outside the open dropdown should dismiss it on a phone;
previously only the close icon (the toggled summary) closed it,
which felt off because the user has nothing visually grabbing
their attention to that one tap target.

Extend the existing delegated click handler in all three layouts
to walk `.mobile-menu[open]` and strip the open attribute on any
that don't contain the click target. The link-click branch is
unchanged: links inside the panel still close the panel directly.

Docs site keeps its own drawer pattern; this change does not touch
it.

Author: vivek7405

.claude/hooks/changelog-nudge.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+#
+# Claude Code PreToolUse hook.
+#
+# Catches the case where the agent is ABOUT to commit a change that
+# bumps a packages/<pkg>/package.json version but has not also
+# generated a matching changelog/<pkg>/<version>.md file. Fires on
+# Bash tool calls whose command starts with `git commit`.
+#
+# Hard block: writes a JSON hookSpecificOutput with
+# "permissionDecision": "deny" so the tool call is refused and the
+# agent reads the included reason. The agent should then run:
+#
+#   node scripts/backfill-changelog.js && git add changelog/
+#
+# and retry the commit.
+#
+# Skipped outside a git work tree and when there are no staged
+# version bumps.
+
+set -e
+
+# Read the hook payload from stdin so we can inspect the command
+# the model is about to run.
+INPUT=$(cat)
+
+# Only act on Bash tool calls whose command is `git commit ...`.
+COMMAND=$(printf '%s' "$INPUT" | grep -oE '"command"\s*:\s*"[^"]+"' | head -1 | sed 's/.*: *"\(.*\)".*/\1/')
+case "$COMMAND" in
+  *git*commit*) ;;
+  *) exit 0 ;;
+esac
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+STAGED_PKG_BUMPS=$(git diff --cached --unified=0 -- 'packages/*/package.json' 2>/dev/null \
+  | awk '
+      /^diff --git/ { match($0, /packages\/[^\/]+\/package.json/); pkg = substr($0, RSTART+9, RLENGTH-22); next }
+      pkg && /^\+\s*"version":\s*"[^"]+"/ {
+        match($0, /"[0-9]+\.[0-9]+\.[0-9]+[^"]*"/); v = substr($0, RSTART+1, RLENGTH-2);
+        print pkg "@" v
+      }')
+
+if [ -z "$STAGED_PKG_BUMPS" ]; then
+  exit 0
+fi
+
+MISSING=""
+for bump in $STAGED_PKG_BUMPS; do
+  pkg="${bump%@*}"; ver="${bump#*@}"
+  if [ ! -f "changelog/$pkg/$ver.md" ]; then
+    MISSING="$MISSING changelog/$pkg/$ver.md"
+  fi
+done
+
+if [ -z "$MISSING" ]; then
+  exit 0
+fi
+
+# Emit a JSON denial so Claude Code refuses this tool call and
+# surfaces the reason to the agent.
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "[changelog-nudge] You are committing a packages/<pkg>/package.json version bump but the matching changelog file(s) are missing:$MISSING\n\nRun: node scripts/backfill-changelog.js && git add changelog/\nThen retry the commit. To bypass (rare; emergencies only): git commit --no-verify"
+  }
+}
+EOF
+exit 0

.claude/settings.json

@@ -9,6 +9,15 @@
             "command": ".claude/hooks/block-prose-punctuation.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/changelog-nudge.sh"
+          }
+        ]
       }
     ],
     "PostToolUse": [

.hooks/pre-commit

@@ -32,4 +32,41 @@ if ! npm test --silent; then
   exit 1
 fi
 
+# Gate 3: when a packages/<pkg>/package.json version bumped, require
+# a matching changelog/<pkg>/<version>.md to land in the same commit.
+# The "diff --cached" check pulls the new version line from the
+# staged package.json; the directory existence test catches the
+# matching changelog entry. Re-runs `scripts/backfill-changelog.js`
+# so an author who forgets only loses time, not the commit.
+STAGED_PKG_BUMPS=$(git diff --cached --unified=0 -- 'packages/*/package.json' 2>/dev/null \
+  | awk '
+      /^diff --git/ { match($0, /packages\/[^\/]+\/package.json/); pkg = substr($0, RSTART+9, RLENGTH-22); next }
+      pkg && /^\+\s*"version":\s*"[^"]+"/ {
+        match($0, /"[0-9]+\.[0-9]+\.[0-9]+[^"]*"/); v = substr($0, RSTART+1, RLENGTH-2);
+        print pkg "@" v
+      }')
+
+if [ -n "$STAGED_PKG_BUMPS" ]; then
+  MISSING=""
+  for bump in $STAGED_PKG_BUMPS; do
+    pkg="${bump%@*}"; ver="${bump#*@}"
+    if [ ! -f "changelog/$pkg/$ver.md" ]; then
+      MISSING="$MISSING\n  - changelog/$pkg/$ver.md (for @webjskit/$pkg $ver)"
+    fi
+  done
+  if [ -n "$MISSING" ]; then
+    echo ""
+    echo "ERROR: detected version bumps in staged changes but matching changelog files are missing:"
+    echo -e "$MISSING"
+    echo ""
+    echo "Run:"
+    echo "  node scripts/backfill-changelog.js"
+    echo "  git add changelog/"
+    echo ""
+    echo "Then re-commit. To bypass (emergencies only): git commit --no-verify"
+    echo ""
+    exit 1
+  fi
+fi
+
 exit 0

AGENTS.md

@@ -97,6 +97,19 @@ When editing the framework monorepo (this repo, not a scaffolded app): **`packag
 
 See `agent-docs/framework-dev.md` for monorepo commands, workspace layout, reference codebases, and per-feature update checklists.
 
+### Changelog: per-package, per-version, auto-generated
+
+webjs ships per-package per-version changelogs under `changelog/<pkg>/<version>.md`. The model: **a version bump is the trigger**. When any commit on `main` changes the `version` field in `packages/<pkg>/package.json`, the scripts/backfill-changelog.js generator emits a new `changelog/<pkg>/<version>.md` summarising every conventional-commit (`feat:` / `fix:` / `breaking:` / `perf:`) that landed in that package since the prior bump. The website renders the union of all packages' files at `/changelog`.
+
+**Mandatory rule for AI agents working in this monorepo:**
+
+1. When you bump a `packages/<pkg>/package.json` `version`, you MUST run `node scripts/backfill-changelog.js` in the same commit (or the immediately following one), so the new `changelog/<pkg>/<version>.md` lands together with the bump.
+2. Review the generated file. The script's body excerpts are the first lines of each commit message; if any are unclear, **edit the file in place** to add migration notes (especially for `breaking` entries) before committing.
+3. Subsequent re-runs are safe: the script never overwrites an existing entry, so your hand-edits survive.
+4. Never edit `changelog/<pkg>/<version>.md` for a version that has already been published. Edit `changelog/<pkg>/<next>.md` instead.
+
+The `.hooks/pre-commit` git hook (and the Claude Code `PreToolUse` hook `.claude/hooks/changelog-nudge.sh`) catches version bumps that lack a matching changelog file and refuses the commit until both land together.
+
 ---
 
 ## What webjs is

changelog/README.md

@@ -0,0 +1,128 @@
+# Changelog
+
+webjs ships **per-package, per-version** changelog files.
+
+```
+changelog/
+  README.md                this file
+  core/
+    0.6.0.md
+    0.5.0.md
+    …
+  server/
+    0.7.1.md
+    …
+  cli/
+    0.7.0.md
+    …
+  ts-plugin/
+    0.4.0.md
+    …
+  ui/
+    0.2.0.md
+    …
+```
+
+The website (`website/app/changelog/page.ts`) reads every
+`<pkg>/<version>.md` at SSR time, sorts by date descending, and
+renders the unified release feed.
+
+## How a release entry gets created
+
+The model is "**a version bump produces a changelog file**". When a
+package's `package.json` `version` field changes in a commit, the
+entry script:
+
+1. Identifies the prior version of the same package on `main`.
+2. Walks the commits between the prior version's bump and the new
+   bump that touched files under `packages/<pkg>/`.
+3. Filters to conventional-commit prefixes that matter to users:
+   `feat:`, `fix:`, `breaking:`, `perf:`.
+4. Groups them under `Breaking` / `Features` / `Performance` /
+   `Fixes` and writes a `<version>.md` file with frontmatter
+   (`package`, `version`, `date`, `commit_count`) plus a bulleted
+   list of changes (PR link + commit SHA + body excerpt).
+
+`chore:`, `refactor:`, `test:`, `docs:`, `style:`, `build:`, `ci:`
+commits never appear in the changelog: those changes don't change the
+package's user-facing contract.
+
+## Entry format
+
+```markdown
+---
+package: "@webjskit/core"
+version: 0.6.0
+date: 2026-05-21
+commit_count: 4
+---
+
+# @webjskit/core 0.6.0
+
+## Breaking
+
+- **Title of the change** ([#NN](https://github.com/vivek7405/webjs/pull/NN)) [`abcd123`](https://github.com/vivek7405/webjs/commit/abcd123)
+  First four lines of the commit body, indented two spaces.
+
+## Features
+…
+
+## Fixes
+…
+```
+
+Frontmatter fields:
+
+| Field | Required | Meaning |
+|---|---|---|
+| `package` | yes | The fully-qualified npm name (`@webjskit/<pkg>`). |
+| `version` | yes | Semver string of the new release. |
+| `date` | yes | Date of the version-bump commit, `YYYY-MM-DD`. |
+| `commit_count` | yes | How many qualifying commits this version shipped. |
+
+## Backfill + ongoing automation
+
+A single script runs in both modes:
+
+```sh
+node scripts/backfill-changelog.js
+```
+
+It walks every package's `package.json` history, finds version
+bumps, and writes a `<pkg>/<version>.md` for any version that does
+not yet have one. **Files that already exist are left alone**, so
+hand-curated entries survive subsequent runs (CI re-runs are safe).
+
+Going forward, the same script runs:
+
+- on every CI build of `main`, so a forgotten version bump
+  still produces an entry without manual intervention;
+- locally when an agent edits a `packages/<pkg>/package.json` to
+  bump the version (the post-commit hook
+  `.hooks/post-version-bump` runs the script).
+
+The AGENTS.md rule that AI agents follow on every code-commit:
+
+> When you bump a `packages/<pkg>/package.json` `version`, run
+> `node scripts/backfill-changelog.js` (or just commit; CI will
+> regenerate). The generated `changelog/<pkg>/<version>.md` file
+> should be reviewed and **edited in-place** for clarity, especially
+> for `breaking` entries that need migration notes. Then commit the
+> changelog file alongside the version bump.
+
+## What if the same change ships across packages
+
+A commit that touches more than one package (e.g. a refactor that
+moves code from `core` to `server`) appears in **every** affected
+package's release file when each of those packages bumps its
+version. That is the right shape: the same change is a user-facing
+event for every package that carries it.
+
+## Migration to the new format
+
+The pre-0.7.1 history was backfilled in one pass. The files in
+`changelog/<pkg>/` are auto-generated but can (and should) be
+hand-edited to add migration notes, examples, or links to docs.
+Subsequent re-runs of `scripts/backfill-changelog.js` will not
+overwrite hand edits because the script skips files that already
+exist.