feat: snapshot calculator

[LesnyRumcajs]

Summary of changes

Changes introduced in this pull request:

• this mostly works, but the dates on the filenames are non-deterministic and current Forest Archive API doesn't allow for easily figuring out the epoch to filename mapping. On hold until this is resolved.

Reference issue to close (if applicable)

Closes#6695

Other information and links

Change checklist

• I have performed a self-review of my own code,
• I have made corresponding changes to the documentation. All new code adheres to the team's documentation standards,
• I have added tests that prove my fix is effective or that my feature works (if possible),
• I have made sure the CHANGELOG is up-to-date. All user-facing changes should be reflected in this document.

Outside contributions

• I have read and agree to the CONTRIBUTING document.
• I have read and agree to the AI Policy document. I understand that failure to comply with the guidelines will lead to rejection of the pull request.

Summary by CodeRabbit

• New Features

  • Interactive Snapshot Calculator added to determine required archival snapshots and generate download scripts.
  • Supports multiple modes and networks (calibnet, mainnet).

• Documentation

  • New Snapshot Calculator guide explaining modes, requirements, and usage.
  • Archival Snapshots guide updated with tips recommending the Snapshot Calculator.

[coderabbitai]

Walkthrough

Adds an interactive Snapshot Calculator (React component + CSS) and a new docs page; also inserts two tip blocks into the archival snapshots guide recommending the calculator. The component computes required lite/diff snapshot specs, resolves availability from archive listings, and generates a download script.

Changes

Cohort / File(s)	Summary
Docs — guide & tips docs/docs/users/guides/advanced/archival_snapshots.md, docs/docs/users/guides/advanced/snapshot_calculator.mdx	Added a new Snapshot Calculator docs page and inserted two tip blocks in the archival snapshots guide pointing users to the interactive calculator and its download commands.
Snapshot Calculator UI & logic docs/src/components/SnapshotCalculator/index.tsx, docs/src/components/SnapshotCalculator/SnapshotCalculator.module.css	New React TypeScript component implementing epoch/network/mode inputs, spec generation (lite/diff), archive listing indexing, URL resolution, debounced input, download script generation, availability/status UI, and associated CSS styling and responsive layout.

Sequence Diagram(s)

sequenceDiagram
%% participants
participant User as User
participant UI as SnapshotCalculator (UI)
participant Archive as Archive Listings
participant Downloader as Download System
User->>UI: Enter epoch, select network & mode
UI->>UI: Compute current/base epochs and required snapshot specs
UI->>Archive: Fetch lite listing
UI->>Archive: Fetch diff listing
Archive-->>UI: Return listings
UI->>UI: Build index and resolve specs to URLs/status
UI->>UI: Generate bash/aria2c download script
UI-->>User: Display snapshot list, availability, warnings, and script
User->>Downloader: Copy/run script or click links to download

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

• akaladarshi
• sudo-shashank

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'feat: snapshot calculator' directly aligns with the main change: adding an interactive snapshot calculator tool to the documentation.
Linked Issues check	✅ Passed	The PR successfully implements all four coding-related requirements from issue #6695: documents snapshot structure, archival node setup, historical data retrieval use cases, and provides an interactive calculator tool for determining required snapshots.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #6695 requirements: documentation pages, the snapshot calculator component, styling, and utilities for determining and downloading archival snapshots.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch snapshot-list-tool

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[LesnyRumcajs]

