infstarweb/.github/copilot-instructions.md

Project Guidelines

Code Style

• This repo is framework-free: plain HTML + CSS + vanilla JavaScript — no frameworks, modules, or build tooling.
• Keep existing naming style: camelCase for JS functions/variables and descriptive DOM ids/classes (for example fetchCrowdfunding, setupMobileMenu, #players-grid).
• Preserve current formatting patterns: 4-space indentation in HTML/CSS, simple function-based JS.
• Shared JS utilities use the global-object pattern (e.g. DataUtils in js/data_utils.js) — do not convert to ES modules.
• Reuse shared tokens in css/style.css (:root variables such as --bg-color, --accent-color) instead of introducing new ad-hoc styles.
• Keep page-local style overrides scoped to their page blocks; avoid broad visual refactors unless explicitly requested.
• Keep user-facing copy in Chinese unless the surrounding section is already English.

Architecture

• Public pages are static entry points:
  • index.html + js/script.js: landing page, sponsors, fundraising progress, live server status.
  • sponsor.html + js/sponsor_script.js: donation total, sponsor list, search/filter, donation modal.
  • stats.html + js/stats_script.js: player leaderboard + searchable player cards + modal details.
  • join.html + js/join_script.js: 4-step wizard (convention → agree → device → tutorial). Uses js/marked.min.js to render data/convention.md as HTML.
  • facilities.html + js/facilities_script.js: searchable/filterable catalog of server facilities from data/facilities.json. Supports Bilibili video embeds (BV IDs) in notes.
  • doc.html, map.html, photo.html: iframe wrappers (navbar + fullscreen iframe to external hosts). No page-specific JS beyond js/components.js.
• Shared utilities:
  • js/components.js: injected into #navbar-component / #footer-component, handles mobile menu & current-link highlighting.
  • js/data_utils.js: DataUtils.parseSponsorsText() and DataUtils.buildSponsorTotals() — used by both index.html and sponsor.html.
• Shared visual system lives in css/style.css; page-specific styles live in css/pages/ (join.css, facilities.css, sponsor.css, stats.css).
• Every page includes <script type="application/ld+json"> Schema.org metadata and full OG/Twitter Card meta tags.
• Data flow for stats:
  1. statsprocess.py fetches raw player JSON files and writes normalized outputs to stats/.
  2. It generates stats/summary.json consumed by stats_script.js via fetch('stats/summary.json').
  3. stats_script.js lazy-loads stats/{uuid}.json when opening player details.

Build and Test

• No package manager/build step exists in this workspace.
• Local static preview:
  • python3 -m http.server 8000
  • open http://localhost:8000/
• Regenerate player summary data:
  • python3 statsprocess.py (requires STATS_BASE_URL, STATS_USER, STATS_PASS env vars for remote authentication).
• Python script dependencies are runtime imports in statsprocess.py (not pinned): requests, tqdm.
• CI/CD: .github/workflows/deploy.yml runs statsprocess.py then deploys to GitHub Pages on push to main, daily cron, or manual dispatch. Secrets live in GitHub Actions — never commit credentials.

Data Contracts

• data/sponsors.txt: comma-separated fields (name, project, amount, [date]), parsed by DataUtils.parseSponsorsText().
• data/fund_progress.txt: line-parsed by frontend scripts.
• data/facilities.json: array of {title, intro, type, dimension, status, coordinates:{x,y,z}, contributors:[], instructions:[{type,content}], notes:[{type,content}]}. Notes with type:"video" use Bilibili BV IDs.
• data/convention.md: Markdown server rules, rendered via marked.js in join wizard.
• stats/summary.json and stats/{uuid}.json: generated by statsprocess.py — do not hand-edit.

Project Conventions

• Prefer progressive enhancement with DOMContentLoaded initializers (all page scripts and components.js).
• Keep network fetch paths relative for local assets.
• For unavailable remote APIs, follow existing behavior: log errors and render fallback text instead of throwing.
• Iframe wrapper pages (doc.html, map.html, photo.html) share an identical pattern: navbar + inline-styled fullscreen iframe. Follow this pattern for new external-embed pages.
• Do not introduce bundlers/framework migrations unless explicitly requested.

Integration Points

• External APIs/services:
  • Server status: https://api.mcstatus.io/v2/status/java/mcpure.lunadeer.cn
  • Avatars: https://minotar.net/... and https://crafatar.com/...
  • Player name resolution in pipeline: Ashcon + Mojang Session APIs (statsprocess.py).
  • Stats source endpoint: authenticated, URL in STATS_BASE_URL secret.
• External iframe hosts: schema.lunadeer.cn (docs), mcmap.lunadeer.cn (map), mcphoto.lunadeer.cn (photo).
• Navbar external links are centralized in js/components.js.
• External assets: Google Fonts, Font Awesome (CDN), Bilibili embeds (facilities notes).

Security

• Treat player UUID/name datasets in stats/ as production content; avoid destructive bulk edits.
• Preserve SEO/verification metadata in page <head> blocks unless a task explicitly targets SEO.
• Avoid adding secrets/tokens to repository files; keep any future credentials out of static HTML/JS.
• Frontend rendering uses innerHTML with fetched txt/json content in several views; keep those data sources trusted or sanitize before accepting untrusted input.