dirplot 0.2.0__tar.gz → 0.3.1__tar.gz

{dirplot-0.2.0 → dirplot-0.3.1}/.claude/settings.local.json

@@ -6,7 +6,8 @@
       "Bash(uv pip:*)",
       "Bash(git mv:*)",
       "Bash(LC_ALL=C sed:*)",
-      "Bash(find:*)"
+      "Bash(find:*)",
+      "Bash(docker run:*)"
     ]
   }
 }

dirplot-0.3.1/.dockerignore

@@ -0,0 +1,11 @@
+.venv/
+.git/
+.pytest_cache/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.mypy_cache/
+.ruff_cache/
+*.png
+*.svg

dirplot-0.3.1/CHANGELOG.md

@@ -0,0 +1,167 @@
+# 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).
+
+## [Unreleased]
+
+### Added
+
+- `github://` URI now accepts an optional subpath after the repository name, letting
+  you scan a subdirectory directly:
+  - `github://owner/repo/sub/path` — subpath on the default branch
+  - `github://owner/repo@ref/sub/path` — subpath on a specific branch, tag, or commit SHA
+  - `https://github.com/owner/repo/tree/branch/sub/path` — full GitHub URL form
+  - Tags and commit SHAs are supported wherever a branch ref was previously accepted
+    (e.g. `github://torvalds/linux@v6.12`), as the GitHub trees API accepts any git ref.
+- `--legend N` replaces the old boolean `--legend/--no-legend` flag. It now shows a
+  **file-count legend** — a sorted list of the top N extensions by number of files,
+  with a coloured swatch and the file count for each entry:
+  - Pass `--legend` alone to use the default of 20 entries.
+  - Pass `--legend 10` for a custom limit.
+  - Omit the flag entirely to show no legend.
+  - The number of rows is also capped automatically so the box never overflows the
+    image, based on available vertical space and the current `--font-size`.
+  - Extensions with the same count are sorted alphabetically as a tiebreaker.
+  - When the total number of extensions exceeds the limit, a `(+N more)` line is
+    appended at the bottom of the box.
+
+- The root tile header now includes a summary of the scanned tree after an em-dash
+  separator: `myproject — 124 files, 18 dirs, 4.0 MB (4,231,680 bytes)`.
+  Applies to both PNG and SVG output. The label is truncated with `…` when the tile
+  is too narrow to fit the full string.
+
+- Greatly expanded archive format support via the new `libarchive-c` core dependency
+  (wraps the system libarchive C library):
+  - **New formats**: `.iso`, `.cpio`, `.xar`, `.pkg`, `.dmg`, `.img`, `.rpm`, `.cab`,
+    `.lha`, `.lzh`, `.a`, `.ar`, `.tar.zst`, `.tzst`
+  - **New ZIP aliases**: `.nupkg` (NuGet), `.vsix` (VS Code extension), `.ipa` (iOS app),
+    `.aab` (Android App Bundle)
+  - `.tar.zst` / `.tzst` routed through libarchive for consistent behaviour across all
+    supported Python versions (stdlib `tarfile` only gained zstd support in 3.12).
+  - `libarchive-c>=5.0` added as a core dependency alongside `py7zr` and `rarfile`.
+    Requires the system libarchive library:
+    `brew install libarchive` / `apt install libarchive-dev`.
+  - See [ARCHIVES.md](docs/ARCHIVES.md) for the full format table, platform notes, and
+    intentionally unsupported formats (`.deb`, UDIF `.dmg`).
+- Encrypted archive handling:
+  - `--password` CLI option passes a passphrase upfront.
+  - If an archive turns out to be encrypted and no password was given, dirplot prompts
+    interactively (`Password:` hidden-input prompt) and retries — no need to re-run with a flag.
+  - A wrong password exits cleanly with `Error: incorrect password.`
+  - `PasswordRequired` exception exported from `dirplot.archives` for programmatic use.
+  - **Encryption behaviour by format** (since dirplot reads metadata only, never extracts):
+    - ZIP and 7z: central directory / file list is unencrypted by default → readable without
+      a password even for encrypted archives.
+    - RAR with header encryption (`-hp`): listing is hidden without password;
+      wrong password raises `PasswordRequired`.
+
+### Fixed
+
+- `--version` moved back to the top-level `dirplot` command (was accidentally scoped
+  to `dirplot map` after the CLI was restructured into subcommands).
+
+## [0.3.0] - 2026-03-10
+
+### Added
+
+- Kubernetes pod scanning via `pod://pod-name/path` syntax — uses `kubectl exec` and
+  `find` to build the tree without copying files out of the pod. Works on any running
+  pod that has a POSIX shell and `find` (GNU or BusyBox). No extra dependency; only
+  `kubectl` is required.
+  - Namespace can be specified inline (`pod://pod-name@namespace:/path`) or via
+    `--k8s-namespace`.
+  - Container can be selected for multi-container pods via `--k8s-container`.
+  - `-xdev` is intentionally omitted so mounted volumes (emptyDir, PVC, etc.) within
+    the scanned path are traversed — the common case in k8s where images declare
+    `VOLUME` entries that are always mounted on a separate filesystem.
+  - Automatically falls back to a portable `sh` + `stat` loop on BusyBox/Alpine pods.
+- Docker container scanning via `docker://container:/path` syntax — uses `docker exec`
+  and `find` to build the tree without copying files out of the container. Works on any
+  running container that has a POSIX shell and `find` (GNU or BusyBox). No extra
+  dependency; only the `docker` CLI is required.
+  - Automatically detects BusyBox `find` (Alpine-based images) and falls back to a
+    portable `sh` + `stat` loop when GNU `-printf` is unavailable.
+  - Virtual filesystems (`/proc`, `/sys`, `/dev`) are skipped via `-xdev`.
+  - Supports `--exclude`, `--depth`, `--log`, and all other standard options.
+  - `Dockerfile` and `.dockerignore` added so the project itself can be used as a
+    scan target.
+- SVG output format via `--format svg` or by saving to a `.svg`-suffixed path with `--output`.
+  The output is a fully self-contained, interactive SVG file:
+  - **CSS hover highlight** — file tiles brighten and gain a soft glow; directory headers
+    brighten on mouse-over (`.tile` / `.dir-tile` classes, no JavaScript needed).
+  - **Floating tooltip panel** — a JavaScript-driven semi-transparent panel tracks the cursor
+    and shows the file or directory name, human-readable size, and file-type / item count.
+    No external scripts or stylesheets — the panel logic is embedded in the SVG itself.
+  - **Van Wijk cushion shading** — approximated via a single diagonal `linearGradient`
+    overlay (`gradientUnits="objectBoundingBox"`), defined once and shared across all tiles.
+    Matches the ×1.20 highlight / ×0.80 shadow range of the PNG renderer.
+    Disabled with `--no-cushion`.
+- `--format png|svg` CLI option; format is also auto-detected from the `--output` file
+   extension.
+- `create_treemap_svg()` added to the public Python API (`from dirplot import create_treemap_svg`).
+- `drawsvg>=2.4` added as a core dependency.
+- Rename the treemap command to `map` (dirplot map <root>).
+- Add `termsize` subcommand and restructure CLI as multi-command app.
+- Add `--depht` parameter to limit the scanning of large file trees.
+- Support for SSH remote directory scanning (`pip install dirplot[ssh]`).
+- Support for AWS S3 buckets in the cloud (`pip install dirplot[s3]`).
+- Support for local archive files, .zip, tgz, .tar.xz, .rar, .7z, etc.
+- Include example archives for 17 different extentions for testing.
+- Comprehensive documentation.
+- `github://owner/repo[@branch]` URI scheme for GitHub repository scanning. The old
+  `github:owner/repo` shorthand has been removed.
+- File tiles now have a 1-px dark outline (60/255 below fill colour per channel) so
+  adjacent same-coloured tiles — e.g. a directory full of extension-less files — are
+  always visually distinct rather than blending into a single flat block.
+
+### Changed
+
+- `docs/REMOTE-ACCESS.md` renamed to `docs/EXAMPLES.md`; Docker and Kubernetes pod
+  sections added; images with captions added for all remote backends.
+
+### Fixed
+
+- SVG tooltips now show the original byte count when `--log` is active, not the
+  log-transformed layout value. `Node.original_size` is populated by `apply_log_sizes`
+  for both file and directory nodes and is used by the SVG renderer for `data-size`.
+- GitHub error messages are now clear and actionable.
+
+## [0.2.0] - 2026-03-09
+
+### Added
+
+- Support for Windows, incl. full test suite
+
+### Fixed
+
+- Improved README, Makefile
+
+## [0.1.2] - 2026-03-06
+
+### Fixed
+
+- Partly incorrect `uvx install dirplot` command
+- Wrong version number in `uv.lock`
+
+## [0.1.1] - 2026-03-06
+
+### Fixed
+
+- Typing complaints
+- Improved README with better install/run commands
+
+## [0.1.0] - 2026-03-06
+
+### Added
+
+- Nested squarified treemap rendered as a PNG at the exact pixel dimensions of the terminal window.
+- Inline terminal display via iTerm2 and Kitty graphics protocols, auto-detected at runtime; supports iTerm2, WezTerm, Warp, Hyper, Kitty, and Ghostty.
+- System-viewer fallback (`open` / `xdg-open`) as the default display mode.
+- File-extension colours from the GitHub Linguist palette (~500 known extensions); unknown extensions fall back to a stable MD5-derived colour from the chosen colormap.
+- Van Wijk quadratic cushion shading giving each tile a raised 3-D look (`--cushion`, on by default).
+- Bundled JetBrains Mono fonts for crisp directory labels at any size.
+- CLI options: `--output`, `--show/--no-show`, `--inline`, `--legend`, `--font-size`, `--colormap`, `--exclude`, `--size`, `--header/--no-header`, `--cushion/--no-cushion`, `--log`.
+- Full test suite (65 tests), strict mypy, ruff linting, pre-commit hooks, and CI on Python 3.10–3.13.

