Dress the repo for company: readme, licence, ci

A picture of the viewer playing itself, a licence file to match the
package, cross-platform browser opening, and one copy of three.js
instead of two.

Author: vdayanand

.github/workflows/check.yml

@@ -0,0 +1,19 @@
+name: check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: ["18", "20", "22"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: make check

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
 *.log
+.claude/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Venkatesh Dayanand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,105 @@
+# gitdiff3d
+
+A git diff is a pile of text. Somebody typed that text, one key at a time, in
+some order that made sense to them. `gitdiff3d` plays it back: your diff becomes
+a 3d scene where every changed line is a plate floating in space, and a caret
+walks through them typing the additions in and erasing the deletions.
+
+![the viewer playing a hunk](docs/screenshot.png)
+
+## Install
+
+```
+git clone https://github.com/vdayanand/gitdiff3d
+cd gitdiff3d
+make install          # symlinks bin/gitdiff3d.js into ~/bin
+```
+
+Or run it straight out of the checkout with `node bin/gitdiff3d.js`.
+
+Node 18 or newer. No dependencies: three.js is vendored, everything else is the
+standard library and the `git` already on your path.
+
+## Use
+
+```
+gitdiff3d                    working tree vs HEAD
+gitdiff3d --staged           the index
+gitdiff3d HEAD~3..HEAD       a commit range
+gitdiff3d main HEAD          two revisions
+gitdiff3d -- src/            limit to a path
+```
+
+It builds the scene, serves it on a random local port, and opens your browser.
+
+```
+--port <n>        listen on port n (default: random)
+--max-hunks <n>   keep only the first n hunks (default: all)
+--order <how>     story or git (default: story)
+--context <n>     lines of unchanged code around each hunk (default: 8)
+--json            print the scene model, do not serve
+--no-open         serve without opening a browser
+```
+
+## Story order
+
+Git prints hunks in path order, which is alphabetical, which is nobody's
+thinking. The default `--order story` reorders them the way the change was
+probably made: a hunk that introduces a name comes before the hunks that call
+that name, and failing that, schema before models before logic before callers
+before tests before prose. It is a topological sort over "who defines what",
+with the file's role as the tie breaker. `--order git` turns it off.
+
+## Overlay
+
+Press `l` and the old version of the hunk sits behind the new one, both in
+frame, separated in depth rather than side by side. This is the one thing a flat
+diff cannot do.
+
+![the old version behind the new one](docs/overlay.png)
+
+## Keys
+
+```
+space  pause            ,  .  a keystroke back or forward
+<  >   a whole line     b  r  rewind this hunk
+arrows previous or next hunk       a  autoplay through everything
+j / k  scroll           wheel, ctrl-wheel zoom, shift-wheel sideways
+drag   orbit            0  refit the camera and follow the caret
+c      more or less context (refetched from git)
+l      overlay          g / G  fade the front or back plane
+t / T  next or previous theme        f  fullscreen
+x / X  faster or slower m  keystroke sound      v  speak the file and symbol
+?      show or hide the shortcuts
+```
+
+Twelve editor themes, dark and light: tokyo night, dracula, one dark, nord,
+gruvbox, solarized, github light, one light, gruvbox light, everforest light,
+mint. A theme names only the colours an editor names; the papers, rims and
+chrome are mixed from those, so nothing needs a table of shades.
+
+## How it works
+
+```
+git diff -U8  ->  parse-diff  ->  structure  ->  layout  ->  order  ->  viewer
+                  hunks and       which symbol   scene      story     three.js,
+                  lines           each hunk is   model      sort      one plate
+                                  inside                              per line
+```
+
+The server holds the scene model and re-runs the diff only when you ask for a
+different context width. Everything the browser needs is one JSON document plus
+one HTML file, so the viewer is dumb on purpose: it draws what it is given.
+
+Source structure is understood by regex, not by a real parser. It knows c-like
+languages (js, ts, go, rust, java, kotlin, swift, c#, c, c++, php, scala, dart),
+python, julia and ruby well enough to name the function a hunk lands in and to
+tell a comment-only change from a real one. Other languages still render, they
+just get no symbol names and no story order.
+
+Binary files are skipped. Very long lines are clipped to 200 characters.
+
+## Licence
+
+MIT, see [LICENSE](LICENSE). Bundles [three.js](https://threejs.org) r128,
+also MIT.

bin/gitdiff3d.js

@@ -41,6 +41,18 @@ function readArgs(argv) {
   return { flags, revisions };
 }
 
+// Whatever this platform calls "hand this url to the browser". A missing
+// opener is not worth failing over; the url is already printed.
+const openerFor = (platform) =>
+  platform === "darwin" ? ["open", []]
+    : platform === "win32" ? ["cmd", ["/c", "start", ""]]
+    : ["xdg-open", []];
+
+const openBrowser = (url) => {
+  const [command, args] = openerFor(process.platform);
+  execFile(command, [...args, url], () => {});
+};
+
 const describe = (revisions, cwd) =>
   revisions.length ? revisions.join(" ") : "working tree vs " + headLabel(cwd);
 
@@ -88,7 +100,7 @@ async function main() {
     scene.totals.additions + " -" + scene.totals.deletions + "  ->  " + url);
   console.log("keys: space pause, , . keystroke, < > line, arrows hunk, l overlay, c context,\n" +
     "      j/k scroll, x/X speed, m sound, v voice, f full, a autoplay, ? help");
-  if (flags.open) execFile("open", [url]);
+  if (flags.open) openBrowser(url);
 }
 
 main().catch((err) => {

docs/overlay.png

@@ -53,7 +53,7 @@
 </div>
 <div id="hint">drag to orbit &middot; wheel to zoom &middot; keys 1-5</div>
 
-<script src="three.min.js"></script>
+<script src="../src/vendor/three.min.js"></script>
 <script>
 /* ---------- fake repository ---------- */
 const rand = (() => { let s = 20260903; return () => (s = (s * 1103515245 + 12345) % 2147483648) / 2147483648; })();

docs/screenshot.png

@@ -1,11 +1,15 @@
 {
   "name": "gitdiff3d",
   "version": "0.1.0",
-  "description": "git diff rendered as a 3d scene",
-  "bin": { "gitdiff3d": "./bin/gitdiff3d.js" },
-  "main": "src/index.js",
+  "description": "git diff rendered as a 3d scene, played back hunk by hunk",
+  "keywords": ["git", "diff", "3d", "three", "code-review", "visualization", "cli"],
+  "homepage": "https://github.com/vdayanand/gitdiff3d#readme",
+  "bugs": "https://github.com/vdayanand/gitdiff3d/issues",
+  "repository": { "type": "git", "url": "git+https://github.com/vdayanand/gitdiff3d.git" },
+  "author": "Venkatesh Dayanand",
+  "license": "MIT",
   "type": "commonjs",
-  "engines": { "node": ">=18" },
-  "files": ["bin", "src"],
-  "license": "MIT"
+  "bin": { "gitdiff3d": "./bin/gitdiff3d.js" },
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" }
 }