@raystack/chronicle 0.12.0 → 0.12.1

package/dist/cli/index.js

@@ -71,6 +71,29 @@ var init_image_utils = () => {};
 // src/lib/remark-resolve-images.ts
 import path4 from "node:path";
 import { visit } from "unist-util-visit";
+function parseImageParams(src) {
+  const qIdx = src.indexOf("?");
+  if (qIdx === -1)
+    return { base: src, params: {} };
+  const base = src.slice(0, qIdx);
+  const search = new URLSearchParams(src.slice(qIdx + 1));
+  const params = {};
+  if (search.has("w"))
+    params.w = Number.parseInt(search.get("w"), 10);
+  if (search.has("q"))
+    params.q = Number.parseInt(search.get("q"), 10);
+  return { base, params };
+}
+function appendParams(url, params) {
+  if (!params.w && !params.q)
+    return url;
+  const qs = new URLSearchParams;
+  if (params.w)
+    qs.set("w", String(params.w));
+  if (params.q)
+    qs.set("q", String(params.q));
+  return `${url}?${qs}`;
+}
 function resolveUrl(src, dir) {
   const normalized = src.replace(/\\/g, "/");
   if (/^[a-z][a-z0-9+\-.]*:/i.test(normalized))
@@ -86,9 +109,12 @@ function resolveUrl(src, dir) {
   return `/_content/${path4.posix.normalize(path4.posix.join(dir, normalized))}`;
 }
 function optimizeUrl(url, optimize) {
-  if (optimize && isLocalImage(url) && !isSvg(url))
-    return buildOptimizedUrl(url, DEFAULT_WIDTH);
-  return url;
+  const { base, params } = parseImageParams(url);
+  const width = params.w || DEFAULT_WIDTH;
+  const quality = params.q;
+  if (optimize && isLocalImage(base) && !isSvg(base))
+    return buildOptimizedUrl(base, width, quality);
+  return base;
 }
 var remarkResolveImages = (options) => {
   const optimize = options?.optimize ?? true;
@@ -112,15 +138,17 @@ var remarkResolveImages = (options) => {
     visit(tree, "image", (node) => {
       if (!node.url)
         return;
-      node.url = resolveUrl(node.url, dir);
-      collect(node.url);
-      node.url = optimizeUrl(node.url, optimize);
+      const { base, params } = parseImageParams(node.url);
+      const resolved = resolveUrl(base, dir);
+      collect(resolved);
+      node.url = optimizeUrl(appendParams(resolved, params), optimize);
     });
     visit(tree, "html", (node) => {
       node.value = node.value.replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (_, before, src, after) => {
-        const resolved = resolveUrl(src, dir);
+        const { base, params } = parseImageParams(src);
+        const resolved = resolveUrl(base, dir);
         collect(resolved);
-        return `${before}${optimizeUrl(resolved, optimize)}${after}`;
+        return `${before}${optimizeUrl(appendParams(resolved, params), optimize)}${after}`;
       });
     });
     visit(tree, (node) => {
@@ -132,9 +160,10 @@ var remarkResolveImages = (options) => {
       const srcAttr = jsx.attributes.find((a) => a.type === "mdxJsxAttribute" && a.name === "src");
       if (!srcAttr?.value || typeof srcAttr.value !== "string")
         return;
-      srcAttr.value = resolveUrl(srcAttr.value, dir);
-      collect(srcAttr.value);
-      srcAttr.value = optimizeUrl(srcAttr.value, optimize);
+      const { base: jsxBase, params: jsxParams } = parseImageParams(srcAttr.value);
+      const jsxResolved = resolveUrl(jsxBase, dir);
+      collect(jsxResolved);
+      srcAttr.value = optimizeUrl(appendParams(jsxResolved, jsxParams), optimize);
     });
     visit(tree, "element", (node) => {
       if (node.tagName !== "img")
@@ -142,9 +171,10 @@ var remarkResolveImages = (options) => {
       const src = node.properties?.src;
       if (typeof src !== "string")
         return;
-      node.properties.src = resolveUrl(src, dir);
-      collect(node.properties.src);
-      node.properties.src = optimizeUrl(node.properties.src, optimize);
+      const { base: elBase, params: elParams } = parseImageParams(src);
+      const elResolved = resolveUrl(elBase, dir);
+      collect(elResolved);
+      node.properties.src = optimizeUrl(appendParams(elResolved, elParams), optimize);
     });
     file.data.images = images;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",

package/src/lib/remark-resolve-images.ts

@@ -7,6 +7,30 @@ import type { MdxJsxFlowElement, MdxJsxTextElement, MdxJsxAttribute } from 'mdas
 import { MdxNodeType } from './mdx-utils'
 import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from './image-utils'
 
+interface ImageParams {
+  w?: number
+  q?: number
+}
+
+function parseImageParams(src: string): { base: string; params: ImageParams } {
+  const qIdx = src.indexOf('?')
+  if (qIdx === -1) return { base: src, params: {} }
+  const base = src.slice(0, qIdx)
+  const search = new URLSearchParams(src.slice(qIdx + 1))
+  const params: ImageParams = {}
+  if (search.has('w')) params.w = Number.parseInt(search.get('w')!, 10)
+  if (search.has('q')) params.q = Number.parseInt(search.get('q')!, 10)
+  return { base, params }
+}
+
+function appendParams(url: string, params: ImageParams): string {
+  if (!params.w && !params.q) return url
+  const qs = new URLSearchParams()
+  if (params.w) qs.set('w', String(params.w))
+  if (params.q) qs.set('q', String(params.q))
+  return `${url}?${qs}`
+}
+
 function resolveUrl(src: string, dir: string): string {
   const normalized = src.replace(/\\/g, '/')
   if (/^[a-z][a-z0-9+\-.]*:/i.test(normalized)) return normalized
@@ -23,8 +47,11 @@ interface RemarkResolveImagesOptions {
 }
 
 function optimizeUrl(url: string, optimize: boolean): string {
-  if (optimize && isLocalImage(url) && !isSvg(url)) return buildOptimizedUrl(url, DEFAULT_WIDTH)
-  return url
+  const { base, params } = parseImageParams(url)
+  const width = params.w || DEFAULT_WIDTH
+  const quality = params.q
+  if (optimize && isLocalImage(base) && !isSvg(base)) return buildOptimizedUrl(base, width, quality)
+  return base
 }
 
 const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) => {
@@ -50,18 +77,20 @@ const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) =>
 
     visit(tree, 'image', (node: Image) => {
       if (!node.url) return
-      node.url = resolveUrl(node.url, dir)
-      collect(node.url)
-      node.url = optimizeUrl(node.url, optimize)
+      const { base, params } = parseImageParams(node.url)
+      const resolved = resolveUrl(base, dir)
+      collect(resolved)
+      node.url = optimizeUrl(appendParams(resolved, params), optimize)
     })
 
     visit(tree, 'html', (node: Html) => {
       node.value = node.value.replace(
         /(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi,
         (_, before, src, after) => {
-          const resolved = resolveUrl(src, dir)
+          const { base, params } = parseImageParams(src)
+          const resolved = resolveUrl(base, dir)
           collect(resolved)
-          return `${before}${optimizeUrl(resolved, optimize)}${after}`
+          return `${before}${optimizeUrl(appendParams(resolved, params), optimize)}${after}`
         }
       )
     })
@@ -72,18 +101,20 @@ const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) =>
       if (jsx.name !== 'img') return
       const srcAttr = jsx.attributes.find((a): a is MdxJsxAttribute => a.type === 'mdxJsxAttribute' && a.name === 'src')
       if (!srcAttr?.value || typeof srcAttr.value !== 'string') return
-      srcAttr.value = resolveUrl(srcAttr.value, dir)
-      collect(srcAttr.value)
-      srcAttr.value = optimizeUrl(srcAttr.value, optimize)
+      const { base: jsxBase, params: jsxParams } = parseImageParams(srcAttr.value)
+      const jsxResolved = resolveUrl(jsxBase, dir)
+      collect(jsxResolved)
+      srcAttr.value = optimizeUrl(appendParams(jsxResolved, jsxParams), optimize)
     })
 
     visit(tree, 'element', (node: Element) => {
       if (node.tagName !== 'img') return
       const src = node.properties?.src
       if (typeof src !== 'string') return
-      node.properties.src = resolveUrl(src, dir)
-      collect(node.properties.src as string)
-      node.properties.src = optimizeUrl(node.properties.src as string, optimize)
+      const { base: elBase, params: elParams } = parseImageParams(src)
+      const elResolved = resolveUrl(elBase, dir)
+      collect(elResolved)
+      node.properties.src = optimizeUrl(appendParams(elResolved, elParams), optimize)
     })
 
     file.data.images = images

package/src/server/api/image.test.ts

@@ -48,6 +48,12 @@ describe('cacheKey', () => {
     expect(a).not.toBe(b);
   });
 
+  test('returns different keys for different mtime', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp', 1000);
+    const b = cacheKey('/_content/img.png', 640, 75, 'webp', 2000);
+    expect(a).not.toBe(b);
+  });
+
   test('key ends with format extension', () => {
     expect(cacheKey('/_content/img.png', 640, 75, 'webp')).toMatch(/\.webp$/);
     expect(cacheKey('/_content/img.png', 640, 75, 'avif')).toMatch(/\.avif$/);

package/src/server/api/image.ts

@@ -6,10 +6,9 @@ import { useStorage } from 'nitro/storage'
 import sharp from 'sharp'
 import { StatusCodes } from 'http-status-codes'
 import { safePath } from '@/server/utils/safe-path'
-import { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_QUALITY } from '@/lib/image-utils'
+import { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_WIDTH, DEFAULT_QUALITY, isLocalImage, isSvg } from '@/lib/image-utils'
 
-const STORAGE_KEY = 'image-cache'
-const MAX_CACHE_ENTRIES = 500
+export const STORAGE_KEY = 'image-cache'
 
 const inflight = new Map<string, Promise<Buffer>>()
 
@@ -29,8 +28,8 @@ export const MIME: Record<string, string> = {
   '.webp': 'image/webp',
 }
 
-export function cacheKey(url: string, w: number, q: number, format: OutputFormat): string {
-  const hash = crypto.createHash('sha256').update(`${url}:${w}:${q}:${format}`).digest('hex').slice(0, 16)
+export function cacheKey(url: string, w: number, q: number, format: OutputFormat, mtime?: number): string {
+  const hash = crypto.createHash('sha256').update(`${url}:${w}:${q}:${format}:${mtime ?? 0}`).digest('hex').slice(0, 16)
   return `${hash}.${format}`
 }
 
@@ -42,11 +41,17 @@ function snapQuality(q: number): number {
   return closest;
 }
 
-async function evictIfNeeded(storage: ReturnType<typeof useStorage>) {
-  const keys = await storage.getKeys()
-  if (keys.length <= MAX_CACHE_ENTRIES) return
-  const toRemove = keys.slice(0, keys.length - MAX_CACHE_ENTRIES)
-  await Promise.all(toRemove.map(k => storage.removeItem(k)))
+export async function optimizeImage(
+  filePath: string,
+  w: number,
+  q: number,
+  format: OutputFormat,
+): Promise<Buffer> {
+  const source = await fs.readFile(filePath);
+  const pipeline = sharp(source).resize({ width: w, withoutEnlargement: true });
+  if (format === 'avif') return pipeline.avif({ quality: q }).toBuffer();
+  if (format === 'webp') return pipeline.webp({ quality: q }).toBuffer();
+  return pipeline.toBuffer();
 }
 
 export default defineHandler(async event => {
@@ -90,7 +95,11 @@ export default defineHandler(async event => {
   const originalMime = MIME[ext] ?? 'application/octet-stream'
   const contentType = format === 'original' ? originalMime : `image/${format}`
 
-  const key = cacheKey(url, w, q, format)
+  const stat = await fs.stat(filePath).catch(() => null)
+  if (!stat) {
+    throw new HTTPError({ status: StatusCodes.NOT_FOUND, message: 'Not Found' })
+  }
+  const key = cacheKey(url, w, q, format, stat.mtimeMs)
 
   const cached = await storage.getItemRaw<Buffer>(key)
   if (cached) {
@@ -116,16 +125,8 @@ export default defineHandler(async event => {
   }
 
   const work = (async () => {
-    const source = await fs.readFile(filePath)
-    const pipeline = sharp(source).resize({ width: w, withoutEnlargement: true })
-    const optimized = format === 'avif'
-      ? await pipeline.avif({ quality: q }).toBuffer()
-      : format === 'webp'
-        ? await pipeline.webp({ quality: q }).toBuffer()
-        : await pipeline.toBuffer()
-
+    const optimized = await optimizeImage(filePath, w, q, format)
     await storage.setItemRaw(key, optimized)
-    await evictIfNeeded(storage)
     return optimized
   })()
 
@@ -154,3 +155,45 @@ export default defineHandler(async event => {
     inflight.delete(key)
   }
 })
+
+export async function warmupImageCache() {
+  const { getPages, getPageImages } = await import('@/lib/source');
+  // biome-ignore lint/correctness/useHookAtTopLevel: useStorage is a Nitro DI accessor, not a React hook
+  const storage = useStorage(STORAGE_KEY);
+  const contentDir = __CHRONICLE_CONTENT_DIR__;
+  const format = 'webp' as const;
+  const w = DEFAULT_WIDTH;
+  const q = DEFAULT_QUALITY;
+
+  const pages = await getPages();
+  const seen = new Set<string>();
+  let warmed = 0;
+
+  for (const page of pages) {
+    for (const url of getPageImages(page)) {
+      if (!isLocalImage(url) || isSvg(url) || seen.has(url)) continue;
+      seen.add(url);
+
+      const relativePath = url.replace(/^\/_content\//, '');
+      const filePath = safePath(contentDir, `/${relativePath}`);
+      if (!filePath) continue;
+
+      const stat = await fs.stat(filePath).catch(() => null);
+      if (!stat) continue;
+
+      const key = cacheKey(url, w, q, format, stat.mtimeMs);
+      const cached = await storage.getItemRaw(key);
+      if (cached) continue;
+
+      try {
+        const optimized = await optimizeImage(filePath, w, q, format);
+        await storage.setItemRaw(key, optimized);
+        warmed++;
+      } catch { /* skip unprocessable */ }
+    }
+  }
+
+  if (warmed > 0) {
+    console.log(`[image-warmup] cached ${warmed} images as webp@${w}w`);
+  }
+}

package/src/server/api/ready.ts

@@ -1,9 +1,11 @@
 import { defineHandler } from 'nitro';
 import { ensureIndex, isSearchReady } from './search';
+import { warmupImageCache } from './image';
 import { LATEST_CONTEXT } from '@/lib/version-source';
 
 export default defineHandler(async () => {
   ensureIndex(LATEST_CONTEXT).catch(e => console.error('[search:index]', e));
+  warmupImageCache().catch(e => console.error('[image-warmup]', e));
 
   if (!isSearchReady()) {
     return new Response(JSON.stringify({ status: 'not_ready', search: false }), {

package/src/themes/default/Layout.module.css

@@ -76,7 +76,9 @@
 
 .topLinks {
   width: 100%;
-  margin-bottom: var(--rs-space-7);
+  display: flex;
+  flex-direction: column;
+  gap: 0;
 }
 
 .topLinkItem {
@@ -135,7 +137,7 @@
 .cardWrapper {
   flex: 1;
   display: flex;
-  padding: 0 0 var(--rs-space-2) 0;
+  padding: 0;
   min-height: 0;
   background: var(--rs-color-background-base-secondary);
 }
@@ -154,7 +156,7 @@
   align-items: center;
   justify-content: space-between;
   height: var(--navbar-height);
-  padding: var(--rs-space-4) var(--rs-space-7);
+  padding: var(--rs-space-4) var(--rs-space-8);
   background: var(--rs-color-background-base-primary);
   border-bottom: 0.5px solid var(--rs-color-border-base-primary);
   backdrop-filter: blur(1px);
@@ -172,7 +174,7 @@
 
 .groupItems {
   padding-left: 0;
-  padding-bottom: var(--rs-space-3);
+  padding-bottom: 0;
   gap: 0;
 }
 
@@ -190,6 +192,9 @@
 
 .navGroup .navGroupHeader {
   margin: 0;
+  margin-bottom: 0;
+  padding-top: 0;
+  padding-bottom: 0;
 }
 
 .navGroup[data-depth='1'] .navGroupHeader {

package/src/themes/default/Layout.tsx

@@ -62,8 +62,6 @@ function renderConfigIcon(
   return <img src={icon} alt={alt} className={styles.configIcon} />;
 }
 
-let savedScrollTop = 0;
-
 export function Layout({
   children,
   config,
@@ -97,22 +95,20 @@ export function Layout({
   );
 
   useEffect(() => {
-    const el = scrollRef.current;
-    if (!el) return;
-    const onScroll = () => {
-      savedScrollTop = el.scrollTop;
-    };
-    el.addEventListener('scroll', onScroll);
-    return () => el.removeEventListener('scroll', onScroll);
-  }, []);
-
-  useEffect(() => {
-    const el = scrollRef.current;
-    if (el)
-      requestAnimationFrame(() => {
-        el.scrollTop = savedScrollTop;
-      });
+    const timer = setTimeout(() => {
+      const container = document.querySelector<HTMLElement>(`.${styles.sidebarMain}`);
+      if (!container) return;
+      const allActive = container.querySelectorAll<HTMLElement>('[data-active="true"]');
+      const activeItem = allActive[allActive.length - 1];
+      if (!activeItem) return;
+      const containerRect = container.getBoundingClientRect();
+      const itemRect = activeItem.getBoundingClientRect();
+      if (itemRect.top < containerRect.top || itemRect.bottom > containerRect.bottom) {
+        container.scrollTop += itemRect.top - containerRect.top - containerRect.height / 2 + itemRect.height / 2;
+      }
+    }, 100);
     setMobileSidebarOpen(false);
+    return () => clearTimeout(timer);
   }, [pathname]);
 
   return (
@@ -436,6 +432,7 @@ function ApiSidebarNode({ item, pathname }: { item: Node; pathname: string }) {
       align='center'
       gap={3}
       className={`${styles.apiItem} ${isActive ? styles.apiItemActive : ''}`}
+      data-active={isActive}
       render={<RouterLink to={href} />}
     >
       <span className={styles.apiItemName}>{item.name}</span>