dirplot-0.3.1/Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install build tools needed by some optional deps
+RUN pip install --no-cache-dir uv
+
+# Copy project metadata first for layer caching
+COPY pyproject.toml README.md ./
+
+# Copy source
+COPY src/ src/
+
+# Install dirplot with all extras
+RUN uv pip install --system --no-cache ".[ssh,s3,docker,dev]"
+
+# Copy the rest (tests, docs, etc.) so the container is a useful scan target
+COPY . .
+
+# Keep the container running so docker:// scanning works
+CMD ["sleep", "infinity"]

{dirplot-0.2.0 → dirplot-0.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dirplot
-Version: 0.2.0
-Summary: Static treemap bitmaps for directory trees, displayed as inline terminal images
+Version: 0.3.1
+Summary: Static treemap bitmaps for directory trees and archives, displayed as inline terminal images
 Project-URL: Repository, https://github.com/deeplook/dirplot
 License: MIT
 License-File: LICENSE
@@ -19,13 +19,18 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: System :: Archiving
 Classifier: Topic :: System :: Filesystems
 Classifier: Topic :: Terminals
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: drawsvg>=2.4.1
+Requires-Dist: libarchive-c>=5.0
 Requires-Dist: matplotlib>=3.7
 Requires-Dist: pillow>=9.0
+Requires-Dist: py7zr>=0.20
+Requires-Dist: rarfile>=4.0
 Requires-Dist: squarify>=0.4
 Requires-Dist: typer>=0.9
 Provides-Extra: dev
@@ -34,6 +39,12 @@ Requires-Dist: pre-commit>=3.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: libarchive
+Requires-Dist: libarchive-c>=5.3; extra == 'libarchive'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.26; extra == 's3'
+Provides-Extra: ssh
+Requires-Dist: paramiko>=3.0; extra == 'ssh'
 Description-Content-Type: text/markdown
 
 # dirplot
@@ -58,10 +69,14 @@ Description-Content-Type: text/markdown
 - Label colour (black/white) chosen automatically based on background luminance.
 - Output resolution matches the current terminal window pixel size (via `TIOCGWINSZ`), or a custom `WIDTHxHEIGHT`.
 - Van Wijk cushion shading gives tiles a raised 3-D appearance (optional).
+- **SVG output** (`--format svg` or `--output file.svg`) produces a fully self-contained interactive file: CSS hover highlight, a JavaScript floating tooltip panel, and cushion shading via a gradient — no external dependencies.
 - Display via system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected).
