behance-dl 0.1.0__tar.gz

behance_dl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # ubuntu-latest (26.04) no longer ships a Python 3.9 build, so the Linux jobs
+        # use 22.04 where every supported interpreter is available.
+        os: [ubuntu-22.04, windows-latest, macos-latest]
+        python-version: ["3.9", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install the package and its test tools
+        run: python -m pip install -e ".[dev]"
+      - name: Run the tests
+        run: python -m pytest --cov=behance_dl --cov-report=term-missing
+
+  lint:
+    name: Lint and format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install the package and its test tools
+        run: python -m pip install -e ".[dev]"
+      - name: Check lint rules
+        run: ruff check .
+      - name: Check formatting
+        run: ruff format --check .
+      - name: Check that the package builds
+        run: python -m build

behance_dl-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build the distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install the build tool
+        run: python -m pip install build
+      - name: Build the wheel and sdist
+        run: python -m build
+      - name: Store the distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Upload to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/behance-dl
+    permissions:
+      id-token: write
+    steps:
+      - name: Fetch the distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

behance_dl-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Byte-compiled files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build and distribution output
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test and coverage output
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tool caches
+.ruff_cache/
+.mypy_cache/
+
+# Editors and operating systems
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

behance_dl-0.1.0/AGENTS.md

@@ -0,0 +1,245 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents when working with code in this repository.
+
+## Project Overview
+
+`behance-dl` is a command line downloader for public Behance project galleries, published to PyPI as `behance-dl` with the import package `behance_dl`.
+
+It reads the project payload Behance inlines in a gallery page (`beconfig-store_state`), chooses one CDN variant per image, and downloads the files concurrently with resume support. It keeps gallery order, records which variant produced each file in `manifest.json`, and records prototypes and video modules as links in `embeds.json`.
+
+Technology stack: Python 3.9 or newer, standard library only at runtime, Hatchling for the build, pytest for tests, Ruff for lint and format, GitHub Actions for CI and publishing.
+
+Key behaviours that must not regress:
+
+- Gallery pages answer 404 for `/gallery/{id}` with no slug, so requests use `/gallery/{id}/gallery`.
+- Behance answers 403 with a cookie challenge. The client sets `js_challenge_value` and retries once with a fresh `Request`, because a reused request keeps the stale `Cookie` header.
+- Variant ranking prefers `source`, then a plain bucket, then an `_opt_` copy, and drops `_still` buckets whenever an animated variant exists. A still bucket holds only the first frame of an animated image.
+- Only `https` URLs on `behance.net` or a `.behance.net` subdomain may be requested. The page payload is untrusted input.
+- The CDN sometimes serves JPEG bytes under a `.png` name, so the saved extension comes from the file's magic bytes.
+
+## Prerequisites
+
+- Python 3.9 or newer. The floor exists because `ThreadPoolExecutor.shutdown(cancel_futures=True)` requires 3.9.
+- `pip` and `venv` from the same interpreter.
+- No external services, credentials, or API keys. Behance is accessed anonymously.
+- Windows is the primary development platform, and CI also runs Linux and macOS.
+
+## Core Philosophy
+
+### Trade-off Priority (when conflicts arise)
+
+1. **Correctness**: the download matches the gallery and the record stays truthful.
+2. **Simplicity and readability**: one small function per job, standard library first.
+3. **Testability**: network access sits behind `BehanceClient`, so tests use fakes.
+4. **Performance**: parallel downloads and streaming transfers, without speculative optimisation.
+5. **Abstraction and reuse**: extract only when duplication is already costing more than a shared helper.
+
+### Ground Rules
+
+- Read and understand the existing module before changing it, and preserve the behaviours listed in Project Overview.
+- If a requirement is ambiguous, ask before writing code.
+- Do not overengineer. Build for today's requirements.
+- A change to `BehanceClient`, the payload parsing, or the manifest format affects every command, so verify the touched paths end to end.
+
+## Design Principles
+
+### SOLID
+
+| Principle | Rule | Common Mistake |
+|-----------|------|----------------|
+| **SRP** (Single Responsibility) | Each module has one axis of change. `client` speaks HTTP, `gallery` parses payloads, `selection` ranks variants, `storage` writes files, `cli` parses arguments and reports. | Putting reporting inside the save step, or network calls inside selection. |
+| **OCP** (Open/Closed) | Add a new module type by extending the dispatch in `gallery.image_sources` and `gallery.embed_assets`. | Scattering module-type checks across several functions. |
+| **LSP** (Liskov Substitution) | A fake client used in tests must honour the same contract as `BehanceClient`. | A fake that returns bodies the real client would reject. |
+| **ISP** (Interface Segregation) | Fakes implement only `get_text` and `download`, which is all the planning and saving code uses. | A test double exposing unrelated helpers. |
+| **DIP** (Dependency Inversion) | `plan_gallery` and `save_gallery` accept a client object rather than constructing one. | Constructing `BehanceClient` deep inside planning code. |
+
+### DRY, KISS, YAGNI
+
+- One rule lives in one place. The Behance host rule lives in `gallery.is_behance_host`, and the file-name rule lives in `naming.safe_name`.
+- Prefer duplication over a wrong abstraction. Two similar-looking expressions with different purposes stay separate.
+- Standard library before any dependency. Runtime dependencies stay at zero unless a feature genuinely needs one.
+- No speculative options, flags, or abstractions.
+
+## Language and Runtime Constraints
+
+The package supports Python 3.9, so these are unavailable at runtime:
+
+- `match`/`case` and PEP 604 unions in evaluated positions (3.10+).
+- Builtin generics in evaluated positions, such as `list[int]` (3.9+). Every module uses `from __future__ import annotations`, so annotations may use them, but runtime expressions may not.
+- `datetime.UTC`, `itertools.batched`, and `tomllib` (3.11+).
+- Exception groups (3.11+).
+
+Keep `from __future__ import annotations` at the top of every module.
+
+## Code Quality
+
+### Linting and Formatting
+
+- Ruff handles both linting and formatting, configured in `pyproject.toml` at line length 100.
+- After changing files, run `ruff check .` and `ruff format .`. Both must pass before a change is complete.
+- Fix a violation before configuring or suppressing it. Use a per-line `noqa` only for a genuine false positive, and never a blanket suppression.
+- `tests/conftest.py` is the shared test double module, registered as first-party for import sorting.
+
+### Naming
+
+- Functions start with a verb, classes are nouns, and booleans read as a yes/no question.
+- No generic names such as `data`, `result`, `obj`, `thing`, `temp`, or `utils`.
+- No abbreviations beyond universally understood ones. `url` inside a tuple unpacking may stay lowercase when it names the element, and prose uses `URL`.
+- One concept keeps one name across modules. A saved image is a `SavedImage` in the record, an `ImageAsset` when planned, and a `StoredImage` when written.
+
+### Strong Typing
+
+- Annotate every public function's parameters and return value.
+- Avoid `Any` except where a JSON payload is genuinely untyped, and narrow it immediately with `isinstance` checks.
+- Do not cast to `Any` to make an error disappear.
+
+### Immutability
+
+- Dataclasses are frozen. Return new objects instead of mutating inputs.
+- Never expose a mutable internal collection. `GalleryProject.modules` is a tuple.
+
+### Early Returns and Guard Clauses
+
+- Put the happy path at the lowest nesting level and return early for the failure case.
+- Repeated numbers and strings become named constants, such as `RETRYABLE_STATUS` and `TRANSFER_BLOCK_SIZE`.
+
+### Comments and Docstrings
+
+- Write a comment only when it explains why, never what.
+- A docstring states the unit's purpose without restating its signature or parameters.
+- Comments and docstrings must make sense to a cold reader. No references to reviews, tickets, or conversations.
+- Never use em-dashes or en-dashes, and never use a hyphen as a clause separator. End the sentence or use a comma.
+
+### Functions
+
+- One job per function. No boolean parameter that switches behaviour.
+- Pass a callback rather than a flag when the caller needs to react to per-item results, as `download_images` does with `on_saved`.
+
+### Output Conventions
+
+- Progress and plans go to standard output. Warnings and errors go to standard error.
+- Exit codes: `0` success, `1` a gallery failed, `2` invalid arguments, `130` interrupted.
+- Never log or print credentials, and there are none to print.
+
+## Architecture
+
+### Module Layout
+
+| Module | Responsibility |
+|--------|----------------|
+| `client.py` | HTTP session, cookie challenge, retries, atomic image transfers. |
+| `gallery.py` | Behance host and URL rules, gallery id parsing, payload parsing, module walking. |
+| `selection.py` | Bucket ranking, variant selection, building a `GalleryPlan`. |
+| `storage.py` | Manifest reading and writing, parallel downloads, metadata files. |
+| `models.py` | Frozen dataclasses shared across modules. |
+| `naming.py` | File-name safety rules. |
+| `errors.py` | `BehanceError`, `GalleryError`, `DownloadError`. |
+| `cli.py` | Argument parsing, reporting, exit codes. |
+
+### Dependency Direction
+
+`cli` depends on `selection` and `storage`. `selection` depends on `gallery` and `models`. `storage` depends on `client` and `models`. `gallery` depends on `client` and `models`. `models` and `naming` depend on nothing local. No module imports `cli`, and no cycles are allowed.
+
+### Layer Rules
+
+- Network access happens only in `client.py`.
+- Filesystem writes happen only in `storage.py`.
+- Selection works on plain payload dictionaries and never performs IO.
+- Errors cross module boundaries as `BehanceError` subclasses, and `cli.main` is the single place that converts them to exit codes.
+
+## Error Handling
+
+- Define domain errors in `errors.py`. Do not raise bare `Exception` or `RuntimeError` directly.
+- Chain re-raises explicitly with `from error` to preserve the cause.
+- Convert untrusted payload shapes into `GalleryError` with enough context to identify the gallery.
+- A single failed image must not abort a gallery, and a single failed gallery must not abort a batch.
+- An interruption must leave the record truthful, so record each image as soon as it lands.
+- Never fail a run because cleanup or bookkeeping failed. Warn and continue.
+
+## Security
+
+### Input Validation and Injection
+
+- Treat every value in the page payload as untrusted.
+- Only `https` URLs on `behance.net` or a `.behance.net` subdomain may be requested. Enforce it in `gallery.is_behance_url` and never bypass it.
+- Never build a file path from raw remote text. Pass names through `naming.safe_name`, and validate recorded names with `naming.is_plain_file_name`.
+- A recorded path must stay inside the gallery folder and share the planned stem.
+- Reject a response whose content type is not `image/*`, or whose bytes match no known image magic.
+
+### Secrets Management
+
+- Never commit credentials, tokens, or API keys.
+- Never place a secret in a workflow file, a test fixture, or a log line.
+
+### Dependencies and Supply Chain
+
+- Runtime dependencies stay at zero.
+- Development dependencies are pinned by floor in `pyproject.toml` and resolved in CI.
+- Do not add a dependency with a known vulnerability that affects this code.
+
+## Testing
+
+> **Test code is production code.** It receives the same care, review, and quality standards.
+
+### Core Principles
+
+- Tests must never touch the network. Use the fakes in `tests/conftest.py`, or stub `_opener` on `BehanceClient`.
+- Follow Arrange-Act-Assert, with one act and one logical assertion per test.
+- Tests must be independent, deterministic, and order-agnostic.
+- Pin specific exception types in `pytest.raises`.
+- Test behaviour through public functions. Stubbing `client._opener` is the accepted exception, because the cookie jar has no other seam.
+- Cover the happy path and adversarial cases: hostile URLs, malformed payloads, unreadable manifests, truncated transfers, and locked files.
+- Add a regression test for every bug fixed.
+
+### How to Run Tests
+
+```powershell
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+ruff format --check .
+python -m build
+```
+
+On Linux or macOS, activate with `source .venv/bin/activate` and call the tools as `python -m pytest`, `python -m ruff`, and `python -m build`.
+
+### Test Naming
+
+- pytest collects `test_` functions. Use `test_[subject]_[aspect]` as the default, for example `test_still_bucket_dropped_when_animated_variant_exists`.
+- Use `test_[behaviour]` only when splitting into subject and aspect would be artificial.
+- Do not encode assertion types or fixture names in a test name.
+
+### Test File Rules
+
+- One file per module under test: `test_client.py`, `test_gallery.py`, `test_selection.py`, `test_storage.py`, `test_naming.py`, `test_cli.py`.
+- Shared doubles and payload builders live in `tests/conftest.py`, and test-local helpers stay in the test module that uses them.
+
+### Coverage
+
+- **Minimum acceptable: 85%**, measured with branch coverage.
+- Run `pytest --cov=behance_dl --cov-report=term-missing` and report the result for the touched modules.
+
+### All Created Tests MUST Pass
+
+- Every test you create or modify must pass, with zero failures and zero skips.
+- Never disable, skip, or delete a test to hide a failure. Fix the code first when the code is wrong.
+- When a test fails, decide whether the code or the test is wrong before editing either.
+
+### Anti-Patterns (Forbidden)
+
+- A test that asserts nothing.
+- A test that mocks the unit under test.
+- A test that depends on the order of other tests.
+- A fake that returns data the real client would reject.
+
+## Versioning
+
+- The version lives in `src/behance_dl/__init__.py` and Hatchling reads it from there, so bump it in one place.
+- Every release must come from a working tree with passing tests, passing lint, and no uncommitted changes.
+
+## Rule of Thumb
+
+**When in doubt: correctness over cleverness, one honest record over a silent skip, and a clear error over a wrong file on disk.**

behance_dl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Elian Kevin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

behance_dl-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.5
+Name: behance-dl
+Version: 0.1.0
+Summary: Download the images of public Behance project galleries.
+Project-URL: Homepage, https://github.com/kevinkwee/behance-dl
+Project-URL: Repository, https://github.com/kevinkwee/behance-dl
+Project-URL: Issues, https://github.com/kevinkwee/behance-dl/issues
+Project-URL: Releases, https://github.com/kevinkwee/behance-dl/releases
+Author-email: Michael Elian Kevin <19345886+kevinkwee@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: behance,cli,downloader,gallery,portfolio
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# behance-dl
+
+Download the images of a public [Behance](https://www.behance.net) project gallery.
+
+`behance-dl` reads the project data Behance inlines in the gallery page, picks the best CDN
+variant of every image, and downloads them in parallel with resume support. It keeps the
+gallery order, records which variant produced each file, and logs the content it cannot
+download as files (prototypes, video players) so nothing is silently lost.
+
+No API key, account, or browser automation is required.
+
+> Not affiliated with Behance or Adobe. Use it for offline viewing of published work, and
+> respect each creator's licence before redistributing anything.
+
+## Install
+
+```console
+pip install behance-dl
+```
+
+Requires Python 3.9 or newer. No third-party runtime dependencies.
+
+## Usage
+
+```console
+behance-dl "https://www.behance.net/gallery/123456789/Sample-Gallery"
+```
+
+Every gallery argument can be a full Behance URL, with or without query parameters, or a
+bare project id:
+
+```console
+behance-dl 123456789
+behance-dl "https://www.behance.net/gallery/123456789/Sample-Gallery?l=22"
+behance-dl 123456789 234567890 345678901 -o downloads
+```
+
+### Options
+
+| Option | Meaning |
+| --- | --- |
+| `-o`, `--output DIR` | Folder that receives one subfolder per gallery. Default: current folder. |
+| `-W`, `--max-width PX` | Largest image at or below this width, else the smallest available. Default: the largest available. |
+| `-j`, `--workers N` | Parallel downloads. Default: 4. |
+| `--attempts N` | Attempts per request before giving up. Default: 3. |
+| `--timeout SECONDS` | Per-request timeout. Default: 30. |
+| `--force` | Ignore the saved record and fetch every image again. |
+| `--dry-run` | List what would be downloaded without writing anything. |
+| `--version` | Print the version and exit. |
+
+### What a gallery folder contains
+
+```text
+123456789_Sample-Gallery/
+  001_0a1b2c3123456789.5f6d7e8f9a0b1.png
+  002_4d5e6f7123456789.5f6d7e9a1c2d3.png
+  003_8a9b0c1123456789.5f6d7eab2e3f4.jpg
+  embeds.json      # prototypes and video players that are links, not files
+  manifest.json    # which CDN variant produced each saved file
+  project.json     # the full project payload Behance served
+```
+
+Files are prefixed with their position in the gallery, so a plain alphabetical listing
+follows the project order. The extension is taken from the file's magic bytes, because
+Behance's CDN sometimes serves JPEG data under a `.png` name.
+
+`embeds.json` records modules that cannot be downloaded as images, such as Figma prototypes
+and Adobe video players, with their source URL, caption and dimensions.
+
+## Re-running, resume and width changes
+
+`manifest.json` records the URL each file came from. A re-run only fetches what is missing,
+and a run with a different `-W` re-fetches the affected images instead of leaving files at
+the old size. An interrupted run keeps whatever already landed, so `Ctrl+C` followed by the
+same command continues where it stopped.
+
+Delete `manifest.json` (or pass `--force`) to fetch everything again.
+
+## How it works
+
+1. `GET https://www.behance.net/gallery/{id}/gallery`. Behance answers 404 for an id with no
+   trailing slug and ignores the slug itself, so any slug works.
+2. Behance answers 403 with a cookie challenge
+   (`document.cookie = "js_challenge_value=..."; location.reload()`). The client sets the
+   cookie and retries once. This is not a CAPTCHA and needs no credentials.
+3. The project payload is read from `<script id="beconfig-store_state">`. It lists every
+   module and every CDN variant of each image with its pixel width.
+4. Variants are filtered and ranked: WebP copies are skipped so the saved file matches the
+   original format, `_still` buckets are dropped when an animated variant exists (a still
+   bucket holds only the first frame of a GIF), and equal widths prefer `source` over a
+   plain bucket over an `_opt_` copy.
+5. Images are downloaded in a thread pool, each to a `.part` file that is verified against
+   `Content-Length`, checked for an image content type and real magic bytes, then renamed
+   into place.
+
+`MediaCollectionModule` carousels are expanded into one file per component. Only URLs on
+`https://*.behance.net` are ever requested, so a tampered payload cannot point the tool at
+a local file or a third-party host.
+
+## Limitations
+
+- Only public projects. Private, removed, or login-gated projects report a clear error.
+- Images only. Prototypes and video modules are recorded as links in `embeds.json`.
+- Behance can change its page format at any time; the payload shape is checked and a
+  mismatch is reported as an error instead of producing an empty folder.
+
+## Development
+
+```console
+python -m venv .venv
+.venv\Scripts\activate        # Windows
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

behance_dl-0.1.0/README.md

@@ -0,0 +1,119 @@
+# behance-dl
+
+Download the images of a public [Behance](https://www.behance.net) project gallery.
+
+`behance-dl` reads the project data Behance inlines in the gallery page, picks the best CDN
+variant of every image, and downloads them in parallel with resume support. It keeps the
+gallery order, records which variant produced each file, and logs the content it cannot
+download as files (prototypes, video players) so nothing is silently lost.
+
+No API key, account, or browser automation is required.
+
+> Not affiliated with Behance or Adobe. Use it for offline viewing of published work, and
+> respect each creator's licence before redistributing anything.
+
+## Install
+
+```console
+pip install behance-dl
+```
+
+Requires Python 3.9 or newer. No third-party runtime dependencies.
+
+## Usage
+
+```console
+behance-dl "https://www.behance.net/gallery/123456789/Sample-Gallery"
+```
+
+Every gallery argument can be a full Behance URL, with or without query parameters, or a
+bare project id:
+
+```console
+behance-dl 123456789
+behance-dl "https://www.behance.net/gallery/123456789/Sample-Gallery?l=22"
+behance-dl 123456789 234567890 345678901 -o downloads
+```
+
+### Options
+
+| Option | Meaning |
+| --- | --- |
+| `-o`, `--output DIR` | Folder that receives one subfolder per gallery. Default: current folder. |
+| `-W`, `--max-width PX` | Largest image at or below this width, else the smallest available. Default: the largest available. |
+| `-j`, `--workers N` | Parallel downloads. Default: 4. |
+| `--attempts N` | Attempts per request before giving up. Default: 3. |
+| `--timeout SECONDS` | Per-request timeout. Default: 30. |
+| `--force` | Ignore the saved record and fetch every image again. |
+| `--dry-run` | List what would be downloaded without writing anything. |
+| `--version` | Print the version and exit. |
+
+### What a gallery folder contains
+
+```text
+123456789_Sample-Gallery/
+  001_0a1b2c3123456789.5f6d7e8f9a0b1.png
+  002_4d5e6f7123456789.5f6d7e9a1c2d3.png
+  003_8a9b0c1123456789.5f6d7eab2e3f4.jpg
+  embeds.json      # prototypes and video players that are links, not files
+  manifest.json    # which CDN variant produced each saved file
+  project.json     # the full project payload Behance served
+```
+
+Files are prefixed with their position in the gallery, so a plain alphabetical listing
+follows the project order. The extension is taken from the file's magic bytes, because
+Behance's CDN sometimes serves JPEG data under a `.png` name.
+
+`embeds.json` records modules that cannot be downloaded as images, such as Figma prototypes
+and Adobe video players, with their source URL, caption and dimensions.
+
+## Re-running, resume and width changes
+
+`manifest.json` records the URL each file came from. A re-run only fetches what is missing,
+and a run with a different `-W` re-fetches the affected images instead of leaving files at
+the old size. An interrupted run keeps whatever already landed, so `Ctrl+C` followed by the
+same command continues where it stopped.
+
+Delete `manifest.json` (or pass `--force`) to fetch everything again.
+
+## How it works
+
+1. `GET https://www.behance.net/gallery/{id}/gallery`. Behance answers 404 for an id with no
+   trailing slug and ignores the slug itself, so any slug works.
+2. Behance answers 403 with a cookie challenge
+   (`document.cookie = "js_challenge_value=..."; location.reload()`). The client sets the
+   cookie and retries once. This is not a CAPTCHA and needs no credentials.
+3. The project payload is read from `<script id="beconfig-store_state">`. It lists every
+   module and every CDN variant of each image with its pixel width.
+4. Variants are filtered and ranked: WebP copies are skipped so the saved file matches the
+   original format, `_still` buckets are dropped when an animated variant exists (a still
+   bucket holds only the first frame of a GIF), and equal widths prefer `source` over a
+   plain bucket over an `_opt_` copy.
+5. Images are downloaded in a thread pool, each to a `.part` file that is verified against
+   `Content-Length`, checked for an image content type and real magic bytes, then renamed
+   into place.
+
+`MediaCollectionModule` carousels are expanded into one file per component. Only URLs on
+`https://*.behance.net` are ever requested, so a tampered payload cannot point the tool at
+a local file or a third-party host.
+
+## Limitations
+
+- Only public projects. Private, removed, or login-gated projects report a clear error.
+- Images only. Prototypes and video modules are recorded as links in `embeds.json`.
+- Behance can change its page format at any time; the payload shape is checked and a
+  mismatch is reported as an error instead of producing an empty folder.
+
+## Development
+
+```console
+python -m venv .venv
+.venv\Scripts\activate        # Windows
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).