fix(site): basePath /GraphCompose for project Pages deployment

The v1.6.8 cut deployed the Next.js site to demchaav.github.io/GraphCompose/
— a PROJECT Pages URL — without enabling Next.js's basePath / assetPrefix.
Result: every absolute path (/_next/static/css, /_next/static/chunks,
/brand/logo, /examples.json, /showcase/pdf, /previews/*) resolved against
the host root (demchaav.github.io) instead of the sub-path, returning 404
across the board. The browser rendered an unstyled, broken page.

Fix is two-pronged:

1) next.config.mjs — set basePath, assetPrefix, and a matching
   NEXT_PUBLIC_BASE_PATH env var to "/GraphCompose" (override to "" via
   the env when running `next dev` locally). Next.js automatically
   prefixes its own _next/static URLs and any <Link> / <Image> hrefs.

2) site/lib/base-path.ts — withBasePath() helper that prefixes runtime
   string paths Next.js doesn't see at build time: plain <img src>,
   <object data>, fetch() URLs. Applied to every public/ asset reference
   in our code:
     - TopBar.tsx        — /brand/graphcompose-logo.png
     - Gallery.tsx       — fetch('/examples.json') + showcaseUrl() for
                           every card's pdf + screenshot
     - lib/gallery.ts    — 16 CV image + 15 letterImage covers
     - lib/presets.tsx   — 3 Playground pdf + 3 poster paths

External URLs (github.com, javadoc.io), hash anchors, mailto:, and data:
URIs pass through untouched. The helper is idempotent — calling it with
an already-prefixed path is a no-op.

Verified with `next build` — 4/4 static pages prerendered green.

Author: DemchaAV

site/components/Gallery.tsx

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { GALLERY, type TemplateSpec } from "@/lib/gallery";
 import { PaperLetter } from "./PaperPage";
 import { highlightJava } from "@/lib/highlight";
+import { withBasePath } from "@/lib/base-path";
 import Reveal from "./Reveal";
 
 /*
@@ -81,7 +82,7 @@ interface Card {
 }
 
 const showcaseUrl = (relative: string) =>
-  `/showcase/${relative.replace(/^showcase\//, "")}`;
+  withBasePath(`/showcase/${relative.replace(/^showcase\//, "")}`);
 
 function buildCards(manifest: Manifest | null): Card[] {
   if (!manifest) return [];
@@ -135,7 +136,7 @@ export default function Gallery() {
   const lastFocus = useRef<HTMLElement | null>(null);
 
   useEffect(() => {
-    fetch("/examples.json", { cache: "force-cache" })
+    fetch(withBasePath("/examples.json"), { cache: "force-cache" })
       .then((r) => {
         if (!r.ok) throw new Error(`HTTP ${r.status}`);
         return r.json() as Promise<Manifest>;

site/components/TopBar.tsx

@@ -1,5 +1,6 @@
 "use client";
 import { useEffect, useState } from "react";
+import { withBasePath } from "@/lib/base-path";
 
 export default function TopBar() {
   const [theme, setTheme] = useState<"light" | "dark">("light");
@@ -28,7 +29,7 @@ export default function TopBar() {
         <a className="brand" href="#top" aria-label="GraphCompose home">
           {/* eslint-disable-next-line @next/next/no-img-element */}
           <img
-            src="/brand/graphcompose-logo.png"
+            src={withBasePath("/brand/graphcompose-logo.png")}
             alt="GraphCompose"
             className="brand-logo"
             width={172}

site/lib/base-path.ts

@@ -0,0 +1,31 @@
+/**
+ * Base-path prefixing for public/ assets.
+ *
+ * Next.js's `basePath` config auto-prefixes routes and `<Image>` /
+ * `<Link>` href values, but plain `<img src>` / `<object data>` /
+ * any string-literal asset path in our own code is left untouched
+ * — it would resolve against the host root and 404 on a project
+ * Pages deployment (e.g. `demchaav.github.io/GraphCompose/`).
+ *
+ * Use `withBasePath('/brand/logo.png')` so the same code works
+ * locally (basePath = "") and on Pages (basePath = "/GraphCompose").
+ *
+ * The base path is sourced from `NEXT_PUBLIC_BASE_PATH` at build
+ * time, which `next.config.mjs` keeps in lockstep with the
+ * `basePath` / `assetPrefix` it sets on the Next.js config.
+ */
+const RAW = (process.env.NEXT_PUBLIC_BASE_PATH ?? "").replace(/\/$/, "");
+
+export const basePath: string = RAW;
+
+export function withBasePath(path: string): string {
+  // External / hash / data URLs pass through untouched.
+  if (!path) return path;
+  if (path.startsWith("http://") || path.startsWith("https://")) return path;
+  if (path.startsWith("#") || path.startsWith("mailto:") || path.startsWith("data:")) return path;
+  // Avoid double-prefixing when callers already did the work.
+  if (RAW && path.startsWith(RAW + "/")) return path;
+  // Ensure a leading slash on inputs that lack one.
+  const normalised = path.startsWith("/") ? path : `/${path}`;
+  return `${RAW}${normalised}`;
+}

