next-route-graph 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.2.0] - 2026-11-10
+
+### Added
+- Offline SVG route maps with intermediate URL segments and source information; available through `--svg`, `--format svg`, and the SDK.
+- A focused HTML explorer with route selection, layout chains, search, endpoint filters, health diagnostics, and downloadable exports.
+- `--output <file>` for every format, including creation of parent directories.
+- `inspectProject()` and immutable `filterRoutes()` SDK helpers, plus a shared `buildRouteGraph()` model for visual exporters.
+- Offline browser regression tests and Windows/Linux CI checks.
+
+### Fixed
+- Interception markers now resolve target URL segments while ignoring route groups and parallel slots.
+- Valid parallel and intercepted views no longer trigger duplicate URL diagnostics. API-only projects do not require UI layouts.
+- Dynamic parameter conflicts are detected even when descendant endpoints differ; static paths remain case-sensitive.
+- File read failures abort with `ERR_FILE_READ` instead of silently producing incomplete metadata.
+- Named HTTP exports use the exported alias and ignore type-only entries.
+- HTML uses escaped markup and text nodes for source data, a restrictive content policy, and spreadsheet-safe CSV cells.
+- Preview binds to `127.0.0.1`, validates ports, handles occupied ports, and serves only the report.
+- Format conflicts and unknown formats fail explicitly. Reports remain available when strict validation fails; status messages use stderr.
+- Mermaid and DOT now share the URL hierarchy, including segments without endpoints; DOT line breaks render correctly.
+- Tests rebuild production artifacts first, preventing stale CLI and SDK tests.
+
+### Changed
+- Indexed layout lookup replaces repeated scans of every discovered file per endpoint.
+- Search updates every endpoint summary count while keeping convention totals and diagnostics project-wide.
+- CLI version is read from package metadata; npm packages include the linked guides, changelog, and report screenshot.
+
+## [1.1.0] - 2026-11-07
+
+### Added
+- **Route Linter & Collision Detection Engine**: Built-in validation rules detecting dynamic segment collisions (`/users/[id]` vs `/users/[slug]`), duplicate URL path conflicts across route groups (`no-duplicate-paths`), conflicting `page.tsx` and `route.ts` handlers, missing root layouts, and unhandled parallel route slots (`@slot`).
+- **Strategy Pattern Renderers**:
+  - `MermaidRenderer` (`--mermaid` or `--format mermaid`): Generates Mermaid flowchart diagrams with entity-encoded node shapes.
+  - `DotRenderer` (`--dot` or `--format dot`): Generates Graphviz DOT graphs with properly escaped string literals.
+  - `MarkdownRenderer` (`--markdown` or `--format markdown`): Generates GitHub-flavored Markdown tables.
+  - `HtmlRenderer` (`--html`, `--serve`, or `--format html`): Generates a standalone, zero-dependency interactive visual HTML report with route hierarchy cards, searchable data table, CSV export, integrated tabbed format explorer (Mermaid, DOT, Markdown, ANSI Terminal, JSON, Flat), and built-in local preview server.
+- **Deep HTTP Method & Metadata Inspection**: Automatically detects exported HTTP handlers (`GET`, `POST`, `PUT`, `DELETE`, etc.) in `route.ts`, React Server Actions (`"use server"`), and route segment configurations (`runtime`, `dynamic`).
+- **Programmatic TypeScript SDK**: Exported root module `dist/index.js` with TypeScript type declarations (`dist/index.d.ts`) and `"exports"` map, enabling library usage via `import { analyzeRoutes } from 'next-route-graph'`.
+- **Domain Error Hierarchy**: Structured error classes (`ProjectNotFoundError`, `AmbiguousRouterError`, `NoAppRouterError`, `RouteLintError`) with machine-readable codes and actionable hints.
+- **New CLI Commands & Flags**:
+  - `next-route-graph check`: Run route linting checks with exit codes.
+  - `--strict`: Fails with non-zero exit code if route issues or collisions are detected.
+  - `--format <tree|flat|json|mermaid|dot|markdown|html>`: Flexible format selector.
+  - `--html [file]`: Export self-contained interactive HTML report (defaults to `route-graph.html`).
+  - `--serve [port]`: Spin up zero-dependency local HTTP preview server (defaults to port 3000) and open in default browser.
+- **Comprehensive Automated Test Suite**: Expanded test coverage from 9 to 50 unit and integration tests, including end-to-end Next.js project fixtures, CLI subprocess tests, scanner edge cases, linter edge cases, external SDK consumer verification, and HTML report validation.
+- **Documentation & Governance Suite**: Added `docs/ARCHITECTURE.md`, `docs/adr/0001-hybrid-parsing-and-strategy-renderers.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md`.
+
+### Fixed
+- **Private Folders**: Ignored Next.js private folders (`_folder`, e.g. `_components`, `_lib`) and hidden directories during route discovery so internal components are not treated as public routes.
+- **Multiple Root Layouts**: Added support for Multiple Root Layouts partitioned within top-level route groups (e.g. `app/(marketing)/layout.tsx` and `app/(shop)/layout.tsx`), eliminating false-positive `require-root-layout` errors.
+- **Intercepting Routes**: Fixed regex in `parseRoutePath` and `extractRouteMetadata` to match multi-level intercepting tokens `(..)(..)` before single-level `(..)`.
+- **Directive Truncation**: Replaced 500-character slice heuristic with a prologue parser (`getPrologueDirectives`), fixing missed `"use client"` / `"use server"` directives in files with long license headers.
+- **Comment-Stripped Extraction**: Stripped comments before extracting HTTP methods, Server Actions, and route configs to prevent commented-out code (e.g. `// export function GET()`) from being reported.
+- **Renderer Escaping**:
+  - Escaped backslashes before double quotes in Graphviz DOT output.
+  - Entity-encoded square brackets (`#91;`, `#93;`) in Mermaid labels to prevent broken node shape syntax.
+  - Escaped pipe characters (`\|`) in Markdown table cells.
+
+### Performance
+- **Reduced Disk I/O**: Reduced filesystem reads by 66% in `analyzer.ts` by reading each file once into memory and caching parsed metadata.
+- **Deterministic Route Ordering**: Implemented composite multi-level sorting (`path`, then `file`) guaranteeing consistent output across operating systems.
+
+### Changed
+- Refactored `analyzer.ts` into a decoupled pipeline supporting layout hierarchy tracking and slot resolution.
+- Enriched `AnalysisResult` and `SummaryStats` with API route, parallel route, and interceptor counts.
+- Enabled direct path execution in `detectAppRouter` when targeting `app/` or `src/app/` directly.
+- Decoded Next.js `%5F` prefix syntax to underscores in URL routes (e.g. `%5Fprivate` ➔ `/_private`).
+- Aligned route tree columns dynamically based on the longest route path in the project.
+- Fixed nested markdown code blocks in `README.md`.
+
+---
+
+## [1.0.2] - 2026-09-13
+
+### Changed
+- Improved rendering performance and CLI tree layout formatting.
+
+---
+
+## [1.0.0] - 2026-09-05
+
+### Added
+- Initial release of `next-route-graph`.
+- Support for static, dynamic, catch-all, and optional catch-all route detection.
+- App Router directory auto-discovery (`app` and `src/app`).
+- Basic tree, flat, and JSON output formats.

