@opendatalabs/darshana 1.2.1 → 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.
@@ -27,6 +27,11 @@ npm install -g @opendatalabs/darshana
 
 Chromium is installed automatically. Or skip the install entirely and use `npx @opendatalabs/darshana`.
 
+**Linux only:** if Chromium fails to launch, you may be missing system libraries. Fix with:
+```bash
+sudo npx playwright install chromium --with-deps
+```
+
 ## CLI reference
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendatalabs/darshana",
-  "version": "1.2.1",
+  "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/capture.mjs

@@ -7,6 +7,8 @@ export async function captureAll(browser, config, urls) {
   const results = [];
   const themes = config.capture.themes;
   const viewportNames = config.capture.viewports;
+  const total = urls.length * themes.length * viewportNames.length;
+  const counter = { n: 0 };
 
   for (const viewportName of viewportNames) {
     for (const theme of themes) {
@@ -20,7 +22,7 @@ export async function captureAll(browser, config, urls) {
         ...(storageStatePath ? { storageState: storageStatePath } : {}),
       };
 
-      console.log(`\n[capture] Segment: ${viewportName} / ${theme} (${urls.length} URLs)`);
+      console.log(`\n[capture] Starting segment ${viewportName}/${theme} (${urls.length} URLs)`);
       const context = await browser.newContext(contextOpts);
 
       for (const url of urls) {
@@ -31,20 +33,23 @@ export async function captureAll(browser, config, urls) {
 
         const effectiveThemes = override?.themes;
         if (effectiveThemes && !effectiveThemes.includes(theme)) {
-          console.log(`  [capture] skip ${pathname} [${theme}] (override)`);
+          counter.n++;
+          console.log(`  [capture] ${counter.n}/${total} skip ${pathname} [${theme}] (override)`);
           continue;
         }
         const effectiveViewports = override?.viewports;
         if (effectiveViewports && !effectiveViewports.includes(viewportName)) {
-          console.log(`  [capture] skip ${pathname} [${viewportName}] (override)`);
+          counter.n++;
+          console.log(`  [capture] ${counter.n}/${total} skip ${pathname} [${viewportName}] (override)`);
           continue;
         }
 
         const delay = override?.delay ?? config.capture.delay ?? 400;
         const waitFor = override?.waitFor ?? config.capture.waitFor ?? null;
         const label = makeLabel(pathname, viewportName, theme);
+        counter.n++;
 
-        console.log(`  [capture] ${label}`);
+        console.log(`  [capture] ${counter.n}/${total}  ${label}`);
         const page = await context.newPage();
 
         try {
@@ -96,14 +101,14 @@ export async function captureAll(browser, config, urls) {
 
           results.push({ url, pathname, theme, viewport: viewportName, imageBuffer, label });
         } catch (err) {
-          console.error(`  [capture] FAILED ${pathname}: ${err.message}`);
+          console.error(`  [capture] ${counter.n}/${total}  FAILED ${pathname}: ${err.message}`);
         } finally {
           await page.close();
         }
       }
 
       await context.close();
-      console.log(`[capture] Segment done: ${viewportName} / ${theme}`);
+      console.log(`[capture] Segment done: ${viewportName}/${theme}`);
     }
   }
 

package/src/config.mjs

@@ -6,6 +6,33 @@ export const VIEWPORT_PRESETS = {
   mobile:  { width: 390,  height: 844, deviceScaleFactor: 2 },
 };
 
+const KNOWN_TOP_LEVEL_KEYS = ['title', 'url', 'start', 'public', 'authStorage', 'authScript', 'crawl', 'capture', 'pdf', 'outputs', 'outputDir'];
+const KNOWN_CRAWL_KEYS = ['include', 'exclude', 'maxDepth', 'maxPages', 'extraRoutes', 'routes'];
+const KNOWN_CAPTURE_KEYS = ['themes', 'viewports', 'fullPage', 'delay', 'waitFor', 'contextOptions', 'launchOptions', 'playwrightOptions', 'routeOptions', 'overrides'];
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => i === 0 ? j : j === 0 ? i : 0));
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+function warnUnknownKeys(obj, knownKeys, section) {
+  if (!obj || typeof obj !== 'object') return;
+  for (const key of Object.keys(obj)) {
+    if (!knownKeys.includes(key)) {
+      const best = knownKeys.reduce((acc, k) => { const d = levenshtein(key, k); return d < acc.d ? { k, d } : acc; }, { k: null, d: Infinity });
+      const prefix = section ? `[darshana] Warning: unknown config field "${section}.${key}"` : `[darshana] Warning: unknown config field "${key}"`;
+      const suffix = best.d <= 3 ? ` — did you mean "${section ? section + '.' : ''}${best.k}"?` : '';
+      console.warn(prefix + suffix);
+    }
+  }
+}
+
 export function loadConfig(configPath) {
   const absConfigPath = path.resolve(configPath);
   const configDir = path.dirname(absConfigPath);
@@ -25,6 +52,10 @@ export function loadConfig(configPath) {
 // Build a config object from a plain object (used by both loadConfig and CLI --url mode).
 // configDir is used to resolve relative paths; defaults to cwd when not loading from a file.
 export function buildConfig(raw, configDir = process.cwd()) {
+  // Validate unknown keys and emit typo hints
+  warnUnknownKeys(raw, KNOWN_TOP_LEVEL_KEYS, null);
+  warnUnknownKeys(raw.crawl, KNOWN_CRAWL_KEYS, 'crawl');
+  warnUnknownKeys(raw.capture, KNOWN_CAPTURE_KEYS, 'capture');
   const config = {
     title: raw.title ?? 'Design Review',
     url: raw.url.replace(/\/$/, ''),

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

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline';
+import { createRequire } from 'node:module';
 import { chromium } from 'playwright';
 import { loadConfig, buildConfig } from './config.mjs';
 import { ensureAuth } from './auth.mjs';
@@ -9,6 +11,9 @@ import { captureAll } from './capture.mjs';
 import { assemblePdf } from './pdf.mjs';
 import { assembleHtml } from './html.mjs';
 
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
 const USAGE = `
 Usage:
   darshana --url <url> [options]          # zero-config mode
@@ -36,6 +41,155 @@ Options:
   --auth-only              Save auth session and exit
 `.trim();
 
+// ── Config summary box ────────────────────────────────────────────────────────
+
+function printConfigSummary(config) {
+  const INNER = 48;
+  const authLabel = config.public
+    ? 'public'
+    : config.authScript
+      ? `script: ${path.basename(config.authScript)}`
+      : 'session file';
+
+  const rows = [
+    ['url',       config.url],
+    ['start',     config.start],
+    ['auth',      authLabel],
+    ['themes',    (config.capture.themes ?? ['system']).join(', ')],
+    ['viewports', (config.capture.viewports ?? ['desktop']).join(', ')],
+    ['maxPages',  `${config.crawl.maxPages}  maxDepth  ${config.crawl.maxDepth}`],
+    ['outputs',   (config.outputs ?? ['pdf', 'html']).join(', ')],
+    ['outputDir', config.outputDir ?? './darshana-output'],
+  ];
+
+  // Compute column widths
+  const keyWidth = Math.max(...rows.map(([k]) => k.length));
+  const valWidth = INNER - keyWidth - 2; // 2 = space + space
+
+  function trunc(s, max) {
+    const str = String(s);
+    return str.length > max ? str.slice(0, max - 1) + '…' : str;
+  }
+
+  function pad(s, len) { return s + ' '.repeat(Math.max(0, len - s.length)); }
+
+  const topLabel = ' darshana ';
+  const topLineLen = INNER + 2; // borders
+  const dashLen = topLineLen - topLabel.length - 2; // -2 for corner chars
+  const dashLeft = Math.floor(dashLen / 2);
+  const dashRight = dashLen - dashLeft;
+
+  console.log(`┌${'─'.repeat(dashLeft)}${topLabel}${'─'.repeat(dashRight)}┐`);
+  for (const [k, v] of rows) {
+    const paddedKey = pad(k, keyWidth);
+    const truncVal = trunc(v, valWidth);
+    const paddedVal = pad(truncVal, valWidth);
+    console.log(`│ ${paddedKey} ${paddedVal} │`);
+  }
+  console.log(`└${'─'.repeat(INNER)}┘`);
+}
+
+// ── init subcommand ───────────────────────────────────────────────────────────
+
+async function runInit() {
+  const configPath = path.join(process.cwd(), 'review.config.json');
+
+  // Build an `ask` function that works for both TTY and piped stdin.
+  // For piped input: readline fires 'close' as soon as the pipe ends, breaking
+  // sequential question() calls. We buffer all lines upfront and serve them.
+  // For interactive TTY: use readline.question() normally.
+  const ask = await makeAsker();
+
+  if (fs.existsSync(configPath)) {
+    const overwrite = await ask('review.config.json already exists. Overwrite? (y/N): ');
+    if (overwrite.trim().toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+  }
+
+  // 1. URL
+  let url;
+  while (true) {
+    const raw = await ask('App URL (e.g. https://myapp.example.com): ');
+    try { url = new URL(raw.trim()).href.replace(/\/$/, ''); break; }
+    catch { console.log('  Invalid URL. Please include the scheme (https://).'); }
+  }
+  const hostname = new URL(url).hostname;
+
+  // 2. Title
+  const titleRaw = await ask(`Title (default: ${hostname}): `);
+  const title = titleRaw.trim() || hostname;
+
+  // 3. Auth
+  const authRaw = await ask('Is the app public? (y/N): ');
+  const isPublic = authRaw.trim().toLowerCase() === 'y';
+
+  // 4. Start path
+  const startRaw = await ask('Start path (default: /): ');
+  const start = startRaw.trim() || '/';
+
+  // 5. Viewports
+  const vpRaw = await ask('Viewports — desktop, mobile, or both? (default: desktop): ');
+  const vpInput = vpRaw.trim().toLowerCase() || 'desktop';
+  let viewports;
+  if (vpInput === 'both') viewports = ['desktop', 'mobile'];
+  else if (vpInput === 'mobile') viewports = ['mobile'];
+  else viewports = ['desktop'];
+
+  // 6. Themes
+  const themeRaw = await ask('Themes — system, dark, light, or multiple? (default: system): ');
+  const themeInput = themeRaw.trim() || 'system';
+  let themes;
+  if (themeInput === 'multiple' || themeInput.includes(',')) {
+    themes = themeInput === 'multiple'
+      ? ['dark', 'light']
+      : themeInput.split(',').map(s => s.trim()).filter(Boolean);
+  } else {
+    themes = [themeInput];
+  }
+
+  // 7. Output dir
+  const outRaw = await ask('Output directory (default: ./darshana-output): ');
+  const outputDir = outRaw.trim() || './darshana-output';
+
+  const config = {
+    title,
+    url,
+    start,
+    public: isPublic,
+    capture: { viewports, themes },
+    outputDir,
+  };
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  console.log('✓ review.config.json created. Run: darshana --config review.config.json');
+  process.exit(0);
+}
+
+// Returns an `ask(question)` function.
+// TTY mode: wraps readline.question for interactive line editing.
+// Piped mode: buffers all stdin lines first, then serves them sequentially.
+async function makeAsker() {
+  if (process.stdin.isTTY) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return (q) => new Promise(resolve => rl.question(q, answer => { resolve(answer); }));
+  }
+  // Non-TTY: read all lines from stdin before asking anything
+  const lines = await new Promise(resolve => {
+    const buf = [];
+    const rl = readline.createInterface({ input: process.stdin });
+    rl.on('line', l => buf.push(l));
+    rl.on('close', () => resolve(buf));
+  });
+  let idx = 0;
+  return (q) => {
+    const answer = lines[idx++] ?? '';
+    console.log(`${q}${answer}`);
+    return Promise.resolve(answer);
+  };
+}
+
 function parseArgs(argv) {
   const args = {
     config: null,
@@ -82,6 +236,7 @@ function parseArgs(argv) {
     if (a === '--route')        { args.route = next(); continue; }
     if (a === '--auth-only')    { args.authOnly = true; continue; }
     if (a === '--help' || a === '-h') { console.log(USAGE); process.exit(0); }
+    if (a === '--version' || a === '-v') { console.log(`darshana ${pkg.version}`); process.exit(0); }
     console.error(`Unknown argument: ${a}\n\n${USAGE}`);
     process.exit(1);
   }
@@ -136,95 +291,111 @@ function applyCliOverrides(config, args) {
   return config;
 }
 
-const args = parseArgs(process.argv.slice(2));
-
-if (!args.config && !args.url) {
-  console.error('Error: --url or --config is required\n\n' + USAGE);
-  process.exit(1);
+// Dispatch init before parseArgs so we don't need --url
+if (process.argv[2] === 'init') {
+  runInit();
+} else {
+  runMain();
 }
 
-async function main() {
-  let config;
-  if (args.config) {
-    config = loadConfig(args.config);
-    config = applyCliOverrides(config, args);
-  } else {
-    config = configFromArgs(args);
+function runMain() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.config && !args.url) {
+    console.error('Error: --url or --config is required\n\n' + USAGE);
+    process.exit(1);
   }
 
-  console.log(`[darshana] ${config.title} — ${config.url}`);
+  async function main() {
+    let config;
+    if (args.config) {
+      config = loadConfig(args.config);
+      config = applyCliOverrides(config, args);
+    } else {
+      config = configFromArgs(args);
+    }
+
+    const { storageStatePath, authCaptures } = await ensureAuth(config);
+    config._storageStatePath = storageStatePath;
 
-  const storageStatePath = await ensureAuth(config);
-  config._storageStatePath = storageStatePath;
+    printConfigSummary(config);
 
-  if (args.authOnly) {
-    console.log('[darshana] --auth-only done.');
-    process.exit(0);
-  }
+    if (args.authOnly) {
+      console.log('[darshana] --auth-only done.');
+      process.exit(0);
+    }
 
-  let urls;
-  if (args.route) {
-    const fullUrl = args.route.startsWith('http') ? args.route : config.url + args.route;
-    urls = [fullUrl];
-    console.log(`[darshana] --route mode: ${fullUrl}`);
-  } else {
-    const crawlBrowser = await chromium.launch({ headless: true });
-    const crawlContextOpts = storageStatePath ? { storageState: storageStatePath } : {};
-    const crawlContext = await crawlBrowser.newContext(crawlContextOpts);
+    let urls;
+    if (args.route) {
+      const fullUrl = args.route.startsWith('http') ? args.route : config.url + args.route;
+      urls = [fullUrl];
+      console.log(`[darshana] --route mode: ${fullUrl}`);
+    } else {
+      const crawlBrowser = await chromium.launch({ headless: true });
+      const crawlContextOpts = storageStatePath ? { storageState: storageStatePath } : {};
+      const crawlContext = await crawlBrowser.newContext(crawlContextOpts);
+      try {
+        console.log(`[darshana] Crawling from ${config.url}${config.start} ...`);
+        urls = await crawl(crawlContext, config);
+      } finally {
+        await crawlContext.close();
+        await crawlBrowser.close();
+      }
+      console.log(`[darshana] Crawl complete: ${urls.length} URLs found.`);
+    }
+
+    if (args.dryRun) {
+      console.log('\n[darshana] --dry-run: discovered URLs:');
+      for (const u of urls) console.log(`  ${u}`);
+      process.exit(0);
+    }
+
+    const browser = await chromium.launch({
+      headless: true,
+      args: ['--no-sandbox', '--disable-setuid-sandbox'],
+      ...(config.capture.launchOptions ?? {}),
+    });
+
+    let captures;
     try {
-      console.log(`[darshana] Crawling from ${config.url}${config.start} ...`);
-      urls = await crawl(crawlContext, config);
+      captures = await captureAll(browser, config, urls);
     } finally {
-      await crawlContext.close();
-      await crawlBrowser.close();
+      await browser.close();
     }
-    console.log(`[darshana] Crawl complete: ${urls.length} URLs found.`);
-  }
 
-  if (args.dryRun) {
-    console.log('\n[darshana] --dry-run: discovered URLs:');
-    for (const u of urls) console.log(`  ${u}`);
-    process.exit(0);
-  }
+    console.log(`\n[darshana] Captured ${captures.length} page(s).`);
 
-  const browser = await chromium.launch({
-    headless: true,
-    args: ['--no-sandbox', '--disable-setuid-sandbox'],
-    ...(config.capture.launchOptions ?? {}),
-  });
+    const allCaptures = [...authCaptures, ...captures];
 
-  let captures;
-  try {
-    captures = await captureAll(browser, config, urls);
-  } finally {
-    await browser.close();
-  }
-
-  console.log(`\n[darshana] Captured ${captures.length} page(s).`);
+    if (allCaptures.length === 0) {
+      console.error('[darshana] No pages captured. Exiting.');
+      process.exit(1);
+    }
 
-  if (captures.length === 0) {
-    console.error('[darshana] No pages captured. Exiting.');
-    process.exit(1);
-  }
+    const outputDir = config.outputDir;
+    fs.mkdirSync(outputDir, { recursive: true });
 
-  const outputDir = config.outputDir;
-  fs.mkdirSync(outputDir, { recursive: true });
+    const outputs = config.outputs ?? ['pdf', 'html'];
 
-  const outputs = config.outputs ?? ['pdf', 'html'];
+    if (outputs.includes('pdf')) {
+      await assemblePdf(allCaptures, config, outputDir);
+    }
 
-  if (outputs.includes('pdf')) {
-    await assemblePdf(captures, config, outputDir);
-  }
+    if (outputs.includes('html')) {
+      await assembleHtml(allCaptures, config, outputDir);
+    }
 
-  if (outputs.includes('html')) {
-    await assembleHtml(captures, config, outputDir);
-  }
+    if (outputs.includes('images')) {
+      await writeImages(allCaptures, outputDir);
+    }
 
-  if (outputs.includes('images')) {
-    await writeImages(captures, outputDir);
+    console.log('\n[darshana] Done.');
   }
 
-  console.log('\n[darshana] Done.');
+  main().catch(err => {
+    console.error('[darshana] Fatal:', err);
+    process.exit(1);
+  });
 }
 
 async function writeImages(captures, outputDir) {
@@ -257,8 +428,3 @@ function slugifyPathname(pathname) {
     .replace(/^-|-$/g, '')
     || 'root';
 }
-
-main().catch(err => {
-  console.error('[darshana] Fatal:', err);
-  process.exit(1);
-});

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,