-- Save output to a PNG file with `--output`.
+- Save output to a PNG or SVG file with `--output`.
 - Exclude paths with `--exclude` (repeatable).
 - Works on macOS, Linux, and Windows; WSL2 fully supported.
+- Scan remote hosts over SSH (`pip install "dirplot[ssh]"`), AWS S3 buckets (`pip install "dirplot[s3]"`), any public/private GitHub repository (including specific branch, tag, commit SHA, or subdirectory), **running Docker containers**, or **Kubernetes pods** — all without extra dependencies beyond the respective CLI/SDK. See [EXAMPLES.md](docs/EXAMPLES.md).
+- Optional **file-count legend** (`--legend`) — a corner overlay listing the top extensions by number of files, with coloured swatches and counts, automatically sized to fit the image.
+- **Wide archive support** — reads zip, tar (gz/bz2/xz/zst), 7z, rar, and via libarchive: iso, cpio, rpm, cab, lha/lzh, xar/pkg, a/ar, and all ZIP-based formats (jar, whl, apk, nupkg, vsix, ipa, …) as virtual directory trees without unpacking. Encrypted archives are handled gracefully: metadata-only reads work without a password for most formats; a password can be supplied with `--password` or entered interactively when needed.
 
 ## How It Works
 
@@ -105,35 +120,51 @@ This tool has been developed and tested on macOS and is CI-tested on Linux and W
 uvx dirplot --help
 
 # Show dirplot for the current directory (opens image in system viewer)
