Films/project-memory.md

ColdFilm project memory

Project summary

• Project name: ColdFilm
• Type: static browser-only frontend, no build step, no backend.
• Goal: monitor new ColdFilm releases, show posters, and let user open torrent/magnet links from browser.
• Intended use: local network only; not public-facing.
• Requirement: VPN enabled for accessing coldfilm.ink from Russia.

File structure

• index.html — page shell with header, status area, refresh button, film list container, quality modal.
• style.css — dark theme, responsive card layout, modal styling, buttons, status colors.
• script.js — main app logic.
• README.md — project description and operational notes.
• project-memory.md — persistent project architecture and change log.

Core architecture

Frontend-only architecture

• HTML renders skeleton and DOM containers.
• CSS supplies layout and visual design.
• JavaScript performs all runtime behavior.

Runtime data flow

1. On page load, loadFilms() runs immediately.
2. fetchWithProxy() retrieves the main ColdFilm page HTML using a list of public CORS proxies.
3. parseColdfilm(html) extracts release titles and page URLs, and tries to pair them with posters.
4. Results are rendered into the DOM as list items with poster, title, and a “Download” button.
5. When user presses “Download”, showQualityModal(filmName) loads the film's detail page, extracts .torrent and magnet links, and shows quality buttons in a modal.
6. downloadTorrent(url) opens the chosen torrent/magnet link in a new browser tab.

State and cache

• currentFilmName stores the currently selected film title.
• availableTorrents stores extracted torrent options for the modal.
• filmData is a Map cache keyed by film title, storing { url, poster }.

Parsing strategy

• Parsing is based on regex matching against HTML.
• Release links are detected via href="/news/..." patterns and titles from class="kino-h" and title="... [Смотреть Онлайн]".
• Posters are extracted using <img> src, alt, or title attributes.
• The parser filters out Telegram-related entries.

Quality detection logic

• Torrent links are classified by filename substring:
  • 720p / hd720 → 720p
  • 1080p / hd1080 → 1080p
  • 4k / 2160p → 4K
  • otherwise → Стандарт
• Magnet links are labeled Magnet.
• Quality buttons are sorted by priority: 4K, 1080p, 720p, Стандарт, Magnet.

Reliability constraints

• Uses third-party public CORS proxies; if proxies fail, the app cannot fetch content reliably.
• Parser is fragile because it depends heavily on the remote site's HTML structure.
• Browser fetches are subject to CORS, proxy availability, and remote host changes.

Auto-refresh behavior

• loadFilms() is called on page load.
• setInterval(loadFilms, 15 * 60 * 1000) refreshes the list every 15 minutes.

UI behavior

• Status panel displays loading, success, error, and downloading states.
• The refresh button triggers loadFilms() manually.
• Modal allows quality choice before opening torrent.

Known implementation notes

• fetchWithProxy() loops through PROXIES and returns the first successful response.
• The PROXIES list includes public proxies; it should be reviewed and cleaned periodically.
• The code is intentionally simple and dependency-free to keep deployment easy.

Current project principles

• Minimal dependencies.
• No backend/server-side logic.
• Direct browser execution only.
• Keep it easy to host on static web server / Synology Web Station.

Recent implementation update

• Removed the broken proxy entry with an invalid host string.
• Reworked proxy fetching to use an AbortController timeout instead of the unsupported fetch({ timeout }) option.
• Added normalizePosterUrl() to centralize poster URL normalization.
• Broadened torrent-link regex to support query strings in .torrent URLs.
• Verified JavaScript syntax with node --check script.js and confirmed exit code 0.

Best practice for future edits

• Preserve the current static browser-only architecture.
• If changing parser logic, keep it regex-based and resilient to HTML variations.
• Prefer small, local changes over large rewrites.
• Record any new dependency, proxy change, or URL structure change here.