site/lib/gallery.ts

@@ -29,6 +29,8 @@ export interface TemplateSpec {
   letterSource: string | null;
 }
 
+import { withBasePath } from "./base-path";
+
 const GH = "https://github.com/DemchaAV/GraphCompose/blob/main/src/main/java/com/demcha/compose/document/templates";
 
 /*
@@ -80,8 +82,8 @@ export const GALLERY: TemplateSpec[] = SPECS.map(({ name, slug, hasLetter = true
   variant,
   desc,
   pair: hasLetter ? `${name}Letter` : null,
-  image: `/previews/cv-v2/cv-${slug}-v2.png`,
-  letterImage: hasLetter ? `/previews/coverletter-v2/cover-letter-${slug}-v2.png` : null,
+  image: withBasePath(`/previews/cv-v2/cv-${slug}-v2.png`),
+  letterImage: hasLetter ? withBasePath(`/previews/coverletter-v2/cover-letter-${slug}-v2.png`) : null,
   source: `${GH}/cv/v2/presets/${name}.java`,
   letterSource: hasLetter ? `${GH}/coverletter/v2/presets/${name}Letter.java` : null,
   code: `CvDocument cv = loadProfile();

site/lib/presets.tsx

@@ -1,4 +1,5 @@
 import { PaperHello, PaperInvoice, PaperCv } from "@/components/PaperPage";
+import { withBasePath } from "./base-path";
 import type { ReactNode } from "react";
 
 export type PresetId = "hello" | "invoice" | "cv";
@@ -38,8 +39,8 @@ export const PRESETS: Record<PresetId, Preset> = {
   hello: {
     id: "hello",
     label: "Hello world",
-    pdf: "/previews/hello.pdf",
-    poster: "/previews/hello.png",
+    pdf: withBasePath("/previews/hello.pdf"),
+    poster: withBasePath("/previews/hello.png"),
     code: `import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.api.DocumentPageSize;
 import com.demcha.compose.document.api.DocumentSession;
@@ -83,8 +84,8 @@ class Hello {
   invoice: {
     id: "invoice",
     label: "Invoice",
-    pdf: "/previews/invoice.pdf",
-    poster: "/previews/invoice.png",
+    pdf: withBasePath("/previews/invoice.pdf"),
+    poster: withBasePath("/previews/invoice.png"),
     code: `import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.api.DocumentPageSize;
 import com.demcha.compose.document.api.DocumentSession;
@@ -127,8 +128,8 @@ try (DocumentSession doc = GraphCompose.document(Path.of("invoice.pdf"))
   cv: {
     id: "cv",
     label: "CV · ModernProfessional",
-    pdf: "/previews/cv.pdf",
-    poster: "/previews/cv.png",
+    pdf: withBasePath("/previews/cv.pdf"),
+    poster: withBasePath("/previews/cv.png"),
     code: `import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.api.DocumentPageSize;
 import com.demcha.compose.document.api.DocumentSession;

site/next.config.mjs

@@ -1,13 +1,27 @@
 /** @type {import('next').NextConfig} */
+
+// Sub-path under which the site is hosted on GitHub Pages.
+// This is a PROJECT page (demchaav.github.io/<repo>/), so every
+// emitted URL needs the /GraphCompose prefix — otherwise `_next/`
+// static chunks, the logo, and every public/ asset 404 against
+// the host root. Set the same value on `basePath`, `assetPrefix`,
+// and `NEXT_PUBLIC_BASE_PATH` so our own `withBasePath(...)` helper
+// (lib/base-path.ts) sees it at runtime.
+//
+// Override to "" for local `next dev` if you prefer accessing the
+// site at http://localhost:5173/ instead of /GraphCompose/.
+const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH ?? "/GraphCompose";
+
 const nextConfig = {
   // Fully static build — `next build` emits ./out, deployable to
   // GitHub Pages / Vercel / any static host. No SSR, no server runtime.
   output: "export",
   images: { unoptimized: true },
-  // If you deploy under a sub-path on GitHub Pages (e.g. user.github.io/graph-compose),
-  // uncomment and set these:
-  // basePath: "/graph-compose",
-  // assetPrefix: "/graph-compose/",
+  basePath: BASE_PATH || undefined,
+  assetPrefix: BASE_PATH ? `${BASE_PATH}/` : undefined,
+  env: {
+    NEXT_PUBLIC_BASE_PATH: BASE_PATH,
+  },
   trailingSlash: true,
 };