Code Filetree Structure

src/
├── grab-api/                   # Core Grab API library
│   ├── common/                 # Shared types and utilities
│   │   ├── types.ts            # Core TypeScript interfaces/types
│   │   └── utils.ts            # Common helper functions
│   ├── core/                   # Main orchestration logic
│   │   ├── cache-pagination.ts # Cache & infinite scroll state
│   │   ├── core.ts             # Main grab() implementation
│   │   ├── flow-control.ts     # Debounce & repeat logic
│   │   ├── regrab-events.ts    # Refetch event listeners
│   │   └── request-executor.ts # Fetch & mock execution
│   ├── logging/                # Output formatting
│   │   ├── colors.ts           # ANSI terminal colors
│   │   ├── log-json.ts         # Colorized JSON logger
│   │   └── structure.ts        # TypeDoc-style JSON describer
│   ├── response/               # Post-fetch handling
│   │   ├── infinite-scroll.ts  # DOM scroll & persistence
│   │   └── response-handler.ts # Fetch result mapping
│   ├── ui/                     # Browser-side UI
│   │   └── devtools.ts         # Visual alert system
│   └── index.ts                # Main library entry point
│
├── grab-url-cli/                # Command-Line Interface
│   ├── arg-parser.ts           # Minimal argument parser
│   ├── download-format.ts      # UI/Progress formatting
│   ├── download-keyboard.ts    # Interactive controls
│   ├── download-multi.ts       # Concurrent file downloader
│   ├── download-single.ts      # Single file download driver
│   ├── download-spinners.ts    # Spinner animations logic
│   ├── download-state.ts       # Resume-state persistence
│   ├── downloader.ts           # High-level CLI orchestrator
│   └── index.ts                # CLI entry point
│
└── icons/                      # Assets & animations
    ├── cli/
    │   └── spinners.js         # CLI spinner frames
    └── svg/                    # SVG loading animations
        ├── index.ts            # SVG string exports
        └── (various).svg       # Individual SVG assets

📄 Component Descriptions

Grab API (src/grab-api/)

The core library used to generate API requests. It supports both Browser and Node.js environments.

• index.ts: The main entry point. It exports the grab function and log utility, sets up global instances, and initializes browser devtools.
• common/types.ts: Contains all TypeScript definitions for request options, response shapes, and mock configurations.
• common/utils.ts: Provides low-level utilities like debouncer, wait (sleep), and buildUrl.
• core/core.ts: The heart of the library. Orchestrates the flow from option merging to final response mapping.
• core/flow-control.ts: Manages non-network request flow such as debouncing and repeating requests.
• core/request-executor.ts: Handles the actual network fetch call or returns mock data if configured.
• core/cache-pagination.ts: Decides if a request should be served from cache and increments page numbers for infinite scrolling.
• core/regrab-events.ts: Sets up listeners (window focus, online status) to automatically refetch data.
• logging/log-json.ts: A robust logger that outputs colorized, structured JSON to the console.
• response/response-handler.ts: Transforms raw fetch responses into the predictable GrabResponse format.
• response/infinite-scroll.ts: Logic for appending paginated results and saving/restoring scroll position in browsers.
• ui/devtools.ts: Implements a floating visual alert/notification system for the browser.

Grab-URL CLI (src/grab-url-cli/)

The command-line tool built on top of the Grab API, specializing in file downloads and quick API prototyping.

• index.ts: Parses CLI arguments and switches between "API Mode" (fetching data) and "Download Mode" (multi-file progress bars).
• arg-parser.ts: A custom, lightweight alternative to yargs for parsing flags and positional URLs.
• downloader.ts: An orchestrator class that coordinates formatting, state, and keyboard modules for a unified download experience.
• download-format.ts: Pure functions for converting bytes to human-readable strings, calculating ETAs, and building progress bars.
• download-state.ts: Handles .download-state sidecar files to allow resuming interrupted downloads.
• download-keyboard.ts: Listens for keypresses (like 'p' for pause) during active downloads.
• download-multi.ts: Manages a pool of concurrent downloads using a multi-progress bar display.
• download-single.ts: The driver logic for streaming a single file to disk with progress updates.
• download-spinners.ts: Selects and animates randomized spinner frames for a polished CLI look.

Icons & Assets (src/icons/)

Shared visual components for both CLI and Browser UIs.

• cli/spinners.js: A collection of character-based animation frames for terminal spinners.
• svg/index.ts: Exports SVG animations as strings, allowing them to be easily imported and used in the grab-api devtools.
• svg/*.svg: Raw SVG files for various loading animations (pacman, ripple, etc.).