version-history-widget 0.1.2 → 0.1.4

package/README.md

@@ -28,8 +28,13 @@ npx vh init                 # sets up .versions/, injects the widget, saves vers
 npx vh record "Title" -d "what changed and why"
 npx vh restore 4            # safety-snapshots current state, then restores version 4
 npx vh list [query]         # list versions, optionally filtered
+npx vh update               # refresh .versions/*.js from the currently installed package
 ```
 
+`vh init` only copies `widget.js` (and friends) into `.versions/` once. If
+you upgrade the package later and want an already-initialized site to pick
+up widget changes (new styling, bug fixes, etc.), run `vh update`.
+
 Serve it so the restore button works:
 
 ```bash
@@ -64,6 +69,20 @@ npx vh-singlefile list page.html [query]
 Restoring is handled entirely in the browser by the injected widget — no
 server needed.
 
+## Claude Code skill
+
+If you use Claude Code, this installs a skill so you can drive it with
+`/version-history-widget` (or by just describing what you want) instead
+of typing the CLI commands yourself:
+
+```bash
+npx version-history-widget skill
+```
+
+This copies a `SKILL.md` into `~/.claude/skills/version-history-widget/`
+on your machine. It's per-machine — anyone else who wants the slash
+command needs to run this once on their own machine too.
+
 ## How it works
 
 - No runtime dependencies — only Node's built-in `fs`, `path`, `http`, and
@@ -72,6 +91,10 @@ server needed.
   are exact and history is human-readable.
 - The widget (`widget.js`) is vanilla JS + inline CSS, scoped under `vh-`
   class names so it never collides with your site's styles.
+- The "Versions" pill is draggable — click and drag it anywhere on screen
+  (works with touch too), and its position is remembered per-browser via
+  `localStorage`. The panel it opens repositions itself next to wherever
+  the pill currently is.
 
 ## Customizing the widget UI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "version-history-widget",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Zero-dependency version history for web projects: snapshots every change and adds a floating widget to browse, search, and restore any version.",
   "keywords": ["version history", "undo", "snapshot", "restore", "dev-tool", "widget"],
   "license": "MIT",
@@ -17,7 +17,8 @@
     "widget.js",
     "middleware.js",
     "serve.js",
