idcmd 0.0.8 → 0.0.10

package/README.md

@@ -9,7 +9,7 @@ bun install
 bun run dev
 ```
 
-Everything you edit lives in `site/`.
+Everything you edit lives at the project root-level source folders (`content/`, `src/`, `styles/`, `assets/`, `site.jsonc`).
 
 ## CLI
 
@@ -19,18 +19,18 @@ idcmd dev          # tailwind watch + SSR dev server
 idcmd build        # static public/
 idcmd preview      # serve public/ locally
 idcmd deploy       # build + validate Vercel static deploy config
-idcmd client ...   # add/update local site/src implementations
+idcmd client ...   # add/update local src implementations
 ```
 
 ## Layout (V1)
 
-- `site/content/<slug>.md` -> `/<slug>/` (`index.md` -> `/`)
-- `site/src/ui/*` is local UI source code (you own and edit these files)
-- `site/src/runtime/*.ts` is local browser runtime code (compiled to `public/_idcmd/*.js`)
-- `site/src/routes/**` file-based server routes (dev/server-host only)
-- `site/styles/tailwind.css` -> `public/styles.css`
-- `site/assets/` static assets
-- `site/site.jsonc` site config
+- `content/<slug>.md` -> `/<slug>/` (`index.md` -> `/`)
+- `src/ui/*` is local UI source code (you own and edit these files)
+- `src/runtime/*.ts` is local browser runtime code (compiled to `public/_idcmd/*.js`)
+- `src/routes/**` file-based server routes (dev/server-host only)
+- `styles/tailwind.css` -> `public/styles.css`
+- `assets/` static assets
+- `site.jsonc` site config
 - `public/` generated output (gitignored)
 
 ## Syncing Local Client Code
@@ -45,11 +45,11 @@ idcmd client update runtime --yes
 ```
 
 `add` creates missing files. `update` overwrites changed files and requires `--yes` unless `--dry-run` is used.
-Runtime files in `site/src/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
+Runtime files in `src/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
 
 ## Example: Add A Page
 
-Create `site/content/hello.md`:
+Create `content/hello.md`:
 
 ```md
 ---
@@ -68,7 +68,7 @@ It renders at `/hello/`.
 
 ## Custom Server Routes (V1)
 