Unblocked, now the archive supports format=json

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/src/components/SnapshotCalculator/index.tsx`:
- Around line 211-216: When reusing a cached index in the useEffect (check of
cacheRef.current[network]) clear the component error state so a stale warning
isn't shown; inside the early-return branch where you call setIndex(cached),
also reset the error state (e.g., call setError(false) or setError(undefined)
consistent with how error is represented) so that the banner is removed when a
valid cached index is used.
- Around line 174-180: The current endpoints.map block in SnapshotCalculator
(the async callback creating responses) swallows non-2xx responses by returning
an empty items array, which hides 404/500 as “no snapshots”; instead, when
resp.ok is false you should throw an Error (or reject) so Promise.all fails and
the caller can set listingError. Update the async map callback that calls
fetch(ep.url, { signal }) to throw a descriptive error including ep.url and
resp.status (and optionally resp.statusText) when !resp.ok, then parse
resp.json() into ListingResponse and return { type: ep.type, items: data.items
?? [] } as before.
- Around line 107-136: The download script currently treats any snapshot with
downloadUrl === null as "missing" even while listings are still loading; update
generateDownloadScript so the "missing" list only includes snapshots that are
definitively resolved-and-unavailable (e.g., change missing = snapshots.filter(s
=> s.downloadUrl === null && s.<resolvedFlag> === true) or s.status ===
'resolved' depending on the ResolvedSnapshot shape) while keeping available =
snapshots.filter(s => s.downloadUrl !== null); adjust the warning block to use
that new missing list so unresolved/loading entries are not reported as NOT
available.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 8223b02b-c23e-40e2-97c3-221724ea1009

📥 Commits

Reviewing files that changed from the base of the PR and between cef5e29 and dc6461b.

📒 Files selected for processing (4)

• docs/docs/users/guides/advanced/archival_snapshots.md
• docs/docs/users/guides/advanced/snapshot_calculator.mdx
• docs/src/components/SnapshotCalculator/SnapshotCalculator.module.css
• docs/src/components/SnapshotCalculator/index.tsx

[coderabbitai]

🧹 Nitpick comments (1)

docs/src/components/SnapshotCalculator/index.tsx (1)

291-293: Consider handling clipboard API errors.

navigator.clipboard.writeText returns a Promise that can reject (e.g., if permissions are denied or the API is unavailable). Silently ignoring failures may confuse users.

♻️ Optional: Add minimal error handling

 const handleCopyScript = () => {
- navigator.clipboard.writeText(downloadScript);+ navigator.clipboard.writeText(downloadScript).catch(() => {+ // Fallback or silent fail - clipboard may be unavailable+ });
};

Alternatively, provide user feedback on success/failure if desired.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.
In `@docs/src/components/SnapshotCalculator/index.tsx` around lines 291 - 293,
handleCopyScript currently calls navigator.clipboard.writeText(downloadScript)
without handling rejection; update the handleCopyScript function to await or
attach a .catch to navigator.clipboard.writeText(downloadScript) and handle
failures (e.g., show an error toast/console.error or fallback to
document.execCommand) and optionally confirm success (e.g., success toast) so
permission or API failures are not silently ignored; reference the
handleCopyScript function, the downloadScript variable, and
navigator.clipboard.writeText when making the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/src/components/SnapshotCalculator/index.tsx`:
- Around line 291-293: handleCopyScript currently calls
navigator.clipboard.writeText(downloadScript) without handling rejection; update
the handleCopyScript function to await or attach a .catch to
navigator.clipboard.writeText(downloadScript) and handle failures (e.g., show an
error toast/console.error or fallback to document.execCommand) and optionally
confirm success (e.g., success toast) so permission or API failures are not
silently ignored; reference the handleCopyScript function, the downloadScript
variable, and navigator.clipboard.writeText when making the change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d46ae138-98e0-4a21-a195-c0e4cb09df4f

📥 Commits

Reviewing files that changed from the base of the PR and between dc6461b and 688a5a8.

📒 Files selected for processing (4)

• docs/docs/users/guides/advanced/archival_snapshots.md
• docs/docs/users/guides/advanced/snapshot_calculator.mdx
• docs/src/components/SnapshotCalculator/SnapshotCalculator.module.css
• docs/src/components/SnapshotCalculator/index.tsx

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/src/components/SnapshotCalculator/SnapshotCalculator.module.css
• docs/docs/users/guides/advanced/archival_snapshots.md