-    "singlefile.js"
+    "singlefile.js",
+    "skill/SKILL.md"
   ],
   "repository": {
     "type": "git",

package/skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: version-history-widget
+description: Zero-dependency version history for web projects (the `vh` / version-history-widget CLI). Use when the user wants to save a checkpoint or snapshot of their site, record a titled version of recent changes, list past versions, or restore/roll back to an earlier version. Covers both project mode (multi-file sites, snapshots in .versions/) and single-file mode (one HTML file, snapshots embedded in the file).
+---
+
+# Version History Widget
+
+CLI for saving titled, restorable snapshots of a web project, plus a
+floating "Versions" widget injected into the live site so anyone can
+browse, search, and restore with one click. No runtime dependencies.
+
+Two modes — pick based on what the user is working on:
+
+- **Project mode**: a normal multi-file site/app. History lives in `.versions/`.
+- **Single-file mode**: one standalone `.html` file. History lives inside that file.
+
+## Project mode
+
+Run these with Bash from the project root (`npx` needs no local install):
+
+- First time only — sets up `.versions/`, injects the widget into the
+  site's entry HTML, saves version 1:
+  `npx version-history-widget init`
+- After the user has made changes and wants a checkpoint:
+  `npx version-history-widget record "Title" -d "what changed and why"`
+- List versions, optionally filtered by title/details text:
+  `npx version-history-widget list [query]`
+- Restore an earlier version (this automatically snapshots the
+  current state first, so it's safe):
+  `npx version-history-widget restore <id>`
+- To serve the site so the widget's in-browser restore button works:
+  `node .versions/serve.js` (or mount `.versions/middleware.js` in
+  their existing dev server — see `.versions/middleware.js`'s header
+  comment for Express/Vite examples).
+
+If `.versions/` doesn't exist yet in the project, run `init` first.
+
+## Single-file mode
+
+Use when the user names one `.html` file rather than a project:
+
+- Init: `npx -p version-history-widget vh-singlefile init page.html`
+- Record: `npx -p version-history-widget vh-singlefile record page.html "Title" -d "details"`
+- List: `npx -p version-history-widget vh-singlefile list page.html [query]`
+
+Restoring in single-file mode happens entirely in the browser via the
+widget embedded in the file — no server or CLI restore command needed.
+
+## Notes
+
+- If the user has it installed as a devDependency already
+  (`npm install --save-dev version-history-widget`), use `npx vh ...`
+  and `npx vh-singlefile ...` directly instead of the longer `-p` form.
+- Always ask for or infer a short, human title when recording — it's
+  what shows up in the widget's list and search.
+- Don't run `restore` without the user confirming which version id
+  they want — list versions first if it's ambiguous.

package/vh.js

@@ -4,8 +4,12 @@
    node vh.js record "Title" [-d "details" | -f details.txt]   — snapshot changed files as a new version
    node vh.js restore <id>               — snapshot current state, then restore version <id>
    node vh.js list [query]               — list versions (optionally filtered by title/details)
+   node vh.js update                     — refresh the vendored widget.js/vh.js/serve.js/middleware.js
+                                            in .versions/ from the installed package (run after upgrading)
+   node vh.js skill                      — install the Claude Code skill (~/.claude/skills) so
+                                            /version-history-widget works in Claude Code sessions
    Env: VH_ROOT (project root, default cwd) */
-const fs = require('fs'), path = require('path');
+const fs = require('fs'), path = require('path'), os = require('os');
 const ROOT = path.resolve(process.env.VH_ROOT || process.cwd());
 const VDIR = path.join(ROOT, '.versions'), SNAP = path.join(VDIR, 'snapshots'), MAN = path.join(VDIR, 'manifest.json');
 const IGNORE = new Set(['node_modules', '.git', '.versions', 'dist', 'build', '.next', '.nuxt', 'coverage', '.cache']);
@@ -82,10 +86,15 @@ function injectWidget() {
   return null;
 }
 
+function vendorFiles() {
+  fs.mkdirSync(VDIR, { recursive: true });
+  for (const f of ['widget.js', 'vh.js', 'serve.js', 'middleware.js']) { const src = path.join(__dirname, f); if (fs.existsSync(src) && src !== path.join(VDIR, f)) fs.copyFileSync(src, path.join(VDIR, f)); }
+}
+
 const cmd = process.argv[2], args = process.argv.slice(3);
 if (cmd === 'init') {
   fs.mkdirSync(SNAP, { recursive: true });
-  for (const f of ['widget.js', 'vh.js', 'serve.js', 'middleware.js']) { const src = path.join(__dirname, f); if (fs.existsSync(src) && src !== path.join(VDIR, f)) fs.copyFileSync(src, path.join(VDIR, f)); }
+  vendorFiles();
   if (!fs.existsSync(MAN)) writeMan([]);
   const gi = path.join(ROOT, '.gitignore'); const line = '.versions/snapshots/';
   if (!fs.existsSync(gi) || !fs.readFileSync(gi, 'utf8').includes(line)) fs.appendFileSync(gi, '\n' + line + '\n');
@@ -115,5 +124,14 @@ if (cmd === 'init') {
 } else if (cmd === 'list') {
   const q = (args[0] || '').toLowerCase();
   for (const v of readMan()) if (!q || v.title.toLowerCase().includes(q) || (v.details || '').toLowerCase().includes(q)) console.log(String(v.id).padStart(3) + '  ' + v.time.slice(0, 16).replace('T', ' ') + '  ' + v.title);
+} else if (cmd === 'update') {
+  if (!fs.existsSync(VDIR)) { console.error('No .versions/ here — run `vh init` first.'); process.exit(1); }
+  vendorFiles();
+  console.log('Updated .versions/{widget.js,vh.js,serve.js,middleware.js} from version-history-widget@' + require('./package.json').version + '. Reload the site to pick up widget changes.');
+} else if (cmd === 'skill') {
+  const dest = path.join(os.homedir(), '.claude', 'skills', 'version-history-widget');
+  fs.mkdirSync(dest, { recursive: true });
+  fs.copyFileSync(path.join(__dirname, 'skill', 'SKILL.md'), path.join(dest, 'SKILL.md'));
+  console.log('Installed Claude Code skill to ' + dest + '. Restart Claude Code (or start a new session) and try /version-history-widget.');
 } else { console.log(fs.readFileSync(__filename, 'utf8').split('*/')[0].split('\n').slice(1).join('\n')); }
 module.exports = { restore: id => { const { execFileSync } = require('child_process'); return execFileSync(process.execPath, [__filename, 'restore', String(id)], { cwd: ROOT, env: process.env }).toString(); } };

package/widget.js

@@ -3,7 +3,8 @@
   if (window.__vhLoaded) return; window.__vhLoaded = true;
   var Z = 2147483647, MODE = document.getElementById('vh-store') ? 'single' : 'project';
   var css = '\
-.vh-pill{position:fixed;right:16px;top:16px;z-index:' + Z + ';font:13px/1 system-ui,sans-serif;background:#111;color:#fff;border:0;border-radius:999px;padding:10px 14px;cursor:pointer;box-shadow:0 6px 20px rgba(0,0,0,.35)}\
+.vh-pill{position:fixed;right:16px;top:16px;z-index:' + Z + ';font:13px/1 system-ui,sans-serif;background:#111;color:#fff;border:0;border-radius:999px;padding:10px 14px;cursor:grab;box-shadow:0 6px 20px rgba(0,0,0,.35);touch-action:none;user-select:none}\
+.vh-pill.vh-dragging{cursor:grabbing}\
 .vh-panel{position:fixed;right:16px;top:56px;width:440px;max-width:calc(100vw - 32px);max-height:70vh;z-index:' + Z + ';background:#fff;color:#111;border:1px solid #ddd;border-radius:12px;box-shadow:0 12px 40px rgba(0,0,0,.35);font:13px/1.4 system-ui,sans-serif;display:flex;flex-direction:column;overflow:hidden}\
 .vh-head{display:flex;gap:8px;padding:10px;border-bottom:1px solid #eee;align-items:center}\
 .vh-search{flex:1;padding:8px 10px;border:1px solid #ccc;border-radius:8px;font:inherit;outline:none}.vh-search:focus{border-color:#111}\
@@ -69,16 +70,65 @@
     });
   }
 