package/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to next-route-graph
+
+Thank you for your interest in contributing! We welcome bug reports, documentation improvements, new renderers, and feature contributions.
+
+---
+
+## Development Setup
+
+1. **Prerequisites**:
+   * Node.js >= 18.0.0
+   * npm >= 9.0.0
+   * Node.js >= 20 for the optional browser tests
+
+2. **Clone and Install**:
+   ```bash
+   git clone https://github.com/Nima-sltn/next-route-graph.git
+   cd next-route-graph
+   npm install
+   ```
+
+3. **Running the Development CLI**:
+   ```bash
+   npm run dev -- [path-to-nextjs-app]
+   ```
+
+---
+
+## Quality Checks & Testing
+
+Before submitting a Pull Request, ensure all tests, type checks, and builds pass:
+
+```bash
+# Run unit tests
+npm test
+
+# Run TypeScript type check
+npm run typecheck
+
+# Build the project
+npm run build
+
+# Exercise the offline HTML report in Chromium
+npx playwright install chromium
+npm run test:browser
+
+# Run the complete pre-publish verification suite
+npm run prepublishOnly
+```
+
+---
+
+## Project Structure
+
+* `src/cli.ts` - Command line interface definition and options.
+* `src/index.ts` - Programmatic public SDK entry point.
+* `src/core/detector.ts` - App Router root directory detection.
+* `src/core/scanner.ts` - File discovery and directory traversal.
+* `src/core/parser.ts` - Directive detection, HTTP method parsing, and URL resolution.
+* `src/core/linter.ts` - Route collision and framework best practice validation.
+* `src/core/analyzer.ts` - Core analysis orchestrator and indexed layout lookup.
+* `src/core/inspect.ts` - Shared CLI/SDK scan entry point and immutable filtering.
+* `src/render/` - Text, SVG, and offline HTML renderers with a shared URL graph.
+* `src/preview.ts` - Loopback-only static report serving.
+* `src/errors/` - Domain error classes and actionable hints.
+* `tests/` - Node.js built-in unit/integration tests and Playwright browser checks.
+
+---
+
+## Pull Request Guidelines
+
+1. Create a descriptive branch name (e.g. `feature/openapi-export` or `fix/parallel-routes`).
+2. Add unit tests for any new functionality in `tests/`.
+3. Follow existing code conventions and maintain explicit TypeScript types.
+4. Update `README.md` and `CHANGELOG.md` when introducing user-facing changes.