-Add `site/src/routes/api/hello.ts`:
+Add `src/routes/api/hello.ts`:
 
 ```ts
 export const GET = (): Response => Response.json({ ok: true });
@@ -94,7 +94,7 @@ It responds at `/api/hello`.
 
 ### Slug and path rules
 
-- Content lives at `site/content/<slug>.md`.
+- Content lives at `content/<slug>.md`.
 - `slug="index"` is the home page.
 - Canonical HTML paths are `/` for index and `/<slug>/` otherwise.
 - Markdown download paths exist in two forms:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idcmd",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "repository": {
     "type": "git",
     "url": "https://github.com/rustydotwtf/idcmd"
@@ -22,9 +22,9 @@
   },
   "scripts": {
     "dev": "concurrently -k -n css,server -c blue,green \"bun run dev:css\" \"bun run dev:server\"",
-    "dev:css": "bunx @tailwindcss/cli -i site/styles/tailwind.css -o public/styles.css --watch",
+    "dev:css": "bunx @tailwindcss/cli -i styles/tailwind.css -o public/styles.css --watch",
     "dev:server": "bun --hot src/server.ts",
-    "build:css": "bunx @tailwindcss/cli -i site/styles/tailwind.css -o public/styles.css --minify",
+    "build:css": "bunx @tailwindcss/cli -i styles/tailwind.css -o public/styles.css --minify",
     "build": "bun run build:css && bun src/build.ts",
     "preview": "bunx serve public",
     "start": "bun src/server.ts",

package/src/build.ts

@@ -20,7 +20,7 @@ const MIN_SEARCH_QUERY_LENGTH = 2;
 
 const project = await getProjectPaths();
 
-// Find all content files in `site/content/` (`site/content/<slug>.md`).
+// Find all content files in `content/` (`content/<slug>.md`).
 const contentFiles: string[] = [];
 
 const buildStart = performance.now();
@@ -214,7 +214,7 @@ if (siteConfig.baseUrl) {
   console.log(`  generated ${project.outputDir}/robots.txt`);
 } else {
   console.log(
-    "Warning: site/site.jsonc missing baseUrl; skipping sitemap.xml and robots.txt."
+    "Warning: site.jsonc missing baseUrl; skipping sitemap.xml and robots.txt."
   );
 }
 

package/src/cli/commands/build.ts

@@ -1,12 +1,12 @@
 import { compileRuntimeAssetsOnce } from "../runtime-assets";
 
 const findTailwindInput = async (): Promise<string> => {
-  const path = "site/styles/tailwind.css";
+  const path = "styles/tailwind.css";
   if (await Bun.file(path).exists()) {
     return path;
   }
   throw new Error(
-    "Could not find Tailwind input. Expected site/styles/tailwind.css."
+    "Could not find Tailwind input. Expected styles/tailwind.css."
   );
 };
 

package/src/cli/commands/client.ts

@@ -8,7 +8,6 @@ const TEMPLATE_UI_DIR = joinPath(
   "..",
   "templates",
   "default",
-  "site",
   "src",
   "ui"
 );
@@ -19,14 +18,13 @@ const TEMPLATE_RUNTIME_DIR = joinPath(
   "..",
   "templates",
   "default",
-  "site",
   "src",
   "runtime"
 );
 
-const SITE_UI_DIR = joinPath("site", "src", "ui");
-const SITE_RUNTIME_DIR = joinPath("site", "src", "runtime");
-const SITE_CONFIG_PATH = joinPath("site", "site.jsonc");
+const SITE_UI_DIR = joinPath("src", "ui");
+const SITE_RUNTIME_DIR = joinPath("src", "runtime");
+const SITE_CONFIG_PATH = "site.jsonc";
 
 const CLIENT_PARTS = [
   "layout",
@@ -144,7 +142,7 @@ const parseClientArgs = (positionals: string[]): ParsedClientArgs => {
 const ensureSiteLayout = async (): Promise<void> => {
   if (!(await Bun.file(SITE_CONFIG_PATH).exists())) {
     throw new Error(
-      `Could not find ${SITE_CONFIG_PATH}. Run this command from an idcmd site project root.`
+      `Could not find ${SITE_CONFIG_PATH}. Run this command from an idcmd project root.`
     );
   }
 };

package/src/cli/commands/deploy.ts

@@ -30,7 +30,7 @@ const warnIfVercelMisconfigured = async (): Promise<void> => {
 };
 
 const warnIfBaseUrlMissing = async (): Promise<void> => {
-  const file = Bun.file("site/site.jsonc");
+  const file = Bun.file("site.jsonc");
   if (!(await file.exists())) {
     return;
   }
@@ -42,13 +42,13 @@ const warnIfBaseUrlMissing = async (): Promise<void> => {
     if (!cfg.baseUrl) {
       // eslint-disable-next-line no-console
       console.warn(
-        "Warning: site/site.jsonc missing baseUrl; sitemap.xml and robots.txt will be skipped."
+        "Warning: site.jsonc missing baseUrl; sitemap.xml and robots.txt will be skipped."
       );
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     // eslint-disable-next-line no-console
-    console.warn(`Warning: Failed to parse site/site.jsonc: ${message}`);
+    console.warn(`Warning: Failed to parse site.jsonc: ${message}`);
   }
 };
 

package/src/cli/commands/dev.ts

@@ -11,12 +11,12 @@ export interface DevFlags {
 }
 
 const findTailwindInput = async (): Promise<string> => {
-  const path = "site/styles/tailwind.css";
+  const path = "styles/tailwind.css";
   if (await Bun.file(path).exists()) {
     return path;
   }
   throw new Error(
-    "Could not find Tailwind input. Expected site/styles/tailwind.css."
+    "Could not find Tailwind input. Expected styles/tailwind.css."
   );
 };
 

package/src/cli/commands/init.ts

@@ -200,7 +200,7 @@ const applySubstitutions = async (args: {
   siteName: string;
   targetDir: string;
 }): Promise<void> => {
-  await replaceInFile(joinPath(args.targetDir, "site", "site.jsonc"), (text) =>
+  await replaceInFile(joinPath(args.targetDir, "site.jsonc"), (text) =>
     fillSiteJsonc({
       baseUrl: args.baseUrl,
       description: args.description,

package/src/cli/runtime-assets.ts

@@ -1,6 +1,6 @@
 import { joinPath } from "./path";
 
-const RUNTIME_SOURCE_DIR = joinPath("site", "src", "runtime");
+const RUNTIME_SOURCE_DIR = joinPath("src", "runtime");
 const RUNTIME_OUTPUT_DIR = joinPath("public", "_idcmd");
 
 const RUNTIME_ENTRY_FILES = [

package/src/content/paths.ts

@@ -21,7 +21,7 @@ export const slugFromContentFile = (file: string): string => {
 export const scanContentFiles =
   async function* scanContentFiles(): AsyncGenerator<string> {
     const { contentDir } = await getProjectPaths();
-    // `site/content/<slug>.md`
+    // `content/<slug>.md`
     for await (const file of flatContentGlob.scan(contentDir)) {
       yield file;
     }

package/src/project/paths.ts

@@ -1,4 +1,3 @@
-const DEFAULT_SITE_DIR = "site";
 const DEFAULT_OUTPUT_DIR = "public";
 const ASSET_PREFIX = "/_idcmd" as const;
 const CONTENT_DIR = "content";
@@ -15,13 +14,11 @@ export interface ProjectPaths {
   assetsDir: string;
   routesDir: string;
   siteConfigPath: string;
-  siteDir: string | null;
 }
 
 export interface ResolveProjectPathsOptions {
   cwd?: string;
   outputDir?: string;
-  siteDir?: string;
 }
 
 const trimTrailingSlash = (value: string): string =>
@@ -45,28 +42,22 @@ const joinPath = (...parts: string[]): string => {
 const buildPaths = (args: {
   cwd: string;
   outputDirName: string;
-  siteDirName: string;
-}): ProjectPaths => {
-  const siteRoot = joinPath(args.cwd, args.siteDirName);
-  return {
-    assetPrefix: ASSET_PREFIX,
-    assetsDir: joinPath(siteRoot, ASSETS_DIR),
-    contentDir: joinPath(siteRoot, CONTENT_DIR),
-    iconsDir: joinPath(siteRoot, ICONS_DIR),
-    outputDir: joinPath(args.cwd, args.outputDirName),
-    routesDir: joinPath(siteRoot, ROUTES_DIR),
-    siteConfigPath: joinPath(siteRoot, SITE_CONFIG_FILE),
-    siteDir: siteRoot,
-  };
-};
+}): ProjectPaths => ({
+  assetPrefix: ASSET_PREFIX,
+  assetsDir: joinPath(args.cwd, ASSETS_DIR),
+  contentDir: joinPath(args.cwd, CONTENT_DIR),
+  iconsDir: joinPath(args.cwd, ICONS_DIR),
+  outputDir: joinPath(args.cwd, args.outputDirName),
+  routesDir: joinPath(args.cwd, ROUTES_DIR),
+  siteConfigPath: joinPath(args.cwd, SITE_CONFIG_FILE),
+});
 
 export const resolveProjectPaths = (
   options: ResolveProjectPathsOptions = {}
 ): Promise<ProjectPaths> => {
   const cwd = trimTrailingSlash(options.cwd ?? process.cwd());
   const outputDirName = options.outputDir ?? DEFAULT_OUTPUT_DIR;
-  const siteDirName = options.siteDir ?? DEFAULT_SITE_DIR;
-  return Promise.resolve(buildPaths({ cwd, outputDirName, siteDirName }));
+  return Promise.resolve(buildPaths({ cwd, outputDirName }));
 };
 
 let cached: Promise<ProjectPaths> | null = null;

package/src/render/layout-loader.ts

@@ -2,7 +2,7 @@ import type { RenderLayout } from "./layout";
 
 import { renderLayout as defaultRenderLayout } from "./layout";
 
-const USER_LAYOUT_PATH = "site/src/ui/layout.tsx";
+const USER_LAYOUT_PATH = "src/ui/layout.tsx";
 
 const loadUserLayout = async (
   filePath: string

package/src/render/layout.tsx

@@ -151,7 +151,7 @@ const TopNavbar = ({
       <div class="flex items-center gap-4">
         <a
           href="/"
-          class="text-sm font-medium tracking-tight font-mono md:hidden"
+          class="text-sm font-medium tracking-tight font-mono lg:hidden"
           data-prefetch="hover"
         >
           <span class="text-muted-foreground">~/</span>

package/src/render/right-rail-loader.ts

@@ -2,7 +2,7 @@ import type { RightRailComponent } from "./right-rail";
 
 import { RightRail as defaultRightRail } from "./right-rail";
 
-const USER_RIGHT_RAIL_PATH = "site/src/ui/right-rail.tsx";
+const USER_RIGHT_RAIL_PATH = "src/ui/right-rail.tsx";
 
 const loadUserRightRail = async (
   filePath: string

package/src/search/search-page-loader.ts

@@ -2,7 +2,7 @@ import type { RenderSearchPageContent } from "./page";
 
 import { renderSearchPageContent as defaultRenderSearchPageContent } from "./page";
 
-const USER_SEARCH_PAGE_PATH = "site/src/ui/search-page.tsx";
+const USER_SEARCH_PAGE_PATH = "src/ui/search-page.tsx";
 
 const loadUserSearchPage = async (
   filePath: string

package/src/server/live-reload.ts

@@ -59,7 +59,7 @@ export const createLiveReload = (env: LiveReloadEnv): LiveReloadController => {
       return;
     }
 
-    console.log("Watching site/content/ for changes...");
+    console.log("Watching content/ for changes...");
     let snapshot = await getContentSnapshot();
 
     const poll = async (): Promise<void> => {

package/src/site/config.ts

@@ -91,7 +91,7 @@ export interface ResolvedRightRailConfig {
   };
 }
 
-const SITE_CONFIG_PATH = "site/site.jsonc";
+const SITE_CONFIG_PATH = "site.jsonc";
 const LOCALHOST_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]);
 
 const DEFAULT_RIGHT_RAIL_CONFIG: ResolvedRightRailConfig = {

package/templates/default/README.md

@@ -1,6 +1,6 @@
 # **IDCMD_SITE_NAME**
 
-Everything you edit lives in `site/`.
+Everything you edit lives in root-level source folders.
 
 This starter is intentionally opinionated for AI-friendly markdown sites.
 
@@ -20,16 +20,16 @@ bun run smoke
 
 ## Layout
 
-- Content: `site/content/` markdown pages (`index.md` -> `/`, `about.md` -> `/about/`)
-- Code: `site/src/ui/` (`layout.tsx`, `right-rail.tsx`, `search-page.tsx`)
-- Code: `site/src/runtime/` browser runtime TS (`*_idcmd` scripts compile from here)
-- Code: `site/src/routes/` file-based server routes (dev/server-host only)
-- Assets: `site/assets/` static files you own (icons, images, favicon, etc.)
-- Styles source: `site/styles/tailwind.css`
-- Config: `site/site.jsonc`
+- Content: `content/` markdown pages (`index.md` -> `/`, `about.md` -> `/about/`)
+- Code: `src/ui/` (`layout.tsx`, `right-rail.tsx`, `search-page.tsx`)
+- Code: `src/runtime/` browser runtime TS (`*_idcmd` scripts compile from here)
+- Code: `src/routes/` file-based server routes (dev/server-host only)
+- Assets: `assets/` static files you own (icons, images, favicon, etc.)
+- Styles source: `styles/tailwind.css`
+- Config: `site.jsonc`
 - Generated output: `public/` (`public/styles.css`, `public/_idcmd/*.js`, built pages)
 
-The mental model is simple: edit `site/content` and `site/src`, treat `public/` as generated output.
+The mental model is simple: edit `content` and `src`, treat `public/` as generated output.
 
 ## Sync Local Client Files
 
@@ -40,8 +40,8 @@ idcmd client update layout --yes
 idcmd client update runtime --yes
 ```
 
-These commands copy the latest baseline implementations from `idcmd` into `site/src/ui/` and `site/src/runtime/`.
-Runtime files in `site/src/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
+These commands copy the latest baseline implementations from `idcmd` into `src/ui/` and `src/runtime/`.
+Runtime files in `src/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
 
 ## Deploy (Vercel static)
 

package/templates/default/{site/content → content}/index.md

@@ -7,4 +7,4 @@ icon: home
 
 # **IDCMD_SITE_NAME**
 
-Edit markdown in `site/content/`.
+Edit markdown in `content/`.

package/templates/default/scripts/check-internal.ts

@@ -11,16 +11,16 @@ const checks: InternalCheck[] = [
     run: () => fileExists("package.json"),
   },
   {
-    description: "site config must exist (site/site.jsonc)",
-    run: () => fileExists("site/site.jsonc"),
+    description: "site config must exist (site.jsonc)",
+    run: () => fileExists("site.jsonc"),
   },
   {
-    description: "tailwind input must exist (site/styles/tailwind.css)",
-    run: () => fileExists("site/styles/tailwind.css"),
+    description: "tailwind input must exist (styles/tailwind.css)",
+    run: () => fileExists("styles/tailwind.css"),
   },
   {
-    description: "site source UI entry must exist (site/src/ui/layout.tsx)",
-    run: () => fileExists("site/src/ui/layout.tsx"),
+    description: "source UI entry must exist (src/ui/layout.tsx)",
+    run: () => fileExists("src/ui/layout.tsx"),
   },
 ];
 

package/templates/default/scripts/check.ts

@@ -36,11 +36,11 @@ const LINT_TARGETS = [
   ".oxlintrc.json",
   ".oxfmtrc.jsonc",
   "scripts",
-  "site/src",
-  "site/content",
-  "site/assets",
-  "site/styles",
-  "site/site.jsonc",
+  "src",
+  "content",
+  "assets",
+  "styles",
+  "site.jsonc",
 ];
 const ROOT_TEST_FILE_PATTERNS = [
   "*.test.ts",
@@ -78,7 +78,7 @@ const NESTED_TEST_FILE_PATTERNS = [
   "**/*_spec_*.js",
   "**/*_spec_*.jsx",
 ];
