@taciturnaxolotl/traverse 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,9 @@
 # traverse
 
-[![the diagram view](https://l4.dunkirk.sh/i/eAqE3K4HnppN.webp)](https://traverse.dunkirk.sh/diagram/6121f05c-a5ef-4ecf-8ffc-02534c5e767c)
+[![the diagram view](https://l4.dunkirk.sh/i/K1vXY48_1NcQ.webp)](https://traverse.dunkirk.sh/diagram/6121f05c-a5ef-4ecf-8ffc-02534c5e767c)
+
+> [!NOTE]
+> The canonical repo for this is hosted on tangled over at [`dunkirk.sh/traverse`](https://tangled.org/@dunkirk.sh/traverse)
 
 One of my favorite features about [amp](https://ampcode.com) is their walkthrough feature. It runs a sub agent which goes and breaks your repo into parts and then sends it up to amp's services to get rendered into a nice web page! I got curious and ended up dumping the tool prompt for both the walkthrough subagent and the tool prompt that generates the diagram.
 
@@ -43,8 +46,6 @@ For other agents its the same JSON config typically.
 
 ## Config
 
-### json config
-
 On macos edit/create `~/Library/Application Support/traverse/config.json`. If you are on Linux then `~/.config/traverse/config.json` (or `$XDG_CONFIG_HOME/traverse/config.json`)
 
 ```json
@@ -55,7 +56,7 @@ On macos edit/create `~/Library/Application Support/traverse/config.json`. If yo
 }
 ```
 
-### env vars
+alteratively or suplementally you can use env vars to define the same options:
 
 | var                  | default                       | description                                |
 | -------------------- | ----------------------------- | ------------------------------------------ |
@@ -64,8 +65,6 @@ On macos edit/create `~/Library/Application Support/traverse/config.json`. If yo
 | `TRAVERSE_SHARE_URL` | `https://traverse.dunkirk.sh` | share server url                           |
 | `TRAVERSE_DATA_DIR`  | platform default              | sqlite db location                         |
 
-The canonical repo for this is hosted on tangled over at [`dunkirk.sh/traverse`](https://tangled.org/@dunkirk.sh/traverse)
-
 <p align="center">
     <img src="https://raw.githubusercontent.com/taciturnaxolotl/carriage/main/.github/images/line-break.svg" />
 </p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taciturnaxolotl/traverse",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Interactive code walkthrough diagrams via MCP",
   "module": "src/index.ts",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "src",
     "bin",
+    "fonts",
     "icon.svg"
   ],
   "scripts": {
@@ -23,7 +24,6 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@fontsource/inter": "^5.2.8",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@resvg/resvg-wasm": "^2.6.2",
     "satori": "^0.19.1"

package/src/index.ts

@@ -4,7 +4,7 @@ import { z } from "zod/v4";
 import { generateViewerHTML } from "./template.ts";
 import type { WalkthroughDiagram } from "./types.ts";
 import { initDb, loadAllDiagrams, saveDiagram, deleteDiagramFromDb, generateId, getSharedUrl, saveSharedUrl } from "./storage.ts";
-import { generateOgImage } from "./og.ts";
+import { generateOgImage, generateIndexOgImage } from "./og.ts";
 import { loadConfig } from "./config.ts";
 
 const config = loadConfig();
@@ -153,11 +153,22 @@ try {
         });
       }
 
+      // Index OG image
+      if (url.pathname === "/og.png") {
+        const png = await generateIndexOgImage(MODE, diagrams.size);
+        return new Response(png, {
+          headers: {
+            "Content-Type": "image/png",
+            "Cache-Control": "public, max-age=3600",
+          },
+        });
+      }
+
       // List available diagrams
       if (url.pathname === "/") {
         const html = MODE === "server"
-          ? generateServerIndexHTML(diagrams.size, VERSION)
-          : generateLocalIndexHTML(diagrams, VERSION);
+          ? generateServerIndexHTML(diagrams.size, VERSION, url.origin)
+          : generateLocalIndexHTML(diagrams, VERSION, url.origin);
         return new Response(html, {
           headers: { "Content-Type": "text/html; charset=utf-8" },
         });
@@ -305,7 +316,7 @@ function generate404HTML(title: string, message: string): string {
 </html>`;
 }
 
-function generateLocalIndexHTML(diagrams: Map<string, WalkthroughDiagram>, gitHash: string): string {
+function generateLocalIndexHTML(diagrams: Map<string, WalkthroughDiagram>, gitHash: string, baseUrl: string): string {
   const items = [...diagrams.entries()]
     .map(
       ([id, d]) => {
@@ -346,6 +357,7 @@ function generateLocalIndexHTML(diagrams: Map<string, WalkthroughDiagram>, gitHa
       </div>`
     : `<div class="diagram-list">${items}</div>`;
 
+  const diagramCount = diagrams.size;
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -353,6 +365,14 @@ function generateLocalIndexHTML(diagrams: Map<string, WalkthroughDiagram>, gitHa
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Traverse</title>
   <link rel="icon" href="/icon.svg" type="image/svg+xml" />
+  <meta property="og:type" content="website" />
+  <meta property="og:title" content="Traverse" />
+  <meta property="og:description" content="Interactive code walkthrough diagrams. ${diagramCount} diagram${diagramCount !== 1 ? "s" : ""}." />
+  <meta property="og:image" content="${escapeHTML(baseUrl)}/og.png" />
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:title" content="Traverse" />
+  <meta name="twitter:description" content="Interactive code walkthrough diagrams." />
+  <meta name="twitter:image" content="${escapeHTML(baseUrl)}/og.png" />
   <style>
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
     :root {
@@ -511,7 +531,7 @@ function generateLocalIndexHTML(diagrams: Map<string, WalkthroughDiagram>, gitHa
 </html>`;
 }
 
-function generateServerIndexHTML(diagramCount: number, gitHash: string): string {
+function generateServerIndexHTML(diagramCount: number, gitHash: string, baseUrl: string): string {
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -519,6 +539,14 @@ function generateServerIndexHTML(diagramCount: number, gitHash: string): string
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Traverse</title>
   <link rel="icon" href="/icon.svg" type="image/svg+xml" />
+  <meta property="og:type" content="website" />
+  <meta property="og:title" content="Traverse" />
+  <meta property="og:description" content="Interactive code walkthrough diagrams, shareable with anyone. ${diagramCount} diagram${diagramCount !== 1 ? "s" : ""} shared." />
+  <meta property="og:image" content="${escapeHTML(baseUrl)}/og.png" />
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:title" content="Traverse" />
+  <meta name="twitter:description" content="Interactive code walkthrough diagrams, shareable with anyone." />
+  <meta name="twitter:image" content="${escapeHTML(baseUrl)}/og.png" />
   <style>
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
     :root {

package/src/og.ts

@@ -3,7 +3,7 @@ import { initWasm, Resvg } from "@resvg/resvg-wasm";
 import { join } from "path";
 
 // Load Inter font files (woff, not woff2 — satori doesn't support woff2)
-const fontsDir = join(import.meta.dir, "../node_modules/@fontsource/inter/files");
+const fontsDir = join(import.meta.dir, "../fonts");
 const [interRegular, interBold] = await Promise.all([
   Bun.file(join(fontsDir, "inter-latin-400-normal.woff")).arrayBuffer(),
   Bun.file(join(fontsDir, "inter-latin-700-normal.woff")).arrayBuffer(),
@@ -16,6 +16,114 @@ await initWasm(Bun.file(wasmPath).arrayBuffer());
 // Cache generated images by diagram ID
 const cache = new Map<string, Buffer>();
 
+export async function generateIndexOgImage(
+  mode: "local" | "server",
+  diagramCount: number,
+): Promise<Buffer> {
+  const cacheKey = `__index_${mode}_${diagramCount}`;
+  const cached = cache.get(cacheKey);
+  if (cached) return cached;
+
+  const subtitle = mode === "server"
+    ? `${diagramCount} diagram${diagramCount !== 1 ? "s" : ""} shared`
+    : `${diagramCount} diagram${diagramCount !== 1 ? "s" : ""}`;
+
+  const tagline = mode === "server"
+    ? "Interactive code walkthrough diagrams, shareable with anyone."
+    : "Interactive code walkthrough diagrams";
+
+  const svg = await satori(
+    {
+      type: "div",
+      props: {
+        style: {
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          flexDirection: "column",
+          justifyContent: "center",
+          alignItems: "center",
+          padding: "60px",
+          backgroundColor: "#0a0a0a",
+          color: "#e5e5e5",
+          fontFamily: "Inter",
+        },
+        children: [
+          {
+            type: "div",
+            props: {
+              style: {
+                display: "flex",
+                flexDirection: "column",
+                alignItems: "center",
+                gap: "20px",
+              },
+              children: [
+                {
+                  type: "div",
+                  props: {
+                    style: {
+                      fontSize: "80px",
+                      fontWeight: 700,
+                      color: "#e5e5e5",
+                    },
+                    children: "Traverse",
+                  },
+                },
+                {
+                  type: "div",
+                  props: {
+                    style: {
+                      fontSize: "32px",
+                      color: "#a3a3a3",
+                      textAlign: "center",
+                    },
+                    children: tagline,
+                  },
+                },
+                {
+                  type: "div",
+                  props: {
+                    style: {
+                      display: "flex",
+                      alignItems: "center",
+                      gap: "8px",
+                      marginTop: "16px",
+                      fontSize: "24px",
+                      color: "#a3a3a3",
+                      backgroundColor: "#1c1c1e",
+                      padding: "10px 24px",
+                      borderRadius: "8px",
+                      border: "1px solid #262626",
+                    },
+                    children: subtitle,
+                  },
+                },
+              ],
+            },
+          },
+        ],
+      },
+    },
+    {
+      width: 1200,
+      height: 630,
+      fonts: [
+        { name: "Inter", data: interRegular, weight: 400, style: "normal" as const },
+        { name: "Inter", data: interBold, weight: 700, style: "normal" as const },
+      ],
+    },
+  );
+
+  const resvg = new Resvg(svg, {
+    fitTo: { mode: "width", value: 1200 },
+  });
+  const png = Buffer.from(resvg.render().asPng());
+
+  cache.set(cacheKey, png);
+  return png;
+}
+
 export async function generateOgImage(
   id: string,
   summary: string,