@opendatalabs/darshana 1.0.0

package/README.md

@@ -0,0 +1,162 @@
+# darshana
+
+Crawl any web app and generate a labeled PDF, HTML viewer, or image set for AI-assisted design review.
+
+*Darśana* — Sanskrit for "the act of seeing clearly."
+
+## Install
+
+```bash
+npm install -g @opendatalabs/darshana
+# or use directly:
+npx @opendatalabs/darshana --config review.config.json
+```
+
+After installing, set up Playwright's browser:
+
+```bash
+npx playwright install chromium
+```
+
+## Quick start
+
+**1. Create a config file** (`review.config.json`):
+
+```json
+{
+  "title": "My App",
+  "url": "https://myapp.example.com",
+  "start": "/dashboard",
+  "public": false,
+  "authStorage": "./auth.json",
+  "crawl": {
+    "include": ["^/dashboard"],
+    "exclude": ["logout", "delete"],
+    "maxDepth": 3,
+    "maxPages": 50,
+    "extraRoutes": []
+  },
+  "capture": {
+    "themes": ["dark"],
+    "viewports": ["desktop", "mobile"],
+    "delay": 400
+  },
+  "outputs": ["pdf", "html"],
+  "outputDir": "./output"
+}
+```
+
+**2. Authenticate** (opens a browser — log in, press Enter):
+
+```bash
+npx darshana --config review.config.json --auth-only
+```
+
+Or provide an `authScript` for headless login (see [examples/auth-example.mjs](examples/auth-example.mjs)).
+
+**3. Generate the review**:
+
+```bash
+npx darshana --config review.config.json
+```
+
+## Config reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `title` | string | `"Design Review"` | Title shown on cover page and HTML header |
+| `url` | string | required | Base URL of the app |
+| `start` | string | required | Path to start crawling from |
+| `public` | boolean | `false` | Skip auth entirely for public sites |
+| `authStorage` | string | `"./auth.json"` | Path to saved Playwright storageState |
+| `authScript` | string | — | Path to a JS file that handles login programmatically |
+| `outputs` | string[] | `["pdf"]` | Any of `"pdf"`, `"html"`, `"images"` |
+| `outputDir` | string | same dir as config | Directory for generated output files |
+
+### `crawl`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `include` | string[] | `[]` | Regex patterns — URL pathname must match all |
+| `exclude` | string[] | `[]` | Regex patterns — URL pathname must not match any |
+| `maxDepth` | number | `5` | Max BFS depth from start URL |
+| `maxPages` | number | `100` | Hard cap on total pages crawled |
+| `extraRoutes` | string[] | `[]` | Additional paths to capture (not crawled for links) |
+| `routes` | Route[] | `[]` | Per-pattern sampling rules (see Routes DSL) |
+
+### `capture`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `themes` | string[] | `["dark"]` | Theme names to capture — injected as `data-theme` + CSS class |
+| `viewports` | string[] | `["desktop"]` | `"desktop"` (1440×900) or `"mobile"` (390×844) |
+| `fullPage` | boolean | `true` | Capture full scrollable page height |
+| `delay` | number | `400` | ms to wait after page load before capture |
+| `waitFor` | string | — | CSS selector (prefix `$`) or JS expression to wait for |
+| `overrides` | Override[] | `[]` | Per-route capture overrides |
+| `contextOptions` | object | `{}` | Passed directly to `browser.newContext()` |
+| `launchOptions` | object | `{}` | Passed directly to `chromium.launch()` |
+| `playwrightOptions` | object | `{}` | Passed directly to `page.screenshot()` |
+| `routeOptions` | object | — | `{ blockPatterns: string[] }` — abort matching network requests |
+
+### Routes DSL
+
+Limit how many pages of each "shape" are captured. Uses Express-style `:param` notation.
+
+```json
+"routes": [
+  { "pattern": "/dashboard/records/:id", "sample": 1, "follow": false },
+  { "pattern": "/dashboard/runs/:id",    "sample": 2, "follow": false },
+  { "pattern": "/dashboard/**",          "follow": true }
+]
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `pattern` | string | required | Path pattern using `:param` and `/**` |
+| `sample` | number | unlimited | Max pages to visit matching this pattern |
+| `follow` | boolean | `true` | Whether to BFS-follow links on matching pages |
+
+Patterns are matched in order — first match wins.
+
+## Auth options
+
+**Headed handover** (default when no `authScript`): darshana opens a browser, you log in manually, press Enter — session is saved to `authStorage`. Sessions are reused for 12 hours.
+
+**Headless auth script**: Create a JS file that exports a default function:
+
+```javascript
+export default async function login(browser) {
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  await page.goto(process.env.APP_URL + '/login');
+  await page.fill('#password', process.env.APP_PASSWORD);
+  await page.click('button[type="submit"]');
+  await page.waitForURL(/\/dashboard/);
+  const storagePath = './auth.json';
+  await context.storageState({ path: storagePath });
+  await context.close();
+  return storagePath;
+}
+```
+
+Set `"authScript": "./my-auth.mjs"` in config.
+
+## CLI
+
+```bash
+darshana --config <path>          # run full pipeline
+darshana --config <path> --dry-run   # discover URLs without capturing
+darshana --config <path> --route /dashboard  # capture one route only
+darshana --config <path> --auth-only  # save auth session and exit
+```
+
+## Outputs
+
+- **`pdf`** — `<outputDir>/console-review.pdf` — labeled pages, cover page, one page per capture
+- **`html`** — `<outputDir>/console-review.html` — self-contained HTML with sidebar nav, filters, keyboard navigation, viewport-correct sizing
+- **`images`** — `<outputDir>/images/<viewport>/NNN-slug-theme.png` — individual screenshots grouped by viewport
+
+## License
+
+MIT

package/examples/auth-example.mjs

@@ -0,0 +1,32 @@
+/**
+ * Example authScript for a password-protected app.
+ * Configure in review.config.json as: "authScript": "./auth.mjs"
+ *
+ * This script receives a Playwright Browser instance, logs in,
+ * saves storageState to auth.json, and returns the path.
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+
+export default async function login(browser) {
+  const pw = process.env.APP_PASSWORD;
+  if (!pw) throw new Error('APP_PASSWORD env var required');
+
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+  // Customize these for your app:
+  await page.goto(process.env.APP_URL + '/login', { waitUntil: 'domcontentloaded', timeout: 30000 });
+  await page.fill('#password', pw);  // update selector for your login form
+  await Promise.all([
+    page.waitForURL(/\/dashboard/, { timeout: 30000 }),
+    page.click('button[type="submit"]'),
+  ]);
+
+  const storagePath = path.join(__dir, 'auth.json');
+  await context.storageState({ path: storagePath });
+  await context.close();
+  return storagePath;
+}

package/examples/pdpp.config.json

@@ -0,0 +1,46 @@
+{
+  "title": "PDPP Console",
+  "url": "https://pdpp.vivid.fish",
+  "start": "/dashboard",
+  "public": false,
+  "authScript": "./auth.mjs",
+  "crawl": {
+    "include": ["^/dashboard"],
+    "exclude": ["delete", "revoke", "logout", "disconnect"],
+    "maxDepth": 4,
+    "maxPages": 80,
+    "extraRoutes": ["/design-system"],
+    "routes": [
+      { "pattern": "/dashboard/records/add/static-secret/:connector", "sample": 1, "follow": false },
+      { "pattern": "/dashboard/records/add/browser-session/:connector", "sample": 1, "follow": false },
+      { "pattern": "/dashboard/connect/manual-upload/:connector", "sample": 1, "follow": false },
+      { "pattern": "/dashboard/records/:connector/:recordId", "sample": 1, "follow": false },
+      { "pattern": "/dashboard/records/:connector", "sample": 3, "follow": true },
+      { "pattern": "/dashboard/runs/:runId", "sample": 2, "follow": false },
+      { "pattern": "/dashboard/traces/:traceId", "sample": 2, "follow": false },
+      { "pattern": "/dashboard/grants/request", "follow": false },
+      { "pattern": "/dashboard/grants/packages/:packageId", "sample": 1, "follow": false },
+      { "pattern": "/dashboard/grants/:grantId", "sample": 2, "follow": false },
+      { "pattern": "/dashboard/**", "follow": true }
+    ]
+  },
+  "capture": {
+    "themes": ["dark", "light"],
+    "viewports": ["desktop", "mobile"],
+    "fullPage": true,
+    "delay": 400,
+    "routeOptions": {
+      "blockPatterns": ["analytics", "tracking", "hotjar", "intercom", "segment"]
+    },
+    "overrides": [
+      { "route": "^/design-system$", "themes": ["dark"], "viewports": ["desktop"] },
+      { "route": "/dashboard/records/", "delay": 1000 }
+    ]
+  },
+  "outputs": ["pdf", "html"],
+  "outputDir": "./output",
+  "pdf": {
+    "output": "./console-review.pdf",
+    "pageSize": "A4"
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@opendatalabs/darshana",
+  "version": "1.0.0",
+  "description": "Crawl any web app and generate a labeled PDF, HTML viewer, or image set for design review.",
+  "type": "module",
+  "bin": {
+    "darshana": "./src/index.mjs"
+  },
+  "files": [
+    "src/",
+    "examples/",
+    "README.md"
+  ],
+  "dependencies": {
+    "playwright": "^1.60.0",
+    "pdf-lib": "^1.17.1",
+    "path-to-regexp": "^8.0.0"
+  },
+  "devDependencies": {
+    "semantic-release": "^25.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/release-notes-generator": "^14.0.0",
+    "@semantic-release/npm": "^12.0.0",
+    "@semantic-release/github": "^10.0.0",
+    "conventional-changelog-conventionalcommits": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false,
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "keywords": [
+    "playwright",
+    "screenshot",
+    "pdf",
+    "html",
+    "design-review",
+    "crawler",
+    "darshana"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vana-com/darshana.git"
+  }
+}

package/src/auth.mjs

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import readline from 'node:readline';
+import { chromium } from 'playwright';
+
+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;
+  }
+
+  const storagePath = config.authStorage;
+
+  if (fs.existsSync(storagePath)) {
+    const stat = fs.statSync(storagePath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < AUTH_MAX_AGE_MS) {
+      const ageMin = Math.round(ageMs / 60000);
+      console.log(`[auth] Using cached auth (${ageMin}m old): ${storagePath}`);
+      return storagePath;
+    }
+    console.log('[auth] Cached auth is stale (>12h) — re-authenticating.');
+  }
+
+  if (config.authScript) {
+    console.log(`[auth] Running authScript: ${config.authScript}`);
+    const mod = await import(config.authScript);
+    const fn = mod.default;
+    if (typeof fn !== 'function') {
+      throw new Error(`authScript must export a default function, got: ${typeof fn}`);
+    }
+    const browser = await chromium.launch({ headless: true });
+    try {
+      const result = await fn(browser);
+      if (typeof result !== 'string') {
+        throw new Error('authScript must return a storageState file path string');
+      }
+      return result;
+    } finally {
+      await browser.close();
+    }
+  }
+
+  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 browser = await chromium.launch({ headless: false });
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  await page.goto(config.url);
+
+  await waitForEnter();
+
+  console.log(`[auth] Saving session to: ${storagePath}`);
+  await context.storageState({ path: storagePath });
+  await browser.close();
+
+  console.log('[auth] Session saved.\n');
+  return storagePath;
+}
+
+function waitForEnter() {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question('', () => {
+      rl.close();
+      resolve();
+    });
+  });
+}

package/src/capture.mjs

@@ -0,0 +1,121 @@
+import { VIEWPORT_PRESETS } from './config.mjs';
+
+const NEXTJS_HIDE_STYLE =
+  'nextjs-portal,[data-nextjs-toast],[data-nextjs-dialog],#__next-build-watcher{display:none!important}';
+
+export async function captureAll(browser, config, urls) {
+  const results = [];
+  const themes = config.capture.themes;
+  const viewportNames = config.capture.viewports;
+
+  for (const viewportName of viewportNames) {
+    for (const theme of themes) {
+      const vpPreset = VIEWPORT_PRESETS[viewportName] ?? { width: 1440, height: 900, deviceScaleFactor: 1 };
+      const storageStatePath = config._storageStatePath ?? null;
+
+      const contextOpts = {
+        viewport: { width: vpPreset.width, height: vpPreset.height },
+        deviceScaleFactor: vpPreset.deviceScaleFactor ?? 1,
+        ...(config.capture.contextOptions ?? {}),
+        ...(storageStatePath ? { storageState: storageStatePath } : {}),
+      };
+
+      console.log(`\n[capture] Segment: ${viewportName} / ${theme} (${urls.length} URLs)`);
+      const context = await browser.newContext(contextOpts);
+
+      for (const url of urls) {
+        let pathname;
+        try { pathname = new URL(url).pathname; } catch { pathname = url; }
+
+        const override = resolveOverride(config.capture.overrides, pathname);
+
+        const effectiveThemes = override?.themes;
+        if (effectiveThemes && !effectiveThemes.includes(theme)) {
+          console.log(`  [capture] skip ${pathname} [${theme}] (override)`);
+          continue;
+        }
+        const effectiveViewports = override?.viewports;
+        if (effectiveViewports && !effectiveViewports.includes(viewportName)) {
+          console.log(`  [capture] 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);
+
+        console.log(`  [capture] ${label}`);
+        const page = await context.newPage();
+
+        try {
+          const blockPatterns = config.capture.routeOptions?.blockPatterns ?? [];
+          if (blockPatterns.length > 0) {
+            await page.route('**/*', (route) => {
+              const reqUrl = route.request().url();
+              if (blockPatterns.some(pat => reqUrl.includes(pat))) {
+                route.abort();
+              } else {
+                route.continue();
+              }
+            });
+          }
+
+          await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
+          await page.addStyleTag({ content: NEXTJS_HIDE_STYLE }).catch(() => {});
+
+          await page.evaluate((t) => {
+            const html = document.documentElement;
+            html.setAttribute('data-theme', t);
+            if (t === 'dark') {
+              html.classList.add('dark');
+              html.classList.remove('light');
+            } else {
+              html.classList.add('light');
+              html.classList.remove('dark');
+            }
+          }, theme);
+
+          if (waitFor) {
+            if (waitFor.startsWith('$')) {
+              await page.waitForSelector(waitFor.slice(1), { timeout: 15000 });
+            } else {
+              await page.waitForFunction(waitFor, { timeout: 15000 });
+            }
+          }
+
+          if (delay > 0) await page.waitForTimeout(delay);
+
+          const imageBuffer = await page.screenshot({
+            fullPage: config.capture.fullPage ?? true,
+            type: 'png',
+            ...(config.capture.playwrightOptions ?? {}),
+          });
+
+          results.push({ url, pathname, theme, viewport: viewportName, imageBuffer, label });
+        } catch (err) {
+          console.error(`  [capture] FAILED ${pathname}: ${err.message}`);
+        } finally {
+          await page.close();
+        }
+      }
+
+      await context.close();
+      console.log(`[capture] Segment done: ${viewportName} / ${theme}`);
+    }
+  }
+
+  return results;
+}
+
+function resolveOverride(overrides, pathname) {
+  if (!overrides?.length) return null;
+  for (const ov of overrides) {
+    if (new RegExp(ov.route).test(pathname)) return ov;
+  }
+  return null;
+}
+
+function makeLabel(pathname, viewport, theme) {
+  const humanPath = pathname.replace(/^\//, '').replace(/-/g, ' ') || '/';
+  return `${humanPath}  ·  ${viewport}  ·  ${theme}`;
+}

package/src/config.mjs

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const VIEWPORT_PRESETS = {
+  desktop: { width: 1440, height: 900, deviceScaleFactor: 1 },
+  mobile:  { width: 390,  height: 844, deviceScaleFactor: 2 },
+};
+
+export function loadConfig(configPath) {
+  const absConfigPath = path.resolve(configPath);
+  const configDir = path.dirname(absConfigPath);
+
+  if (!fs.existsSync(absConfigPath)) {
+    throw new Error(`Config file not found: ${absConfigPath}`);
+  }
+
+  const raw = JSON.parse(fs.readFileSync(absConfigPath, 'utf8'));
+
+  if (!raw.url) throw new Error('Config missing required field: url');
+  if (!raw.start) throw new Error('Config missing required field: start');
+
+  const config = {
+    title: raw.title ?? 'Design Review',
+    url: raw.url.replace(/\/$/, ''),
+    start: raw.start,
+    public: raw.public ?? false,
+    authStorage: raw.authStorage ?? './auth.json',
+    authScript: raw.authScript ?? null,
+
+    crawl: {
+      include: raw.crawl?.include ?? [],
+      exclude: raw.crawl?.exclude ?? [],
+      maxDepth: raw.crawl?.maxDepth ?? 5,
+      maxPages: raw.crawl?.maxPages ?? 100,
+      extraRoutes: raw.crawl?.extraRoutes ?? [],
+      routes: raw.crawl?.routes ?? [],
+    },
+
+    capture: {
+      themes: raw.capture?.themes ?? ['dark'],
+      viewports: raw.capture?.viewports ?? ['desktop'],
+      fullPage: raw.capture?.fullPage ?? true,
+      delay: raw.capture?.delay ?? 400,
+      waitFor: raw.capture?.waitFor ?? null,
+      contextOptions: raw.capture?.contextOptions ?? {},
+      launchOptions: raw.capture?.launchOptions ?? {},
+      playwrightOptions: raw.capture?.playwrightOptions ?? {},
+      routeOptions: raw.capture?.routeOptions ?? null,
+      overrides: raw.capture?.overrides ?? [],
+    },
+
+    pdf: {
+      output: raw.pdf?.output ?? './console-review.pdf',
+      pageSize: raw.pdf?.pageSize ?? 'A4',
+    },
+
+    outputs: raw.outputs ?? ['pdf'],
+    outputDir: raw.outputDir ? path.resolve(configDir, raw.outputDir) : null,
+  };
+
+  config.authStorage = path.resolve(configDir, config.authStorage);
+  if (config.authScript) {
+    config.authScript = path.resolve(configDir, config.authScript);
+  }
+  config.pdf.output = path.resolve(configDir, config.pdf.output);
+
+  if (!config.outputDir) {
+    config.outputDir = path.dirname(config.pdf.output);
+  }
+
+  return config;
+}

package/src/crawl.mjs

@@ -0,0 +1,116 @@
+import { match } from 'path-to-regexp';
+
+// path-to-regexp v8 uses {*path} for catch-all wildcards; config uses /** for readability
+function toRegexpPattern(pattern) {
+  return pattern.replace(/\/\*\*$/, '/{*path}');
+}
+
+function compileRoutes(routes) {
+  return routes.map(route => ({
+    pattern: route.pattern,
+    matchFn: match(toRegexpPattern(route.pattern), { decode: decodeURIComponent }),
+    sample: route.sample ?? null,
+    follow: route.follow ?? true,
+  }));
+}
+
+export async function crawl(context, config) {
+  const origin = new URL(config.url).origin;
+  const startUrl = config.url + config.start;
+
+  const includePatterns = (config.crawl.include ?? []).map(r => new RegExp(r));
+  const excludePatterns = (config.crawl.exclude ?? []).map(r => new RegExp(r));
+  const compiledRoutes = compileRoutes(config.crawl.routes ?? []);
+  const seenShapes = new Map();
+
+  const visitedPathnames = new Set();
+  const queue = [{ url: startUrl, depth: 0 }];
+  const result = [];
+
+  function passesFilters(url) {
+    let pathname;
+    try { pathname = new URL(url).pathname; } catch { return false; }
+    if (includePatterns.length > 0 && !includePatterns.every(re => re.test(pathname))) return false;
+    if (excludePatterns.some(re => re.test(pathname))) return false;
+    return true;
+  }
+
+  function normalizeKey(url) {
+    try { return new URL(url).pathname; } catch { return url; }
+  }
+
+  function findRoute(url) {
+    let pathname;
+    try { pathname = new URL(url).pathname; } catch { return null; }
+    for (const route of compiledRoutes) {
+      if (route.matchFn(pathname)) return route;
+    }
+    return null;
+  }
+
+  while (queue.length > 0 && result.length < config.crawl.maxPages) {
+    const { url, depth } = queue.shift();
+    const key = normalizeKey(url);
+
+    if (visitedPathnames.has(key)) continue;
+    visitedPathnames.add(key);
+
+    if (!passesFilters(url)) continue;
+
+    const matchedRoute = findRoute(url);
+    let shouldFollow = true;
+
+    if (matchedRoute !== null) {
+      const visitCount = seenShapes.get(matchedRoute.pattern) ?? 0;
+      if (matchedRoute.sample !== null && visitCount >= matchedRoute.sample) {
+        // Over sample limit — skip entirely, don't visit, don't follow
+        continue;
+      }
+      result.push(url);
+      console.log(`  [crawl] ${url} (depth ${depth}) [${matchedRoute.pattern}]`);
+      seenShapes.set(matchedRoute.pattern, visitCount + 1);
+      shouldFollow = matchedRoute.follow;
+    } else {
+      // No route matched — visit and follow (existing behavior)
+      result.push(url);
+      console.log(`  [crawl] ${url} (depth ${depth})`);
+    }
+
+    // Don't load the page if we're not following links from it
+    if (!shouldFollow) continue;
+    if (depth >= config.crawl.maxDepth || result.length >= config.crawl.maxPages) continue;
+
+    const page = await context.newPage();
+    try {
+      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+      const hrefs = await page.$$eval('a[href]', els =>
+        els.map(el => el.getAttribute('href')).filter(Boolean)
+      );
+      for (const href of hrefs) {
+        let resolved;
+        try { resolved = new URL(href, url).href; } catch { continue; }
+        if (!resolved.startsWith(origin)) continue;
+        const childKey = normalizeKey(resolved);
+        if (!visitedPathnames.has(childKey)) {
+          queue.push({ url: resolved, depth: depth + 1 });
+        }
+      }
+    } catch (err) {
+      console.warn(`  [crawl] Failed to load ${url}: ${err.message}`);
+    } finally {
+      await page.close();
+    }
+  }
+
+  for (const route of (config.crawl.extraRoutes ?? [])) {
+    const fullUrl = route.startsWith('http') ? route : config.url + route;
+    const key = normalizeKey(fullUrl);
+    if (!visitedPathnames.has(key)) {
+      visitedPathnames.add(key);
+      result.push(fullUrl);
+      console.log(`  [crawl] extra: ${fullUrl}`);
+    }
+  }
+
+  return result;
+}

package/src/html.mjs

@@ -0,0 +1,164 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { VIEWPORT_PRESETS } from './config.mjs';
+
+export async function assembleHtml(pages, config, outputDir) {
+  const date = new Date().toISOString().slice(0, 10);
+  const title = config.title ?? 'Design Review';
+
+  // Generate viewport-specific CSS widths from actual config
+  const viewportCss = config.capture.viewports.map(vp => {
+    const preset = VIEWPORT_PRESETS[vp] ?? { width: 1440 };
+    const cssWidth = vp === 'desktop' ? '100%' : `${preset.width}px`;
+    return `img[data-viewport="${vp}"] { width: ${cssWidth}; max-width: ${preset.width}px; }`;
+  }).join('\n    ');
+
+  const navItems = [];
+  const pageSections = [];
+
+  pages.forEach((capture, i) => {
+    const idx = i + 1;
+    const pageId = `page-${idx}`;
+    const base64 = capture.imageBuffer.toString('base64');
+
+    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)}">
+      <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">
+    </div>`);
+  });
+
+  const themes = [...new Set(pages.map(p => p.theme))];
+  const viewports = [...new Set(pages.map(p => p.viewport))];
+
+  const themeCheckboxes = themes.map(t =>
+    `<label><input type="checkbox" data-filter="theme" value="${escHtml(t)}" checked> ${escHtml(t)}</label>`
+  ).join('\n      ');
+
+  const viewportCheckboxes = viewports.map(v =>
+    `<label><input type="checkbox" data-filter="viewport" value="${escHtml(v)}" checked> ${escHtml(v)}</label>`
+  ).join('\n      ');
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escHtml(title)}</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; }
+    body { background: #1a1a1a; color: #fff; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; margin: 0; display: flex; min-height: 100vh; }
+
+    #sidebar { width: 240px; min-width: 240px; background: #111; border-right: 1px solid #2a2a2a; position: fixed; top: 0; left: 0; height: 100vh; overflow-y: auto; display: flex; flex-direction: column; z-index: 100; }
+    .nav-header { padding: 16px; font-size: 13px; font-weight: 600; color: #fff; border-bottom: 1px solid #2a2a2a; }
+    .nav-meta { padding: 8px 16px; font-size: 11px; color: #555; border-bottom: 1px solid #2a2a2a; }
+    .filters { padding: 12px 16px; border-bottom: 1px solid #2a2a2a; }
+    .filters label { display: block; font-size: 12px; color: #aaa; margin: 4px 0; cursor: pointer; }
+    .filters label input { margin-right: 6px; accent-color: #4a9eff; }
+    .filter-group-label { font-size: 10px; color: #555; text-transform: uppercase; letter-spacing: 0.08em; margin: 8px 0 4px; }
+    #nav-list { list-style: none; margin: 0; padding: 8px 0; flex: 1; }
+    #nav-list li a { display: block; padding: 5px 16px; font-size: 11px; color: #666; text-decoration: none; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    #nav-list li a:hover, #nav-list li a.active { background: #1e1e1e; color: #fff; }
+    #nav-list li[data-hidden] { display: none; }
+
+    #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; }
+    .cover p { color: #666; margin: 4px 0; font-size: 13px; }
+
+    .page { margin-bottom: 56px; }
+    .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 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); }
+
+    ${viewportCss}
+
+    @media (max-width: 600px) {
+      #sidebar { display: none; }
+      #content { margin-left: 0; }
+    }
+  </style>
+</head>
+<body>
+  <nav id="sidebar">
+    <div class="nav-header">${escHtml(title)}</div>
+    <div class="nav-meta">${escHtml(date)} · ${pages.length} pages</div>
+    <div class="filters">
+      <div class="filter-group-label">Theme</div>
+      ${themeCheckboxes}
+      <div class="filter-group-label" style="margin-top:10px">Viewport</div>
+      ${viewportCheckboxes}
+    </div>
+    <ul id="nav-list">
+      ${navItems.join('\n      ')}
+    </ul>
+  </nav>
+  <main id="content">
+    <div class="cover">
+      <h1>${escHtml(title)}</h1>
+      <p>${escHtml(config.url)}</p>
+      <p>${escHtml(date)} · ${pages.length} pages</p>
+    </div>
+    ${pageSections.join('\n    ')}
+  </main>
+  <script>
+    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) => {
+        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);
+      });
+    }
+    document.querySelectorAll('input[data-filter]').forEach(cb => cb.addEventListener('change', applyFilters));
+
+    let currentIdx = 0;
+    function visiblePages() { return [...document.querySelectorAll('.page:not([data-hidden])')]; }
+    document.addEventListener('keydown', e => {
+      const ps = visiblePages();
+      if (!ps.length) return;
+      if (e.key === 'ArrowRight' || e.key === 'ArrowDown') currentIdx = Math.min(currentIdx + 1, ps.length - 1);
+      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 + '"]');
+      if (link) { link.classList.add('active'); link.scrollIntoView({ block: 'nearest' }); }
+    });
+
+    const observer = new IntersectionObserver(entries => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting && !entry.target.hasAttribute('data-hidden')) {
+          const id = entry.target.id;
+          document.querySelectorAll('#nav-list li a').forEach(a => {
+            a.classList.toggle('active', a.getAttribute('href') === '#' + id);
+          });
+        }
+      });
+    }, { threshold: 0.1 });
+    document.querySelectorAll('.page').forEach(p => observer.observe(p));
+  </script>
+</body>
+</html>`;
+
+  const outputPath = path.join(outputDir, 'console-review.html');
+  fs.writeFileSync(outputPath, html, 'utf8');
+  const sizeMB = (fs.statSync(outputPath).size / 1024 / 1024).toFixed(1);
+  console.log(`\n[html] Wrote ${pages.length} pages (${sizeMB} MB) → ${outputPath}`);
+}
+
+function escHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/index.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { chromium } from 'playwright';
+import { loadConfig } from './config.mjs';
+import { ensureAuth } from './auth.mjs';
+import { crawl } from './crawl.mjs';
+import { captureAll } from './capture.mjs';
+import { assemblePdf } from './pdf.mjs';
+import { assembleHtml } from './html.mjs';
+
+function parseArgs(argv) {
+  const args = { config: null, dryRun: false, route: null, authOnly: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--config' && argv[i + 1]) { args.config = argv[++i]; continue; }
+    if (argv[i] === '--dry-run') { args.dryRun = true; continue; }
+    if (argv[i] === '--route' && argv[i + 1]) { args.route = argv[++i]; continue; }
+    if (argv[i] === '--auth-only') { args.authOnly = true; continue; }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv.slice(2));
+
+if (!args.config) {
+  console.error('Usage: darshana --config <path> [--dry-run] [--route <path>] [--auth-only]');
+  process.exit(1);
+}
+
+async function main() {
+  const config = loadConfig(args.config);
+  console.log(`[darshana] ${config.title} — ${config.url}`);
+
+  const storageStatePath = await ensureAuth(config);
+  config._storageStatePath = storageStatePath;
+
+  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);
+    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 {
+    captures = await captureAll(browser, config, urls);
+  } finally {
+    await browser.close();
+  }
+
+  console.log(`\n[darshana] Captured ${captures.length} page(s).`);
+
+  if (captures.length === 0) {
+    console.error('[darshana] No pages captured. Exiting.');
+    process.exit(1);
+  }
+
+  const outputDir = config.outputDir;
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const outputs = config.outputs ?? ['pdf'];
+
+  if (outputs.includes('pdf')) {
+    await assemblePdf(captures, config, outputDir);
+  }
+
+  if (outputs.includes('html')) {
+    await assembleHtml(captures, config, outputDir);
+  }
+
+  if (outputs.includes('images')) {
+    await writeImages(captures, outputDir);
+  }
+
+  console.log('\n[darshana] Done.');
+}
+
+async function writeImages(captures, outputDir) {
+  const byViewport = {};
+  for (const capture of captures) {
+    (byViewport[capture.viewport] = byViewport[capture.viewport] || []).push(capture);
+  }
+  let total = 0;
+  for (const [viewport, vpCaptures] of Object.entries(byViewport)) {
+    const vpDir = path.join(outputDir, 'images', viewport);
+    fs.mkdirSync(vpDir, { recursive: true });
+    vpCaptures.forEach((capture, i) => {
+      const slug = slugifyPathname(capture.pathname);
+      const filename = `${String(i + 1).padStart(3, '0')}-${slug}-${capture.theme}.png`;
+      fs.writeFileSync(path.join(vpDir, filename), capture.imageBuffer);
+      console.log(`  [images] ${viewport}/${filename}`);
+      total++;
+    });
+  }
+  console.log(`\n[images] Wrote ${total} PNG(s) → ${path.join(outputDir, 'images')}`);
+}
+
+function slugifyPathname(pathname) {
+  return (pathname ?? '/')
+    .replace(/^\//, '')
+    .replace(/\//g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    || 'root';
+}
+
+main().catch(err => {
+  console.error('[darshana] Fatal:', err);
+  process.exit(1);
+});

package/src/pdf.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PDFDocument, rgb, StandardFonts } from 'pdf-lib';
+
+const HEADER_HEIGHT = 28;
+const HEADER_BG = rgb(0, 0, 0);
+const HEADER_FG = rgb(1, 1, 1);
+const FONT_SIZE = 11;
+
+export async function assemblePdf(pages, config, outputDir) {
+  const masterDoc = await PDFDocument.create();
+  const font = await masterDoc.embedFont(StandardFonts.Helvetica);
+  const date = new Date().toISOString().slice(0, 10);
+
+  // Cover page — sized to first capture's dimensions, or 1440×900 fallback
+  let coverWidth = 1440, coverHeight = 900;
+  if (pages.length > 0) {
+    try {
+      const firstImg = await masterDoc.embedPng(pages[0].imageBuffer);
+      const dims = firstImg.scale(1);
+      coverWidth = dims.width;
+      coverHeight = dims.height;
+    } catch (_) {}
+  }
+
+  const coverPage = masterDoc.addPage([coverWidth, coverHeight + HEADER_HEIGHT]);
+  coverPage.drawRectangle({ x: 0, y: 0, width: coverWidth, height: coverHeight + HEADER_HEIGHT, color: rgb(0.05, 0.05, 0.05) });
+  coverPage.drawText(config.title ?? 'Design Review', {
+    x: 60, y: coverHeight / 2 + 60, font, size: 36, color: rgb(1, 1, 1),
+  });
+  coverPage.drawText(config.url, {
+    x: 60, y: coverHeight / 2 + 10, font, size: 16, color: rgb(0.7, 0.7, 0.7),
+  });
+  coverPage.drawText(`${date}  ·  ${pages.length} pages`, {
+    x: 60, y: coverHeight / 2 - 30, font, size: 14, color: rgb(0.5, 0.5, 0.5),
+  });
+
+  // Embed each screenshot
+  for (const capture of pages) {
+    console.log(`  [pdf] embedding: ${capture.label}`);
+    try {
+      const img = await masterDoc.embedPng(capture.imageBuffer);
+      const { width: imgWidth, height: imgHeight } = img.scale(1);
+      const pgWidth = imgWidth;
+      const pgHeight = imgHeight + HEADER_HEIGHT;
+      const page = masterDoc.addPage([pgWidth, pgHeight]);
+
+      // Draw screenshot filling below the header
+      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)
+      page.drawRectangle({
+        x: 0, y: imgHeight, width: pgWidth, height: HEADER_HEIGHT, color: HEADER_BG,
+      });
+      page.drawText(capture.label, {
+        x: 8, y: imgHeight + 8, font, size: FONT_SIZE, color: HEADER_FG, maxWidth: pgWidth - 16,
+      });
+    } catch (err) {
+      console.warn(`  [pdf] WARNING: failed to embed ${capture.label}: ${err.message}`);
+    }
+  }
+
+  const outputPath = path.join(outputDir, 'console-review.pdf');
+  const pdfBytes = await masterDoc.save();
+  fs.writeFileSync(outputPath, pdfBytes);
+
+  const sizeMB = (fs.statSync(outputPath).size / 1024 / 1024).toFixed(1);
+  console.log(`\n[pdf] Wrote ${masterDoc.getPageCount()} pages (${sizeMB} MB) → ${outputPath}`);
+}