idcmd 0.0.7 → 0.0.9

package/src/server.ts

@@ -24,8 +24,8 @@ import {
 type ServerInstance = Server<undefined>;
 
 const project = await getProjectPaths();
-const PUBLIC_DIR = project.publicDir;
-const DIST_DIR = project.distDir;
+const ASSETS_DIR = project.assetsDir;
+const OUTPUT_DIR = project.outputDir;
 const isDev = process.env.NODE_ENV !== "production";
 const LIVE_RELOAD_POLL_MS = 250;
 const MIN_SEARCH_QUERY_LENGTH = 2;
@@ -185,7 +185,7 @@ const handleRequest = async (
     return undefined;
   }
 
-  const seoEnv = { distDir: DIST_DIR, isDev, staticCacheHeaders };
+  const seoEnv = { isDev, outputDir: OUTPUT_DIR, staticCacheHeaders };
   const searchPageEnv = {
     cacheHeaders,
     isDev,
@@ -193,9 +193,9 @@ const handleRequest = async (
     minQueryLength: MIN_SEARCH_QUERY_LENGTH,
   };
   const staticEnv = {
-    distDir: DIST_DIR,
+    assetsDir: ASSETS_DIR,
     isDev,
-    publicDir: PUBLIC_DIR,
+    outputDir: OUTPUT_DIR,
     staticCacheHeaders,
   };
   const userRoutesEnv = { isDev, routesDir: project.routesDir };

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/code/ui/` (`layout.tsx`, `right-rail.tsx`, `search-page.tsx`)
-- Code: `site/code/runtime/` browser runtime TS (`*_idcmd` scripts compile from here)
-- Code: `site/code/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`
-- Generated output: `dist/` (`dist/styles.css`, `dist/_idcmd/*.js`, built pages)
+- 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/code`, treat `dist/` 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/code/ui/` and `site/code/runtime/`.
-Runtime files in `site/code/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)
 
@@ -49,4 +49,4 @@ Runtime files in `site/code/runtime/` are compiled automatically by `idcmd dev`
 bun run build
 ```
 
-This produces a static `dist/` directory for Vercel.
+This produces a static `public/` directory for Vercel.

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 code UI entry must exist (site/code/ui/layout.tsx)",
-    run: () => fileExists("site/code/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/code",
-  "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/code → 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/code/routes/**`.
+// V1 runs the built-in idcmd server; add custom endpoints via `src/routes/**`.
 
 export const serverPlaceholder = true;

package/templates/default/vercel.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "buildCommand": "bun run build",
-  "outputDirectory": "dist",
+  "outputDirectory": "public",
   "installCommand": "bun install",
   "bunVersion": "1.x"
 }