package/README.md

@@ -1,245 +1,169 @@
 # next-route-graph
 
-[![npm version](https://img.shields.io/npm/v/next-route-graph.svg?color=blue&style=flat-square)](https://www.npmjs.com/package/next-route-graph)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=flat-square)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
-[![Tests](https://img.shields.io/badge/tests-47%20passed-success?style=flat-square)](https://github.com/Nima-sltn/next-route-graph)
+[![npm version](https://img.shields.io/npm/v/next-route-graph.svg)](https://www.npmjs.com/package/next-route-graph)
+[![CI](https://github.com/Nima-sltn/next-route-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/Nima-sltn/next-route-graph/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-> Inspect, lint, and visualize the structure of your Next.js App Router project from the terminal or programmatic TypeScript SDK.
+Inspect, lint, and visualize a Next.js App Router project without starting Next.js or executing its code. Use the terminal for quick inspection, an offline HTML report for exploration, and SVG for a diagram you can share anywhere.
 
-`next-route-graph` is a lightweight, zero-config CLI and SDK that scans your `app/` or `src/app/` directory and turns your routing architecture into a clear visual overview.
-
-Useful for auditing large codebases, preventing route collisions in CI/CD, onboarding developers, generating README diagrams, or supplying structured context to AI coding assistants.
-
----
-
-## ✨ Features
-
-- **Route Discovery**: Identifies static, dynamic (`[slug]`), catch-all (`[...slug]`), and optional catch-all (`[[...slug]]`) routes.
-- **App Router Special Conventions**: Full detection of `page`, `layout`, `loading`, `error`, `not-found`, `template`, `default`, and `route` files.
-- **Deep HTTP Method Detection**: Inspects `route.ts` API handlers to extract supported methods (`GET`, `POST`, `PUT`, `DELETE`, etc.).
-- **Route Linter & Collision Detection**: Catches dynamic parameter collisions (e.g. `/users/[id]` vs `/users/[slug]`), missing root layouts, page/route conflicts, and parallel route slot fallbacks.
-- **Multiple Output Formats**: Styled terminal tree, flat list, JSON, **Mermaid flowchart**, **Graphviz DOT**, and **Markdown table**.
-- **Programmatic TypeScript SDK**: Use directly in Node.js scripts, build pipelines, or devtools with full type definitions.
-- **Fast & Zero-Config**: Runs in milliseconds without starting a Next.js server, bundler, or runtime.
+```sh
+npx next-route-graph ./my-app
+npx next-route-graph ./my-app --html reports/routes.html
+npx next-route-graph ./my-app --svg --output reports/routes.svg
+```
 
----
+Version **1.2.0** adds rendered SVG exports, an offline HTML explorer, and shared CLI/SDK scanning. See the [changelog](CHANGELOG.md) for details.
 
-## 🚀 Installation & Quick Start
+![Offline route map with parallel endpoint details](docs/route-report.png)
 
-Run instantly with `npx`:
+## What it tells you
 
-```bash
-npx next-route-graph
-```
+- Public URL paths, dynamic segments, route groups, parallel slots, and intercepted targets.
+- Page and API handler source files, declared HTTP methods, client directives, Server Actions, and literal segment configuration.
+- Layout chains from the outermost layout to each endpoint.
+- Route collisions, missing page layouts, page/handler conflicts, slot fallback warnings, and misplaced global error files.
 
-Or install globally:
+Private folders and build/dependency directories are excluded. Routes are sorted for consistent output. All exports work without a Next.js server.
 
-```bash
-npm install -g next-route-graph
-```
+## Install
 
-Or add as a development dependency:
+Requires Node.js 18 or newer. Run with `npx`, or install in your project:
 
-```bash
+```sh
 npm install -D next-route-graph
 ```
 
----
-
-## 🖥️ CLI Usage
+## Explore visually
 
-### Basic Tree Overview
+```sh
+# Standalone report; opens directly from disk and works offline
+npx next-route-graph ./my-app --html reports/routes.html
 
-Run from the root of your Next.js project:
+# Local static snapshot; visit the printed URL (default port 3000)
+npx next-route-graph ./my-app --serve
 
-```bash
-npx next-route-graph
+# Choose a port, or 0 to choose an available port
+npx next-route-graph ./my-app --serve 4300
 ```
 
-Analyze a specific project directory:
-
-```bash
-npx next-route-graph ./path/to/my-next-app
-```
-
-Example terminal output:
-
-```text
-next-route-graph
-
-Project    my-next-app
-Router     App Router
-Root       src/app
-
-Routes
-────────────────────────────────────────
-├── /                            page.tsx
-├── /about                       page.tsx  [client]
-├── /blog                        page.tsx
-├── /blog/[slug]                 page.tsx  [dynamic]
-├── /dashboard                   page.tsx  [@analytics]
-└── /api/users                   route.ts  [GET, POST]
-
-Summary
-────────────────────────────────────────
-Routes       6
-Dynamic      1
-Client       1
-Server       5
-Layouts      2
-Loading      1
-Errors       1
-API Routes   1
-Parallel     1
-
-✓ Analysis completed in 8ms
-```
-
----
-
-## 🛡️ Route Health & Linting (`check`)
-
-Run route validation checks to detect conflicts, broken parallel slots, or missing layouts before deploying:
+The report has four sections:
 
-```bash
-# Check routes and display issues
-npx next-route-graph check
+| Section | Purpose |
+| --- | --- |
+| Route map | Rendered SVG hierarchy, including segments without endpoints. Select a node with a mouse or keyboard to inspect every source and its layout chain. |
+| Routes | Search paths, source files, methods, or layouts; filter pages, handlers, rendering declarations, dynamic routes, slots, or interceptions. Download matching rows as CSV. |
+| Health | Project-wide diagnostics with rule names, locations, and actionable hints. |
+| Exports | Download SVG, Mermaid, DOT, Markdown, JSON, flat paths, or a plain terminal tree. One selector keeps the interface compact. |
 
-# Strict mode: exits with code 1 if errors or collisions are discovered (ideal for CI)
-npx next-route-graph check --strict
-```
-
----
+Multiple sources at one URL remain inspectable. Map filtering dims unrelated branches and retains ancestors for context. Report downloads contain all endpoints included in the report; CSV uses the current browser filter.
 
-## 📊 Output Formats (Strategy Pattern)
+SVG is a real vector image. Mermaid and Graphviz DOT are source formats for their respective renderers; they do not need to render in your terminal. The HTML map renders directly without a CDN or a graph library. The preview server binds only to `127.0.0.1` and serves the in-memory report. Rerun the command to refresh its snapshot.
 
-Select any format with `--format <type>` or dedicated flags:
+## Export and automate
 
-### 1. Mermaid Flowchart (`--mermaid`)
-Generate a Mermaid flowchart diagram to paste directly into GitHub READMEs, PRs, or Notion:
+Choose one format flag, or use `--format`. `--output` works for every format and creates missing parent directories. File-write notices go to stderr; stdout remains suitable for pipes.
 
-```bash
-npx next-route-graph --mermaid
-```
+| Format | Flag | Use |
+| --- | --- | --- |
+| Terminal tree | Default / `--format tree` | Quick overview and lint summary |
+| Flat paths | `--flat` | Shell pipelines |
+| JSON | `--json` | SDK consumers, build tools, or AI context |
+| SVG | `--svg` | Rendered image for reports and design tools |
+| HTML | `--html [file]` / `--format html` | Offline interactive report |
+| Mermaid | `--mermaid` | Fenced diagram for Markdown documentation |
+| Graphviz DOT | `--dot` | Graphviz processing |
+| Markdown | `--markdown` | Documentation table |
 
-```mermaid
-flowchart TD
-  %% Next.js Route Graph
-  root["/"]
-  route_1["/about (client)"]
-  route_2["/api/users (GET/POST)"]
-  root --> route_1
-  root --> route_2
-```
+```sh
+npx next-route-graph ./my-app --json --output reports/routes.json
+npx next-route-graph ./my-app --mermaid --output reports/routes.md
+npx next-route-graph ./my-app --dot --output reports/routes.dot
+dot -Tsvg reports/routes.dot -o reports/graphviz.svg
 
-### 2. Graphviz DOT (`--dot`)
-Output standard Graphviz DOT notation for visual pipelines and rendering tools:
+# Stream HTML instead of writing a report file
+npx next-route-graph ./my-app --format html > routes.html
 
-```bash
-npx next-route-graph --dot > routes.dot
+# Case-insensitive filtering by path, file, or HTTP method
+npx next-route-graph ./my-app --search POST --json
 ```
 
-### 3. Markdown Table (`--markdown`)
-Generate a clean Markdown summary table:
+`--search` changes endpoint counts in the report; layout/loading/error-file totals and diagnostics still describe the whole project. A filtered export cannot hide a CI failure. Use `--output -` to explicitly write to stdout. `--html` defaults to `route-graph.html`.
 
-```bash
-npx next-route-graph --markdown
-```
+## Validate in CI
 
-### 4. JSON (`--json`)
-Output machine-readable JSON for CI integration, custom tooling, or AI agents:
+```sh
+npx next-route-graph check ./my-app
+npx next-route-graph check ./my-app --strict --json
 
-```bash
-npx next-route-graph --json
+# Save a reviewable artifact even if validation fails
+npx next-route-graph ./my-app --strict --format html --output reports/routes.html
 ```
 
-### 5. Flat Paths (`--flat`)
-Output only newline-separated URL paths:
+| Command | Exit 1 when |
+| --- | --- |
+| Default scan | Scanning or output fails |
+| `check` / `--check` | Scanning fails or lint errors exist |
+| `--strict` | Scanning fails or lint errors or warnings exist |
 
-```bash
-npx next-route-graph --flat
-```
+JSON scan errors are written as `{ "error": "…", "code": "…" }` to stderr. Successful report data is written to stdout or the requested file. Invalid options also fail. A strict file export is written before lint determines the exit code.
 
-### 6. Route Filtering (`--search`)
-Filter routes matching a specific substring:
+Example GitHub Actions step after installing your project's dependencies:
 
-```bash
-npx next-route-graph --search blog
+```yaml
+- name: Check routing and generate a report
+  run: npx next-route-graph . --strict --format html --output reports/routes.html
+- name: Save report
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: route-report
+    path: reports/routes.html
 ```
 
----
-
-## 📦 Programmatic TypeScript SDK
+## TypeScript SDK
 
-`next-route-graph` exports a complete, fully-typed programmatic API:
+```ts
+import { inspectProject, filterRoutes, getRenderer } from "next-route-graph";
+import { writeFile } from "node:fs/promises";
 
-```typescript
-import {
-  detectAppRouter,
-  scanAppDir,
-  analyzeRoutes,
-  lintRoutes,
-  getRenderer,
-} from "next-route-graph";
+const result = await inspectProject("./my-app");
+await writeFile("routes.html", getRenderer("html").render(result));
+await writeFile("routes.svg", getRenderer("svg").render(result));
 
-// 1. Detect App Router root
-const { appDir, displayRoot } = detectAppRouter("./my-next-app");
-
-// 2. Discover files
-const files = await scanAppDir(appDir);
+const api = filterRoutes(result, "api/"); // returns a new result
+console.log(api.summary.apiRoutes);
+if (result.lint?.hasErrors) process.exitCode = 1;
+```
 
-// 3. Analyze routes, HTTP methods, and layouts
-const result = await analyzeRoutes(files, "./my-next-app", displayRoot);
+The lower-level `detectAppRouter()`, `scanAppDir()`, `analyzeRoutes()`, and `lintRoutes()` APIs remain available. `buildRouteGraph(result.routes)` exposes URL nodes with stable IDs within an export, parent IDs, depth, and all endpoint sources attached to each node. `getRenderer()` rejects unknown formats. See [architecture](docs/ARCHITECTURE.md) for module boundaries.
 
-console.log(`Found ${result.summary.routes} routes`);
+## Scope and limitations
 
-// 4. Render output via Strategy Pattern
-const mermaidOutput = getRenderer("mermaid").render(result);
-console.log(mermaidOutput);
+This is static **App Router** source inspection, not a replacement for `next build`. Pages Router, metadata-generated endpoints, custom `pageExtensions`, rewrites, redirects, middleware/proxy behavior, and imports are not evaluated. Source extraction uses comment-aware text parsing, not an AST or TypeScript evaluation; computed exports, complex string contents, and re-export chains can be incomplete. Detected HTTP methods are declared methods, not Next.js-generated methods.
 
-// 5. Run route lint checks programmatically
-const lint = lintRoutes(result.routes, files);
-if (lint.hasErrors) {
-  console.error("Route validation failed:", lint.issues);
-}
-```
+“Server” means the file has no top-level `use client` directive. It does not prove static generation, caching, SSR behavior, or imported component boundaries. Runtime and dynamic configuration show local literal declarations, not inherited effective values. The URL graph describes structure; its edges do not imply imports, navigation links, or layout inheritance. Layout inheritance appears separately in the details panel.
 
----
+Diagnostics intentionally cover a small set of routing conventions. Parallel fallback warnings flag potentially unmatched navigation; the tool does not simulate navigation. Share exported reports with the same care as source filenames and internal endpoint names: they contain those names and detected metadata, but never source file contents.
 
-## 🤖 CI/CD Integration (GitHub Actions)
+Framework references: [intercepting routes](https://nextjs.org/docs/app/api-reference/file-conventions/intercepting-routes), [parallel routes](https://nextjs.org/docs/app/api-reference/file-conventions/parallel-routes), and [layouts](https://nextjs.org/docs/app/api-reference/file-conventions/layout).
 
-Add a route validation check to your GitHub Actions pull request workflow:
+## Development
 
-```yaml
-name: Route Verification
-on: [pull_request]
-
-jobs:
-  check-routes:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm ci
-      - name: Lint Next.js Routes
-        run: npx next-route-graph check --strict
+```sh
+npm ci
+npm run typecheck
+npm test                 # builds first; unit, CLI, SDK, and HTTP integration tests
+npx playwright install chromium
+npm run test:browser     # builds first; real offline browser workflow
 ```
 
----
-
-## 🏛️ Architecture & Documentation
-
-- [Architecture Guide](docs/ARCHITECTURE.md) - Pipeline design, data structures, and component diagram.
-- [Architectural Decision Records (ADRs)](docs/adr/0001-hybrid-parsing-and-strategy-renderers.md) - Technical decisions and trade-offs.
-- [Contributing Guide](CONTRIBUTING.md) - How to run tests and contribute.
-- [Changelog](CHANGELOG.md) - Release history and version notes.
-
----
+Browser development tests require Node.js 20 or newer. To use installed Chrome in PowerShell: `$env:PLAYWRIGHT_CHROMIUM_CHANNEL='chrome'`. Set `NRG_REPORT_ARTIFACT_DIR=reports` to save the example HTML and desktop/mobile screenshots during browser tests.
 
-## 📄 License
+- [Contributing](CONTRIBUTING.md)
+- [Architecture and trade-offs](docs/ARCHITECTURE.md)
+- [Architecture decision](docs/adr/0001-offline-reports-and-shared-route-graph.md)
+- [Improvement evidence](docs/NEW_FEATURES.md)
+- [Changelog](CHANGELOG.md)
+- [Security](SECURITY.md)
 
-[MIT](LICENSE) © 2026 [Nima Soltanian](https://github.com/Nima-sltn)
+[MIT](LICENSE) © 2026 Nima Soltanian

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.2.x   | :white_check_mark: |
+| 1.1.x   | :white_check_mark: |
+| 1.0.x   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in `next-route-graph`, please report it responsibly:
+
+1. **Do not open a public GitHub issue.**
+2. Send an email to the repository maintainer or open a private security advisory through GitHub.
+3. Include detailed steps to reproduce the issue along with a minimal reproduction project if possible.
+
+You will receive an acknowledgment within 48 hours, followed by updates on the timeline for a patch.