+  var POS_KEY = 'vh-pill-pos';
+  function clamp(v, min, max) { return Math.max(min, Math.min(max, v)); }
+  function loadPos() { try { var p = JSON.parse(localStorage.getItem(POS_KEY)); if (p && isFinite(p.left) && isFinite(p.top)) return p; } catch (e) { } return null; }
+  function savePos(p) { try { localStorage.setItem(POS_KEY, JSON.stringify(p)); } catch (e) { } }
+  function placePill(left, top) {
+    var r = pill.getBoundingClientRect();
+    left = clamp(left, 8, window.innerWidth - r.width - 8);
+    top = clamp(top, 8, window.innerHeight - r.height - 8);
+    pill.style.left = left + 'px'; pill.style.top = top + 'px'; pill.style.right = 'auto'; pill.style.bottom = 'auto';
+    return { left: left, top: top };
+  }
+  function positionPanel() {
+    var r = pill.getBoundingClientRect(), vw = window.innerWidth, vh = window.innerHeight;
+    var w = Math.min(440, vw - 16), h = Math.min(vh * 0.7, panel.scrollHeight || vh * 0.7);
+    var top = (vh - r.bottom >= h + 8 || vh - r.bottom >= r.top) ? r.bottom + 8 : r.top - h - 8;
+    top = clamp(top, 8, vh - h - 8);
+    var left = clamp(r.right - w, 8, vw - w - 8);
+    panel.style.top = top + 'px'; panel.style.left = left + 'px'; panel.style.right = 'auto'; panel.style.bottom = 'auto'; panel.style.width = w + 'px';
+  }
+  function initDrag() {
+    var saved = loadPos(); if (saved) placePill(saved.left, saved.top);
+    var dragging = false, moved = false, startX, startY, baseLeft, baseTop;
+    function start(x, y) {
+      var r = pill.getBoundingClientRect();
+      dragging = true; moved = false; startX = x; startY = y; baseLeft = r.left; baseTop = r.top;
+      pill.classList.add('vh-dragging');
+    }
+    function moveTo(x, y) {
+      if (!dragging) return;
+      if (Math.abs(x - startX) > 3 || Math.abs(y - startY) > 3) moved = true;
+      if (!moved) return;
+      placePill(baseLeft + (x - startX), baseTop + (y - startY));
+      if (open) positionPanel();
+    }
+    function end() {
+      if (!dragging) return;
+      dragging = false; pill.classList.remove('vh-dragging');
+      if (moved) { var r = pill.getBoundingClientRect(); savePos({ left: r.left, top: r.top }); }
+    }
+    pill.addEventListener('mousedown', function (e) { start(e.clientX, e.clientY); e.preventDefault(); });
+    document.addEventListener('mousemove', function (e) { moveTo(e.clientX, e.clientY); });
+    document.addEventListener('mouseup', end);
+    pill.addEventListener('touchstart', function (e) { var t = e.touches[0]; start(t.clientX, t.clientY); }, { passive: true });
+    document.addEventListener('touchmove', function (e) { if (!dragging) return; var t = e.touches[0]; moveTo(t.clientX, t.clientY); }, { passive: true });
+    document.addEventListener('touchend', end);
+    pill.onclick = function () { if (moved) { moved = false; return; } toggle(); };
+    window.addEventListener('resize', function () { var r = pill.getBoundingClientRect(); placePill(r.left, r.top); if (open) positionPanel(); });
+  }
   function build() {
-    pill = document.createElement('button'); pill.className = 'vh-pill'; pill.textContent = 'Versions'; pill.onclick = toggle; document.body.appendChild(pill);
+    pill = document.createElement('button'); pill.className = 'vh-pill'; pill.textContent = 'Versions'; document.body.appendChild(pill);
     panel = document.createElement('div'); panel.className = 'vh-panel'; panel.style.display = 'none';
     panel.innerHTML = '<div class="vh-head"><input class="vh-search" placeholder="Search versions\u2026"><button class="vh-clear" title="Clear">\u00D7</button></div><div class="vh-list"></div><div class="vh-note"></div>';
     var inp = panel.querySelector('.vh-search'); inp.oninput = function () { query = inp.value; render(); };
     panel.querySelector('.vh-clear').onclick = function () { inp.value = ''; query = ''; render(); inp.focus(); };
     document.addEventListener('keydown', function (e) { if (e.key !== 'Escape' || !open) return; if (query) { inp.value = ''; query = ''; render(); } else toggle(); });
     document.body.appendChild(panel);
+    initDrag();
   }
-  function toggle() { open = !open; if (open) load(function () { panel.style.display = 'flex'; render(); panel.querySelector('.vh-search').focus(); }); else panel.style.display = 'none'; }
+  function toggle() { open = !open; if (open) load(function () { panel.style.display = 'flex'; positionPanel(); render(); panel.querySelector('.vh-search').focus(); }); else panel.style.display = 'none'; }
   function init() { build(); load(render); }
   if (document.body) init(); else document.addEventListener('DOMContentLoaded', init);
 })();