-dirplot .
+dirplot map .
+
+# Show current terminal size in characters and pixels
+dirplot termsize
 
 # Save to a file without displaying
-dirplot . --output dirplot.png --no-show
+dirplot map . --output dirplot.png --no-show
 
 # Display inline (protocol auto-detected: iTerm2, Kitty, Ghostty)
-dirplot . --inline
+dirplot map . --inline
 
 # Exclude directories
-dirplot . --exclude .venv --exclude .git
+dirplot map . --exclude .venv --exclude .git
 
 # Use a different colormap and larger directory labels
-dirplot . --colormap Set2 --font-size 18
+dirplot map . --colormap Set2 --font-size 18
 
 # Render at a fixed resolution instead of terminal size
-dirplot . --size 1920x1080 --output dirplot.png --no-show
+dirplot map . --size 1920x1080 --output dirplot.png --no-show
 
 # Don't apply cushion shading — makes tiles look flat
-dirplot . --no-cushion
+dirplot map . --no-cushion
+
+# Show a file-count legend (top 20 extensions by default)
+dirplot map . --legend
+
+# Show a file-count legend limited to 10 entries
+dirplot map . --legend 10
+
+# Save as an interactive SVG (hover highlight + floating tooltip)
+dirplot map . --output treemap.svg --no-show
+
+# Force SVG format explicitly
+dirplot map . --format svg --output treemap.svg --no-show
 ```
 
 ### Options
 
 | Flag | Short | Default | Description |
 |---|---|---|---|
-| `--output` | `-o` | — | Save PNG to this path |
+| `--output` | `-o` | — | Save to this path (PNG or SVG) |
+| `--format` | `-f` | auto | Output format: `png` or `svg`. Auto-detected from `--output` extension |
 | `--show/--no-show` | | `--show` | Display the image after rendering |
-| `--inline` | | off | Display in terminal (protocol auto-detected) |
-| `--legend/--no-legend` | | `--no-legend` | Show file-extension colour legend |
+| `--inline` | | off | Display in terminal (protocol auto-detected; PNG only) |
+| `--legend [N]` | | off | Show file-count legend; `N` sets max entries (default: 20) |
 | `--font-size` | `-s` | `12` | Directory label font size in pixels |
 | `--colormap` | `-c` | `tab20` | Matplotlib colormap for unknown extensions |
 | `--exclude` | `-e` | — | Path to exclude (repeatable) |
@@ -141,6 +172,8 @@ dirplot . --no-cushion
 | `--header/--no-header` | | `--header` | Print info lines before rendering |
 | `--cushion/--no-cushion` | | `--cushion` | Apply van Wijk cushion shading for a raised 3-D look |
 | `--log/--no-log` | | `--no-log` | Use log of file sizes for layout, making small files more visible |
+| `--password` | | — | Password for encrypted archives; prompted interactively if not supplied and needed |
+| `--github-token` | | `$GITHUB_TOKEN` | GitHub personal access token for private repos or higher rate limits |
 
 ## Inline Display
 
@@ -159,30 +192,82 @@ The default mode (`--show`, no `--inline`) opens the PNG in the system viewer (`
 
 > **Windows note:** Common Windows shells (PowerShell, cmd, Git Bash) and terminal emulators (Windows Terminal, ConEmu) do not support any inline image protocol. `--inline` will silently produce no output in these environments. [WezTerm](https://wezfurlong.org/wezterm/) is currently the only mainstream Windows terminal emulator that supports inline image rendering (via the Kitty graphics protocol). WSL2 is treated as Linux and has full support.
 
+> **Tip:** In terminals that support inline images (iTerm2, WezTerm, Kitty, etc.), the rendered image can often be dragged directly out of the terminal window and dropped into another application or saved to the desktop — no `--output` needed. This drag-and-drop behaviour is not guaranteed across all terminals.
+
 > **Note:** `--inline` does not work in AI coding assistants such as Claude Code, Cursor, or GitHub Copilot Chat. These tools intercept terminal output as plain text and do not implement any graphics protocol, so the escape sequences are either stripped or displayed as garbage. Use the default `--show` mode (system viewer) or `--output` to save the PNG to a file instead. Or use [Pi](https://pi.dev) where it is easily added as an extension.
 
+## Archives
+
+dirplot can read local archive files without unpacking them — zip, tar (gz/bz2/xz/zst), 7z, rar, and many more via libarchive (iso, cpio, rpm, cab, lha, xar, and all ZIP-based formats like jar, whl, apk, nupkg, vsix, ipa). See [ARCHIVES.md](docs/ARCHIVES.md) for the full list, dependencies, and platform notes.
+
+```bash
+dirplot map project.zip
+dirplot map release.tar.gz --depth 2
+dirplot map app.jar
+```
+
+## Remote Access
+
+dirplot can scan SSH hosts, AWS S3 buckets, GitHub repositories, running Docker containers, and Kubernetes pods. See [EXAMPLES.md](docs/EXAMPLES.md) for full details.
+
+```bash
+pip install "dirplot[ssh]"   # SSH via paramiko
+pip install "dirplot[s3]"    # AWS S3 via boto3
+                             # GitHub: no extra dependency needed
+                             # Docker: only the docker CLI required
+                             # Kubernetes: only kubectl required
+```
+
+```bash
+dirplot map ssh://alice@prod.example.com/var/www
+dirplot map s3://noaa-ghcn-pds --no-sign
+dirplot map github://pallets/flask
+dirplot map github://torvalds/linux@v6.12/Documentation
+dirplot map docker://my-container:/app
+dirplot map pod://my-pod:/app
+dirplot map pod://my-pod@staging:/app
+```
+
+### GitHub authentication
+
+Public repositories work without a token but are subject to GitHub's unauthenticated rate limit of **60 requests/hour**. A personal access token raises this to **5,000 requests/hour** and is required for private repositories.
+
+Pass a token via the `--github-token` flag or the `GITHUB_TOKEN` environment variable:
+
+```bash
+# via flag
+dirplot map github://my-org/private-repo --github-token ghp_…
+
+# via environment variable (also picked up automatically by the CLI)
+export GITHUB_TOKEN=ghp_…
+dirplot map github://my-org/private-repo
+```
+
+To create a token: GitHub → Settings → Developer settings → Personal access tokens → Generate new token (see [GitHub's guide](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)). For read-only treemap access the `public_repo` scope (or no scope for public repos) is sufficient; add `repo` for private repositories.
+
 ## Python API
 
-The public API is small — `build_tree`, `create_treemap`, and the display helpers:
+> **Note:** The programmatic Python API is still evolving and may change between releases without notice. Pin a specific version if you depend on it. The CLI interface is stable.
+
+The public API is small — `build_tree`, `create_treemap`, `create_treemap_svg`, and the display helpers:
 
 ```python
 from pathlib import Path
-from dirplot.scanner import build_tree
-from dirplot.render import create_treemap
+from dirplot import build_tree, create_treemap, create_treemap_svg
 
-# Build the tree and render to a PNG in memory
 root = build_tree(Path("/path/to/project"))
-buf = create_treemap(root, width_px=1920, height_px=1080, colormap="tab20", cushion=True)
 
-# Save to disk
+# PNG — returns a BytesIO containing PNG bytes
+buf = create_treemap(root, width_px=1920, height_px=1080, colormap="tab20", cushion=True)
 Path("treemap.png").write_bytes(buf.read())
 
-# In a Jupyter notebook: display inline as a cell output (no save needed)
-from PIL import Image
-Image.open(buf)  # Jupyter renders PIL images automatically via _repr_png_()
+# SVG — returns a BytesIO containing UTF-8 SVG bytes
+# Includes CSS hover highlight, a JS floating tooltip, and cushion gradient shading.
+buf = create_treemap_svg(root, width_px=1920, height_px=1080, cushion=True)
+Path("treemap.svg").write_bytes(buf.read())
 ```
 
-To open the result in the system image viewer or display it inline:
+To open a PNG in the system image viewer or display it inline in the terminal:
 
 ```python
 from dirplot.display import display_window, display_inline
@@ -194,6 +279,14 @@ buf.seek(0)
 display_inline(buf)   # inline in terminal (iTerm2 / Kitty / WezTerm)
 ```
 
+In a Jupyter notebook, PNG output renders automatically via PIL:
+
+```python
+from PIL import Image
+buf = create_treemap(root, width_px=1280, height_px=720)
+Image.open(buf)  # Jupyter renders PIL images automatically via _repr_png_()
+```
+
 ## Development
 
 ```bash

{dirplot-0.2.0 → dirplot-0.3.1}/README.md

@@ -20,10 +20,14 @@
 - Label colour (black/white) chosen automatically based on background luminance.
 - Output resolution matches the current terminal window pixel size (via `TIOCGWINSZ`), or a custom `WIDTHxHEIGHT`.
 - Van Wijk cushion shading gives tiles a raised 3-D appearance (optional).
+- **SVG output** (`--format svg` or `--output file.svg`) produces a fully self-contained interactive file: CSS hover highlight, a JavaScript floating tooltip panel, and cushion shading via a gradient — no external dependencies.
 - Display via system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected).
-- Save output to a PNG file with `--output`.
+- Save output to a PNG or SVG file with `--output`.
 - Exclude paths with `--exclude` (repeatable).
 - Works on macOS, Linux, and Windows; WSL2 fully supported.
+- Scan remote hosts over SSH (`pip install "dirplot[ssh]"`), AWS S3 buckets (`pip install "dirplot[s3]"`), any public/private GitHub repository (including specific branch, tag, commit SHA, or subdirectory), **running Docker containers**, or **Kubernetes pods** — all without extra dependencies beyond the respective CLI/SDK. See [EXAMPLES.md](docs/EXAMPLES.md).
+- Optional **file-count legend** (`--legend`) — a corner overlay listing the top extensions by number of files, with coloured swatches and counts, automatically sized to fit the image.
+- **Wide archive support** — reads zip, tar (gz/bz2/xz/zst), 7z, rar, and via libarchive: iso, cpio, rpm, cab, lha/lzh, xar/pkg, a/ar, and all ZIP-based formats (jar, whl, apk, nupkg, vsix, ipa, …) as virtual directory trees without unpacking. Encrypted archives are handled gracefully: metadata-only reads work without a password for most formats; a password can be supplied with `--password` or entered interactively when needed.
 
 ## How It Works
 
@@ -67,35 +71,51 @@ This tool has been developed and tested on macOS and is CI-tested on Linux and W
 uvx dirplot --help
 
 # Show dirplot for the current directory (opens image in system viewer)
-dirplot .
+dirplot map .
+
+# Show current terminal size in characters and pixels
+dirplot termsize
 
 # Save to a file without displaying
-dirplot . --output dirplot.png --no-show
+dirplot map . --output dirplot.png --no-show
 
 # Display inline (protocol auto-detected: iTerm2, Kitty, Ghostty)
-dirplot . --inline
+dirplot map . --inline
 
 # Exclude directories
-dirplot . --exclude .venv --exclude .git
+dirplot map . --exclude .venv --exclude .git
 
 # Use a different colormap and larger directory labels
-dirplot . --colormap Set2 --font-size 18
+dirplot map . --colormap Set2 --font-size 18
 
 # Render at a fixed resolution instead of terminal size
-dirplot . --size 1920x1080 --output dirplot.png --no-show
+dirplot map . --size 1920x1080 --output dirplot.png --no-show
 
 # Don't apply cushion shading — makes tiles look flat
-dirplot . --no-cushion
+dirplot map . --no-cushion
+
+# Show a file-count legend (top 20 extensions by default)
+dirplot map . --legend
+
+# Show a file-count legend limited to 10 entries
+dirplot map . --legend 10
+
+# Save as an interactive SVG (hover highlight + floating tooltip)
+dirplot map . --output treemap.svg --no-show
+
+# Force SVG format explicitly
+dirplot map . --format svg --output treemap.svg --no-show
 ```
 
 ### Options
 
 | Flag | Short | Default | Description |
 |---|---|---|---|
-| `--output` | `-o` | — | Save PNG to this path |
+| `--output` | `-o` | — | Save to this path (PNG or SVG) |
+| `--format` | `-f` | auto | Output format: `png` or `svg`. Auto-detected from `--output` extension |
 | `--show/--no-show` | | `--show` | Display the image after rendering |
-| `--inline` | | off | Display in terminal (protocol auto-detected) |
-| `--legend/--no-legend` | | `--no-legend` | Show file-extension colour legend |
+| `--inline` | | off | Display in terminal (protocol auto-detected; PNG only) |
+| `--legend [N]` | | off | Show file-count legend; `N` sets max entries (default: 20) |
 | `--font-size` | `-s` | `12` | Directory label font size in pixels |
 | `--colormap` | `-c` | `tab20` | Matplotlib colormap for unknown extensions |
 | `--exclude` | `-e` | — | Path to exclude (repeatable) |
@@ -103,6 +123,8 @@ dirplot . --no-cushion
 | `--header/--no-header` | | `--header` | Print info lines before rendering |
 | `--cushion/--no-cushion` | | `--cushion` | Apply van Wijk cushion shading for a raised 3-D look |
 | `--log/--no-log` | | `--no-log` | Use log of file sizes for layout, making small files more visible |
+| `--password` | | — | Password for encrypted archives; prompted interactively if not supplied and needed |
+| `--github-token` | | `$GITHUB_TOKEN` | GitHub personal access token for private repos or higher rate limits |
 
 ## Inline Display
 
@@ -121,30 +143,82 @@ The default mode (`--show`, no `--inline`) opens the PNG in the system viewer (`
 
 > **Windows note:** Common Windows shells (PowerShell, cmd, Git Bash) and terminal emulators (Windows Terminal, ConEmu) do not support any inline image protocol. `--inline` will silently produce no output in these environments. [WezTerm](https://wezfurlong.org/wezterm/) is currently the only mainstream Windows terminal emulator that supports inline image rendering (via the Kitty graphics protocol). WSL2 is treated as Linux and has full support.
 
+> **Tip:** In terminals that support inline images (iTerm2, WezTerm, Kitty, etc.), the rendered image can often be dragged directly out of the terminal window and dropped into another application or saved to the desktop — no `--output` needed. This drag-and-drop behaviour is not guaranteed across all terminals.
+
 > **Note:** `--inline` does not work in AI coding assistants such as Claude Code, Cursor, or GitHub Copilot Chat. These tools intercept terminal output as plain text and do not implement any graphics protocol, so the escape sequences are either stripped or displayed as garbage. Use the default `--show` mode (system viewer) or `--output` to save the PNG to a file instead. Or use [Pi](https://pi.dev) where it is easily added as an extension.
 
+## Archives
+
+dirplot can read local archive files without unpacking them — zip, tar (gz/bz2/xz/zst), 7z, rar, and many more via libarchive (iso, cpio, rpm, cab, lha, xar, and all ZIP-based formats like jar, whl, apk, nupkg, vsix, ipa). See [ARCHIVES.md](docs/ARCHIVES.md) for the full list, dependencies, and platform notes.
+
+```bash
+dirplot map project.zip
+dirplot map release.tar.gz --depth 2
+dirplot map app.jar
+```
+
+## Remote Access
+
+dirplot can scan SSH hosts, AWS S3 buckets, GitHub repositories, running Docker containers, and Kubernetes pods. See [EXAMPLES.md](docs/EXAMPLES.md) for full details.
+
+```bash
+pip install "dirplot[ssh]"   # SSH via paramiko
+pip install "dirplot[s3]"    # AWS S3 via boto3
+                             # GitHub: no extra dependency needed
+                             # Docker: only the docker CLI required
+                             # Kubernetes: only kubectl required
+```
+
+```bash
+dirplot map ssh://alice@prod.example.com/var/www
+dirplot map s3://noaa-ghcn-pds --no-sign
+dirplot map github://pallets/flask
+dirplot map github://torvalds/linux@v6.12/Documentation
+dirplot map docker://my-container:/app
+dirplot map pod://my-pod:/app
+dirplot map pod://my-pod@staging:/app
+```
+
+### GitHub authentication
+
+Public repositories work without a token but are subject to GitHub's unauthenticated rate limit of **60 requests/hour**. A personal access token raises this to **5,000 requests/hour** and is required for private repositories.
+
+Pass a token via the `--github-token` flag or the `GITHUB_TOKEN` environment variable:
+
+```bash
+# via flag
+dirplot map github://my-org/private-repo --github-token ghp_…
+
+# via environment variable (also picked up automatically by the CLI)
+export GITHUB_TOKEN=ghp_…
+dirplot map github://my-org/private-repo
+```
+
+To create a token: GitHub → Settings → Developer settings → Personal access tokens → Generate new token (see [GitHub's guide](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)). For read-only treemap access the `public_repo` scope (or no scope for public repos) is sufficient; add `repo` for private repositories.
+
 ## Python API
 
-The public API is small — `build_tree`, `create_treemap`, and the display helpers:
+> **Note:** The programmatic Python API is still evolving and may change between releases without notice. Pin a specific version if you depend on it. The CLI interface is stable.
+
+The public API is small — `build_tree`, `create_treemap`, `create_treemap_svg`, and the display helpers:
 
 ```python
 from pathlib import Path
-from dirplot.scanner import build_tree
-from dirplot.render import create_treemap
+from dirplot import build_tree, create_treemap, create_treemap_svg
 
-# Build the tree and render to a PNG in memory
 root = build_tree(Path("/path/to/project"))
-buf = create_treemap(root, width_px=1920, height_px=1080, colormap="tab20", cushion=True)
 
-# Save to disk
+# PNG — returns a BytesIO containing PNG bytes
+buf = create_treemap(root, width_px=1920, height_px=1080, colormap="tab20", cushion=True)
 Path("treemap.png").write_bytes(buf.read())
 
-# In a Jupyter notebook: display inline as a cell output (no save needed)
-from PIL import Image
-Image.open(buf)  # Jupyter renders PIL images automatically via _repr_png_()
+# SVG — returns a BytesIO containing UTF-8 SVG bytes
+# Includes CSS hover highlight, a JS floating tooltip, and cushion gradient shading.
+buf = create_treemap_svg(root, width_px=1920, height_px=1080, cushion=True)
+Path("treemap.svg").write_bytes(buf.read())
 ```
 
-To open the result in the system image viewer or display it inline:
+To open a PNG in the system image viewer or display it inline in the terminal:
 
 ```python
 from dirplot.display import display_window, display_inline
@@ -156,6 +230,14 @@ buf.seek(0)
 display_inline(buf)   # inline in terminal (iTerm2 / Kitty / WezTerm)
 ```
 
+In a Jupyter notebook, PNG output renders automatically via PIL:
+
+```python
+from PIL import Image
+buf = create_treemap(root, width_px=1280, height_px=720)
+Image.open(buf)  # Jupyter renders PIL images automatically via _repr_png_()
+```
+
 ## Development
 
 ```bash

{dirplot-0.2.0 → dirplot-0.3.1}/SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 0.1.x   | :white_check_mark: |
+| 0.3.x   | :white_check_mark: |
 
 ## Reporting a Vulnerability