-const TEST_SOURCE_DIRS = ["site", "scripts", "src", "tests"];
+const TEST_SOURCE_DIRS = ["content", "scripts", "src", "tests"];
 
 const buildScopedTestFilePatterns = (): string[] => {
   const patterns = [...ROOT_TEST_FILE_PATTERNS];

package/templates/default/src/runtime/live-reload.ts

@@ -0,0 +1,18 @@
+(() => {
+  const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+  const socket = new WebSocket(
+    `${protocol}//${location.host}/_idcmd/live-reload`
+  );
+
+  socket.addEventListener("message", (event) => {
+    if (event.data === "reload") {
+      location.reload();
+    }
+  });
+
+  socket.addEventListener("close", () => {
+    setTimeout(() => {
+      location.reload();
+    }, 1000);
+  });
+})();

package/templates/default/src/runtime/llm-menu.ts

@@ -0,0 +1,162 @@
+const COPY_SELECTOR = 'a[data-copy-markdown="1"]';
+const LABEL_SELECTOR = '[data-copy-markdown-label="1"]';
+const RESET_DELAY_MS = 2000;
+
+const setLinkDisabled = (link: HTMLAnchorElement, disabled: boolean): void => {
+  if (disabled) {
+    link.setAttribute("aria-disabled", "true");
+    link.style.pointerEvents = "none";
+    link.style.opacity = "0.8";
+    return;
+  }
+
+  link.removeAttribute("aria-disabled");
+  link.style.pointerEvents = "";
+  link.style.opacity = "";
+};
+
+const setLinkLabel = (link: HTMLAnchorElement, next: string): void => {
+  const label = link.querySelector(LABEL_SELECTOR);
+  if (label) {
+    label.textContent = next;
+  }
+};
+
+const toAbsoluteUrl = (href: string): string => {
+  try {
+    return new URL(href, window.location.href).toString();
+  } catch {
+    return href;
+  }
+};
+
+const createHiddenTextarea = (text: string): HTMLTextAreaElement => {
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.setAttribute("readonly", "true");
+  textarea.style.position = "fixed";
+  textarea.style.left = "-9999px";
+  textarea.style.top = "0";
+  return textarea;
+};
+
+const safeExecCommandCopy = (): boolean => {
+  try {
+    return document.execCommand("copy");
+  } catch {
+    return false;
+  }
+};
+
+const copyViaExecCommand = (text: string): boolean => {
+  const textarea = createHiddenTextarea(text);
+  document.body.append(textarea);
+  textarea.focus();
+  textarea.select();
+  const ok = safeExecCommandCopy();
+  textarea.remove();
+  return ok;
+};
+
+const copyText = async (text: string): Promise<boolean> => {
+  const { clipboard } = navigator;
+  if (clipboard?.writeText) {
+    try {
+      await clipboard.writeText(text);
+      return true;
+    } catch {
+      // Fall back below.
+    }
+  }
+
+  return copyViaExecCommand(text);
+};
+
+const closeMenuIfPresent = (link: HTMLAnchorElement): void => {
+  const details = link.closest("details");
+  if (details instanceof HTMLDetailsElement) {
+    details.open = false;
+  }
+};
+
+const getOriginalLabel = (link: HTMLAnchorElement): string =>
+  link.querySelector(LABEL_SELECTOR)?.textContent ??
+  "Copy Markdown to Clipboard";
+
+const fetchMarkdownText = async (href: string): Promise<string | null> => {
+  const res = await fetch(toAbsoluteUrl(href), { credentials: "same-origin" });
+  if (!res.ok) {
+    return null;
+  }
+  return res.text();
+};
+
+const copyMarkdownFromHref = async (href: string): Promise<boolean> => {
+  try {
+    const text = await fetchMarkdownText(href);
+    if (!text) {
+      return false;
+    }
+    return copyText(text);
+  } catch {
+    return false;
+  }
+};
+
+const startCopyOperation = (link: HTMLAnchorElement): void => {
+  setLinkDisabled(link, true);
+  setLinkLabel(link, "Copying...");
+};
+
+const finishCopyOperation = (link: HTMLAnchorElement, ok: boolean): void => {
+  setLinkLabel(link, ok ? "Copied" : "Copy failed");
+  closeMenuIfPresent(link);
+};
+
+const scheduleResetOperation = (
+  link: HTMLAnchorElement,
+  originalLabel: string
+): void => {
+  window.setTimeout(() => {
+    setLinkLabel(link, originalLabel);
+    setLinkDisabled(link, false);
+  }, RESET_DELAY_MS);
+};
+
+const handleCopyClick = async (
+  link: HTMLAnchorElement,
+  originalLabel: string
+): Promise<void> => {
+  const href = link.getAttribute("href");
+  if (!href) {
+    return;
+  }
+
+  startCopyOperation(link);
+  const ok = await copyMarkdownFromHref(href);
+  finishCopyOperation(link, ok);
+  scheduleResetOperation(link, originalLabel);
+};
+
+const attachCopyHandler = (link: HTMLAnchorElement): void => {
+  const originalLabel = getOriginalLabel(link);
+  link.addEventListener("click", async (event) => {
+    event.preventDefault();
+    if (link.getAttribute("aria-disabled") === "true") {
+      return;
+    }
+    await handleCopyClick(link, originalLabel);
+  });
+};
+
+const initCopyMarkdownButtons = (): void => {
+  const links = [...document.querySelectorAll(COPY_SELECTOR)].filter(
+    (link): link is HTMLAnchorElement => link instanceof HTMLAnchorElement
+  );
+
+  for (const link of links) {
+    attachCopyHandler(link);
+  }
+};
+
+initCopyMarkdownButtons();

package/templates/default/src/runtime/nav-prefetch.ts

@@ -0,0 +1,30 @@
+(() => {
+  const selector = 'a[data-prefetch="hover"][href]';
+  const prefetched = new Set<string>();
+
+  const prefetch = (href: string | null | undefined): void => {
+    if (!href || prefetched.has(href)) {
+      return;
+    }
+    prefetched.add(href);
+
+    const link = document.createElement("link");
+    link.rel = "prefetch";
+    link.href = href;
+    document.head.append(link);
+  };
+
+  const onOver = (event: Event): void => {
+    const { target } = event;
+    if (!(target instanceof Element)) {
+      return;
+    }
+    const link = target.closest(selector);
+    if (!(link instanceof HTMLAnchorElement)) {
+      return;
+    }
+    prefetch(link.href);
+  };
+
+  document.addEventListener("mouseover", onOver, { passive: true });
+})();

package/templates/default/src/runtime/right-rail-scrollspy.ts

@@ -0,0 +1,303 @@
+const TOC_ROOT_SELECTOR = '[data-toc-root="1"]';
+const TOC_LINK_SELECTOR = 'a[data-toc-link="1"][href^="#"]';
+const TOC_SCROLL_CONTAINER_SELECTOR = '[data-toc-scroll-container="1"]';
+
+const NAVBAR_GAP_PX = 16;
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(Math.max(value, min), max);
+
+const getTopOffset = (): number => {
+  const header = document.querySelector("header");
+  const headerHeight = header?.getBoundingClientRect().height ?? 0;
+  return Math.ceil(headerHeight + NAVBAR_GAP_PX);
+};
+
+const decodeAnchorId = (href: string | null): string | null => {
+  if (!href?.startsWith("#")) {
+    return null;
+  }
+
+  const raw = href.slice(1);
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+};
+
+interface TocEntry {
+  heading: HTMLElement;
+  link: HTMLAnchorElement;
+  y: number;
+}
+
+const toEntry = (link: HTMLAnchorElement): TocEntry | null => {
+  const id = decodeAnchorId(link.getAttribute("href"));
+  if (!id) {
+    return null;
+  }
+
+  // ids like "11-overview" are valid HTML ids but invalid CSS selectors unless escaped.
+  // eslint-disable-next-line unicorn/prefer-query-selector
+  const heading = document.getElementById(id);
+  if (!heading) {
+    return null;
+  }
+
+  return { heading, link, y: 0 };
+};
+
+const buildEntries = (tocRoot: Element): TocEntry[] =>
+  [...tocRoot.querySelectorAll(TOC_LINK_SELECTOR)]
+    .filter(
+      (link): link is HTMLAnchorElement => link instanceof HTMLAnchorElement
+    )
+    .map(toEntry)
+    .filter((entry): entry is TocEntry => entry !== null);
+
+const measureEntries = (entries: TocEntry[]): void => {
+  for (const entry of entries) {
+    entry.y = entry.heading.getBoundingClientRect().top + window.scrollY;
+  }
+};
+
+const setScrollMarginTop = (topOffset: number): void => {
+  document.documentElement.style.setProperty(
+    "--scroll-margin-top",
+    `${topOffset}px`
+  );
+};
+
+const binarySearchLastAtOrAbove = (
+  entries: TocEntry[],
+  anchorLine: number
+): number => {
+  let lo = 0;
+  let hi = entries.length;
+
+  // Find the first entry with y > anchorLine, then step back one.
+  while (lo < hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    const midY = entries[mid]?.y ?? Number.POSITIVE_INFINITY;
+    if (midY <= anchorLine) {
+      lo = mid + 1;
+    } else {
+      hi = mid;
+    }
+  }
+
+  return lo - 1;
+};
+
+const findActiveIndex = (entries: TocEntry[], topOffset: number): number => {
+  const anchorLine = window.scrollY + topOffset + 1;
+  const best = binarySearchLastAtOrAbove(entries, anchorLine);
+  return Math.max(0, best);
+};
+
+const parseTransformValues = (transform: string, prefix: string): number[] =>
+  transform
+    .slice(prefix.length, -1)
+    .split(",")
+    .map((value) => Number.parseFloat(value.trim()));
+
+const getNumberAtIndex = (values: number[], index: number): number => {
+  const value = values[index] ?? Number.NaN;
+  return Number.isFinite(value) ? value : 0;
+};
+
+const getMatrix3dTranslateY = (values: number[]): number =>
+  getNumberAtIndex(values, 13);
+
+const getMatrixTranslateY = (values: number[]): number =>
+  getNumberAtIndex(values, 5);
+
+const getComputedTranslateY = (element: Element): number => {
+  const { transform } = window.getComputedStyle(element);
+  if (!transform || transform === "none") {
+    return 0;
+  }
+
+  if (transform.startsWith("matrix3d(")) {
+    const values = parseTransformValues(transform, "matrix3d(");
+    return getMatrix3dTranslateY(values);
+  }
+
+  if (transform.startsWith("matrix(")) {
+    const values = parseTransformValues(transform, "matrix(");
+    return getMatrixTranslateY(values);
+  }
+
+  return 0;
+};
+
+const setTranslateY = (element: HTMLElement, next: number): void => {
+  element.style.transform = `translate3d(0, ${next}px, 0)`;
+};
+
+const getElementCenterY = (element: Element): number => {
+  const rect = element.getBoundingClientRect();
+  return rect.top + rect.height / 2;
+};
+
+const getCenteredTranslateY = (
+  scrollContainer: HTMLElement,
+  list: HTMLElement,
+  link: HTMLAnchorElement
+): number => {
+  const containerHeight = scrollContainer.clientHeight;
+  const listHeight = list.scrollHeight;
+
+  if (listHeight <= containerHeight + 1) {
+    return 0;
+  }
+
+  const delta = getElementCenterY(scrollContainer) - getElementCenterY(link);
+  const currentTranslate = getComputedTranslateY(list);
+  const minTranslate = containerHeight - listHeight;
+  return clamp(currentTranslate + delta, minTranslate, 0);
+};
+
+interface ScrollSpyState {
+  activeIndex: number;
+  centerActiveItem: boolean;
+  entries: TocEntry[];
+  isTicking: boolean;
+  scrollContainer: HTMLElement | null;
+  tocList: HTMLElement | null;
+  topOffset: number;
+}
+
+const centerLinkIfNeeded = (
+  state: ScrollSpyState,
+  link: HTMLAnchorElement
+): void => {
+  const { scrollContainer, tocList } = state;
+  if (!scrollContainer || !tocList) {
+    return;
+  }
+
+  const next = getCenteredTranslateY(scrollContainer, tocList, link);
+  const current = getComputedTranslateY(tocList);
+  if (Math.abs(current - next) < 0.5) {
+    return;
+  }
+
+  setTranslateY(tocList, next);
+};
+
+const setCurrentLocationAttr = (entry: TocEntry | undefined): void => {
+  if (!entry) {
+    return;
+  }
+  entry.link.setAttribute("aria-current", "location");
+};
+
+const setActiveLink = (state: ScrollSpyState, index: number): void => {
+  if (index === state.activeIndex) {
+    return;
+  }
+
+  const previous = state.entries[state.activeIndex];
+  previous?.link.removeAttribute("aria-current");
+
+  state.activeIndex = index;
+  const current = state.entries[state.activeIndex];
+  setCurrentLocationAttr(current);
+
+  if (state.centerActiveItem && current) {
+    centerLinkIfNeeded(state, current.link);
+  }
+};
+
+const updateActive = (state: ScrollSpyState): void => {
+  setActiveLink(state, findActiveIndex(state.entries, state.topOffset));
+};
+
+const scheduleUpdate = (state: ScrollSpyState): void => {
+  if (state.isTicking) {
+    return;
+  }
+
+  state.isTicking = true;
+  requestAnimationFrame(() => {
+    state.isTicking = false;
+    updateActive(state);
+  });
+};
+
+const refreshLayout = (state: ScrollSpyState): void => {
+  state.topOffset = getTopOffset();
+  setScrollMarginTop(state.topOffset);
+  measureEntries(state.entries);
+  updateActive(state);
+
+  if (state.centerActiveItem) {
+    const current = state.entries[state.activeIndex];
+    if (current) {
+      centerLinkIfNeeded(state, current.link);
+    }
+  }
+};
+
+const createState = (): ScrollSpyState | null => {
+  const { body } = document;
+  const tocRoot = document.querySelector(TOC_ROOT_SELECTOR);
+  const entries = tocRoot ? buildEntries(tocRoot) : [];
+  if (
+    !body ||
+    body.dataset.scrollspy !== "1" ||
+    !tocRoot ||
+    entries.length === 0
+  ) {
+    return null;
+  }
+
+  const centerActiveItem = body.dataset.scrollspyCenter === "1";
+  const scrollContainer = tocRoot.querySelector(TOC_SCROLL_CONTAINER_SELECTOR);
+  const tocList = scrollContainer?.querySelector("ul") ?? null;
+
+  return {
+    activeIndex: -1,
+    centerActiveItem,
+    entries,
+    isTicking: false,
+    scrollContainer:
+      scrollContainer instanceof HTMLElement ? scrollContainer : null,
+    tocList: tocList instanceof HTMLElement ? tocList : null,
+    topOffset: getTopOffset(),
+  };
+};
+
+const start = (state: ScrollSpyState): void => {
+  // Disable independent TOC scrolling whenever scrollspy is active.
+  // The TOC list position is controlled by JS (either centered or left as-is).
+  document.body.dataset.tocFollow = "1";
+
+  window.addEventListener("scroll", () => scheduleUpdate(state), {
+    passive: true,
+  });
+  window.addEventListener("resize", () => refreshLayout(state));
+  window.addEventListener("load", () => {
+    refreshLayout(state);
+    setTimeout(() => refreshLayout(state), 250);
+    setTimeout(() => refreshLayout(state), 1000);
+  });
+
+  refreshLayout(state);
+};
+
+const init = (): void => {
+  const state = createState();
+  if (!state) {
+    return;
+  }
+
+  start(state);
+};
+
+init();

package/templates/default/{site/src → src}/server.ts

@@ -1,4 +1,4 @@
 // Optional: this file is here as the obvious place to put server-side code.
-// V1 runs the built-in idcmd server; add custom endpoints via `site/src/routes/**`.
+// V1 runs the built-in idcmd server; add custom endpoints via `src/routes/**`.
 
 export const serverPlaceholder = true;

package/templates/default/{site/src → src}/ui/layout.tsx

@@ -104,7 +104,7 @@ const TopNavbar = ({
       <div class="flex items-center gap-4">
         <a
           href="/"
-          class="text-sm font-mono font-medium tracking-tight md:hidden"
+          class="text-sm font-mono font-medium tracking-tight lg:hidden"
           data-prefetch="hover"
         >
           <span class="text-muted-foreground">~/</span>

package/templates/default/{site/styles → styles}/tailwind.css

@@ -151,7 +151,7 @@ header {
   display: none;
 }
 
-@media (min-width: 768px) {
+@media (min-width: 1024px) {
   .sidebar {
     position: fixed;
     top: 0;
@@ -185,7 +185,7 @@ header {
   flex-direction: column;
 }
 
-@media (min-width: 768px) {
+@media (min-width: 1024px) {
   .main-wrapper {
     margin-left: var(--sidebar-width);
   }