@opendatalabs/darshana 1.3.0 → 1.4.0

package/README.md

@@ -7,7 +7,7 @@ Crawl any web app and generate a labeled PDF, HTML viewer, or image set for desi
 ## Try it now
 
 ```bash
-npx @opendatalabs/darshana --url https://vana.org --public
+npx @opendatalabs/darshana --url https://vana.org --public --max-pages 10
 ```
 
 Output lands in `./darshana-output/` — a PDF and a self-contained HTML viewer with sidebar nav, filters, and keyboard navigation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/darshana",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Crawl any web app and generate a labeled PDF, HTML viewer, or image set for design review.",
   "type": "module",
   "bin": {

package/src/auth.mjs

@@ -7,7 +7,7 @@ const AUTH_MAX_AGE_MS = 12 * 60 * 60 * 1000;
 export async function ensureAuth(config) {
   if (config.public === true) {
     console.log('[auth] Public app — skipping auth.');
-    return null;
+    return { storageStatePath: null, authCaptures: [] };
   }
 
   const storagePath = config.authStorage;
@@ -18,7 +18,7 @@ export async function ensureAuth(config) {
     if (ageMs < AUTH_MAX_AGE_MS) {
       const ageMin = Math.round(ageMs / 60000);
       console.log(`[auth] Using cached auth (${ageMin}m old): ${storagePath}`);
-      return storagePath;
+      return { storageStatePath: storagePath, authCaptures: [] };
     }
     console.log('[auth] Cached auth is stale (>12h) — re-authenticating.');
   }
@@ -31,25 +31,77 @@ export async function ensureAuth(config) {
       throw new Error(`authScript must export a default function, got: ${typeof fn}`);
     }
     const browser = await chromium.launch({ headless: true });
+    let storagePath;
     try {
       const result = await fn(browser);
       if (typeof result !== 'string') {
         throw new Error('authScript must return a storageState file path string');
       }
-      return result;
+      storagePath = result;
     } finally {
       await browser.close();
     }
+
+    // Post-auth verification screenshot using the saved storageState
+    const authCaptures = [];
+    try {
+      console.log('[auth] Capturing post-auth landing page...');
+      const verifyBrowser = await chromium.launch({ headless: true });
+      try {
+        const verifyContext = await verifyBrowser.newContext({ storageState: storagePath });
+        const verifyPage = await verifyContext.newPage();
+        const landingUrl = config.url + (config.start ?? '/');
+        await verifyPage.goto(landingUrl, { waitUntil: 'networkidle', timeout: 30000 });
+        const imageBuffer = await verifyPage.screenshot({ fullPage: true, type: 'png' });
+        authCaptures.push({
+          url: verifyPage.url(),
+          pathname: '/_auth/landing',
+          theme: 'system',
+          viewport: 'desktop',
+          section: 'auth',
+          label: 'Auth · post-login landing',
+          imageBuffer,
+        });
+        await verifyPage.close();
+        await verifyContext.close();
+      } finally {
+        await verifyBrowser.close();
+      }
+    } catch (err) {
+      console.warn(`[auth] WARNING: post-auth screenshot failed: ${err.message}`);
+    }
+
+    return { storageStatePath: storagePath, authCaptures };
   }
 
   console.log('\n[auth] Launching headed browser for manual login...');
   console.log(`[auth] Navigate to: ${config.url}`);
   console.log('[auth] Log in, then press ENTER here to capture session.\n');
 
+  const startPath = config.start ?? '/';
+  const startUrl = config.url + startPath;
+
   const browser = await chromium.launch({ headless: false });
   const context = await browser.newContext();
   const page = await context.newPage();
-  await page.goto(config.url);
+  await page.goto(startUrl, { waitUntil: 'load' });
+
+  // Pre-auth screenshot (captures the login/redirect page)
+  let preAuthCapture = null;
+  try {
+    const preAuthImageBuffer = await page.screenshot({ fullPage: true, type: 'png' });
+    preAuthCapture = {
+      url: page.url(),
+      pathname: '/_auth/login',
+      theme: 'system',
+      viewport: 'desktop',
+      section: 'auth',
+      label: 'Auth · login page',
+      imageBuffer: preAuthImageBuffer,
+    };
+  } catch (err) {
+    console.warn(`[auth] WARNING: pre-auth screenshot failed: ${err.message}`);
+  }
 
   await waitForEnter();
 
@@ -58,7 +110,41 @@ export async function ensureAuth(config) {
   await browser.close();
 
   console.log('[auth] Session saved.\n');
-  return storagePath;
+
+  // Post-auth verification screenshot using a new page with saved storageState
+  let postAuthCapture = null;
+  try {
+    console.log('[auth] Capturing post-auth landing page...');
+    const verifyBrowser = await chromium.launch({ headless: true });
+    try {
+      const verifyContext = await verifyBrowser.newContext({ storageState: storagePath });
+      const verifyPage = await verifyContext.newPage();
+      await verifyPage.goto(startUrl, { waitUntil: 'networkidle', timeout: 30000 });
+      const postAuthImageBuffer = await verifyPage.screenshot({ fullPage: true, type: 'png' });
+      postAuthCapture = {
+        url: verifyPage.url(),
+        pathname: '/_auth/landing',
+        theme: 'system',
+        viewport: 'desktop',
+        section: 'auth',
+        label: 'Auth · post-login landing',
+        imageBuffer: postAuthImageBuffer,
+      };
+      await verifyPage.close();
+      await verifyContext.close();
+    } finally {
+      await verifyBrowser.close();
+    }
+  } catch (err) {
+    console.warn(`[auth] WARNING: post-auth screenshot failed: ${err.message}`);
+  }
+
+  const authCaptures = [
+    ...(preAuthCapture ? [preAuthCapture] : []),
+    ...(postAuthCapture ? [postAuthCapture] : []),
+  ];
+
+  return { storageStatePath: storagePath, authCaptures };
 }
 
 function waitForEnter() {

package/src/html.mjs

@@ -13,26 +13,78 @@ export async function assembleHtml(pages, config, outputDir) {
     return `img[data-viewport="${vp}"] { width: ${cssWidth}; max-width: ${preset.width}px; }`;
   }).join('\n    ');
 
-  const navItems = [];
+  const authPages = pages.filter(p => p.section === 'auth');
+  const appPages = pages.filter(p => p.section !== 'auth');
+  const hasAuthCaptures = authPages.length > 0;
+
   const pageSections = [];
 
   pages.forEach((capture, i) => {
     const idx = i + 1;
     const pageId = `page-${idx}`;
     const base64 = capture.imageBuffer.toString('base64');
+    const sectionAttr = capture.section === 'auth' ? ' data-section="auth"' : '';
 
-    navItems.push(
-      `<li data-theme="${escHtml(capture.theme)}" data-viewport="${escHtml(capture.viewport)}"><a href="#${pageId}" data-theme="${escHtml(capture.theme)}" data-viewport="${escHtml(capture.viewport)}">${escHtml(capture.label)}</a></li>`
-    );
-
-    pageSections.push(`<div class="page" id="${pageId}" data-theme="${escHtml(capture.theme)}" data-viewport="${escHtml(capture.viewport)}">
+    pageSections.push(`<div class="page" id="${pageId}" data-theme="${escHtml(capture.theme)}" data-viewport="${escHtml(capture.viewport)}"${sectionAttr}>
       <div class="label"><span class="idx">${idx}</span>${escHtml(capture.label)}</div>
-      <img src="data:image/png;base64,${base64}" alt="${escHtml(capture.label)}" data-viewport="${escHtml(capture.viewport)}" loading="lazy">
+      <img src="data:image/png;base64,${base64}" alt="${escHtml(capture.label)}" data-viewport="${escHtml(capture.viewport)}"${sectionAttr} loading="lazy">
     </div>`);
   });
 
-  const themes = [...new Set(pages.map(p => p.theme))];
-  const viewports = [...new Set(pages.map(p => p.viewport))];
+  // Build sidebar nav items
+  let navHtml;
+  if (hasAuthCaptures) {
+    // Auth group
+    const authItems = [];
+    pages.forEach((capture, i) => {
+      if (capture.section !== 'auth') return;
+      const idx = i + 1;
+      const pageId = `page-${idx}`;
+      authItems.push(
+        `<li data-section="auth"><a href="#${pageId}">${escHtml(capture.label)}</a></li>`
+      );
+    });
+
+    // Pages group
+    const pageItems = [];
+    pages.forEach((capture, i) => {
+      if (capture.section === 'auth') return;
+      const idx = i + 1;
+      const pageId = `page-${idx}`;
+      pageItems.push(
+        `<li data-theme="${escHtml(capture.theme)}" data-viewport="${escHtml(capture.viewport)}"><a href="#${pageId}" data-theme="${escHtml(capture.theme)}" data-viewport="${escHtml(capture.viewport)}">${escHtml(capture.label)}</a></li>`
+      );
+    });
+
+    navHtml = `
+      <div class="section-group">
+        <div class="section-header" onclick="toggleSection(this)">
+          <span class="chevron">&#9660;</span> Auth
+        </div>
+        <ul class="section-list">
+          ${authItems.join('\n          ')}
+        </ul>
+      </div>
+      <div class="section-group">
+        <div class="section-header" onclick="toggleSection(this)">
+          <span class="chevron">&#9660;</span> Pages
+        </div>
+        <ul class="section-list" id="pages-section-list">
+          ${pageItems.join('\n          ')}
+        </ul>
+      </div>`;
+  } else {
+    // Flat nav — same as original behavior
+    const flatItems = pages.map((capture, i) => {
+      const idx = i + 1;
+      const pageId = `page-${idx}`;
+      return `<li data-theme="${escHtml(capture.theme)}" data-viewport="${escHtml(capture.viewport)}"><a href="#${pageId}" data-theme="${escHtml(capture.theme)}" data-viewport="${escHtml(capture.viewport)}">${escHtml(capture.label)}</a></li>`;
+    });
+    navHtml = `<ul id="nav-list">\n      ${flatItems.join('\n      ')}\n    </ul>`;
+  }
+
+  const themes = [...new Set(appPages.map(p => p.theme))];
+  const viewports = [...new Set(appPages.map(p => p.viewport))];
 
   const themeCheckboxes = themes.map(t =>
     `<label><input type="checkbox" data-filter="theme" value="${escHtml(t)}" checked> ${escHtml(t)}</label>`
@@ -64,6 +116,19 @@ export async function assembleHtml(pages, config, outputDir) {
     #nav-list li a:hover, #nav-list li a.active { background: #1e1e1e; color: #fff; }
     #nav-list li[data-hidden] { display: none; }
 
+    .section-group { flex-shrink: 0; }
+    .section-header { position: sticky; top: 0; background: #111; z-index: 1; padding: 8px 16px; font-size: 10px; font-weight: 600; color: #888; text-transform: uppercase; letter-spacing: 0.08em; border-bottom: 1px solid #2a2a2a; cursor: pointer; user-select: none; display: flex; align-items: center; gap: 6px; }
+    .section-header:hover { color: #bbb; }
+    .section-header .chevron { font-size: 8px; transition: transform 0.15s; display: inline-block; }
+    .section-header.collapsed .chevron { transform: rotate(-90deg); }
+    .section-list { list-style: none; margin: 0; padding: 4px 0; }
+    .section-list.collapsed { display: none; }
+    .section-list li a { display: block; padding: 5px 16px; font-size: 11px; color: #666; text-decoration: none; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .section-list li a:hover, .section-list li a.active { background: #1e1e1e; color: #fff; }
+    .section-list li[data-hidden] { display: none; }
+    .section-list li[data-section="auth"] a { color: #7a8aaa; }
+    .section-list li[data-section="auth"] a:hover { color: #aab8d4; background: #1e1e1e; }
+
     #content { margin-left: 240px; flex: 1; padding: 32px; min-width: 0; }
     .cover { padding: 48px 0 40px; border-bottom: 1px solid #2a2a2a; margin-bottom: 48px; }
     .cover h1 { font-size: 1.75rem; margin: 0 0 8px; font-weight: 600; }
@@ -73,6 +138,7 @@ export async function assembleHtml(pages, config, outputDir) {
     .page[data-hidden] { display: none; }
     .label { background: #0d0d0d; border: 1px solid #2a2a2a; border-bottom: none; padding: 8px 14px; font-size: 12px; color: #ccc; font-family: 'SF Mono', 'Fira Code', monospace; display: flex; align-items: center; gap: 10px; border-radius: 6px 6px 0 0; }
     .label .idx { background: #2a2a2a; color: #888; padding: 1px 6px; border-radius: 3px; font-size: 10px; min-width: 24px; text-align: center; }
+    .page[data-section="auth"] .label { background: #0d0f1a; border-color: #2a2e42; color: #9aadcc; }
     .page img { display: block; border: 1px solid #2a2a2a; border-radius: 0 0 6px 6px; box-shadow: 0 4px 24px rgba(0,0,0,0.4); }
     img[data-viewport="mobile"] { border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.5); }
 
@@ -94,9 +160,7 @@ export async function assembleHtml(pages, config, outputDir) {
       <div class="filter-group-label" style="margin-top:10px">Viewport</div>
       ${viewportCheckboxes}
     </div>
-    <ul id="nav-list">
-      ${navItems.join('\n      ')}
-    </ul>
+    ${navHtml}
   </nav>
   <main id="content">
     <div class="cover">
@@ -107,15 +171,30 @@ export async function assembleHtml(pages, config, outputDir) {
     ${pageSections.join('\n    ')}
   </main>
   <script>
+    function toggleSection(header) {
+      header.classList.toggle('collapsed');
+      const list = header.nextElementSibling;
+      if (list && list.classList.contains('section-list')) {
+        list.classList.toggle('collapsed');
+      }
+    }
+
     function applyFilters() {
       const checked = { theme: new Set(), viewport: new Set() };
       document.querySelectorAll('input[data-filter]').forEach(cb => {
         if (cb.checked) checked[cb.dataset.filter].add(cb.value);
       });
-      document.querySelectorAll('.page').forEach((page, i) => {
+      document.querySelectorAll('.page').forEach(page => {
+        // Auth captures are always visible — not part of the theme/viewport matrix
+        if (page.dataset.section === 'auth') return;
         const visible = checked.theme.has(page.dataset.theme) && checked.viewport.has(page.dataset.viewport);
         page.toggleAttribute('data-hidden', !visible);
-        document.querySelectorAll('#nav-list li')[i]?.toggleAttribute('data-hidden', !visible);
+        // Also hide/show the corresponding nav item in the Pages section list
+        const link = document.querySelector('.section-list a[href="#' + page.id + '"]');
+        if (link) link.closest('li')?.toggleAttribute('data-hidden', !visible);
+        // Flat nav fallback
+        const flatLink = document.querySelector('#nav-list a[href="#' + page.id + '"]');
+        if (flatLink) flatLink.closest('li')?.toggleAttribute('data-hidden', !visible);
       });
     }
     document.querySelectorAll('input[data-filter]').forEach(cb => cb.addEventListener('change', applyFilters));
@@ -129,8 +208,8 @@ export async function assembleHtml(pages, config, outputDir) {
       else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') currentIdx = Math.max(currentIdx - 1, 0);
       else return;
       ps[currentIdx].scrollIntoView({ behavior: 'smooth', block: 'start' });
-      document.querySelectorAll('#nav-list li a').forEach(a => a.classList.remove('active'));
-      const link = document.querySelector('#nav-list li a[href="#' + ps[currentIdx].id + '"]');
+      document.querySelectorAll('.section-list li a, #nav-list li a').forEach(a => a.classList.remove('active'));
+      const link = document.querySelector('a[href="#' + ps[currentIdx].id + '"]');
       if (link) { link.classList.add('active'); link.scrollIntoView({ block: 'nearest' }); }
     });
 
@@ -138,7 +217,7 @@ export async function assembleHtml(pages, config, outputDir) {
       entries.forEach(entry => {
         if (entry.isIntersecting && !entry.target.hasAttribute('data-hidden')) {
           const id = entry.target.id;
-          document.querySelectorAll('#nav-list li a').forEach(a => {
+          document.querySelectorAll('.section-list li a, #nav-list li a').forEach(a => {
             a.classList.toggle('active', a.getAttribute('href') === '#' + id);
           });
         }

package/src/index.mjs

@@ -315,7 +315,7 @@ function runMain() {
       config = configFromArgs(args);
     }
 
-    const storageStatePath = await ensureAuth(config);
+    const { storageStatePath, authCaptures } = await ensureAuth(config);
     config._storageStatePath = storageStatePath;
 
     printConfigSummary(config);
@@ -365,7 +365,9 @@ function runMain() {
 
     console.log(`\n[darshana] Captured ${captures.length} page(s).`);
 
-    if (captures.length === 0) {
+    const allCaptures = [...authCaptures, ...captures];
+
+    if (allCaptures.length === 0) {
       console.error('[darshana] No pages captured. Exiting.');
       process.exit(1);
     }
@@ -376,15 +378,15 @@ function runMain() {
     const outputs = config.outputs ?? ['pdf', 'html'];
 
     if (outputs.includes('pdf')) {
-      await assemblePdf(captures, config, outputDir);
+      await assemblePdf(allCaptures, config, outputDir);
     }
 
     if (outputs.includes('html')) {
-      await assembleHtml(captures, config, outputDir);
+      await assembleHtml(allCaptures, config, outputDir);
     }
 
     if (outputs.includes('images')) {
-      await writeImages(captures, outputDir);
+      await writeImages(allCaptures, outputDir);
     }
 
     console.log('\n[darshana] Done.');

package/src/pdf.mjs

@@ -4,6 +4,7 @@ import { PDFDocument, rgb, StandardFonts } from 'pdf-lib';
 
 const HEADER_HEIGHT = 28;
 const HEADER_BG = rgb(0, 0, 0);
+const HEADER_BG_AUTH = rgb(0.25, 0.25, 0.35);
 const HEADER_FG = rgb(1, 1, 1);
 const FONT_SIZE = 11;
 
@@ -49,8 +50,9 @@ export async function assemblePdf(pages, config, outputDir) {
       page.drawImage(img, { x: 0, y: 0, width: pgWidth, height: imgHeight });
 
       // Header bar at top (y=0 is bottom in pdf-lib, so header sits at y=imgHeight)
+      const headerColor = capture.section === 'auth' ? HEADER_BG_AUTH : HEADER_BG;
       page.drawRectangle({
-        x: 0, y: imgHeight, width: pgWidth, height: HEADER_HEIGHT, color: HEADER_BG,
+        x: 0, y: imgHeight, width: pgWidth, height: HEADER_HEIGHT, color: headerColor,
       });
       page.drawText(capture.label, {
         x: 8, y: imgHeight + 8, font, size: FONT_SIZE, color: HEADER_FG, maxWidth: pgWidth - 16,