z-sci-viz-lab

z-sci-viz-lab: Visual Science Communication

Positioning

Turn any mathematical/scientific concept into a "single-page interactive experiment accessible on both computers and phones".

Do not start with a string of definitions and formulas; instead, let readers first build intuition through rotating, dragging, and adjusting parameters, then move on to formal definitions, boundaries of conclusions, and authoritative sources. As long as the problem involves spatial relationships, temporal changes, scale changes, or parameter effects, interactive experiments have room to shine.

Core workflow (8 steps)

1. Fact verification: First consult authoritative sources (official pages, original papers, reliable reviews) before starting; fabricating theorems, numbers, citations, and conclusions is prohibited
2. Intuitive model: Convert abstract concepts into operable visuals (3D models, 2D canvases), first building the intuition of "what exactly is this problem asking"
3. Formal definition: After intuition, give precise definitions and distinctions between key concepts (e.g., Lebesgue measure / Hausdorff dimension / Minkowski dimension)
4. Interactive experiment design: Parameter sliders + real-time feedback; drag to rotate, scroll to zoom, reset the view, pause animation; immediately update the model and status text when parameters change
5. Boundary explanation: Make clear that the page demonstration is only for building intuition and cannot serve as a mathematical proof; clearly state which problems are solved and which remain open
6. Source tracing: All important conclusions can be traced back to official materials, original papers, or reliable reviews, with source links listed at the end of the page
7. Vite single-file build：npm run build, packaged into a single dist/index.html
8. Cloudflare Pages deployment：npm run deploy, yielding an online address directly accessible on both computers and phones

For the detailed methodology, see references/workflow.md。

Two ways to use

Method A: Brand-new topic, generate a complete single page

Use templates/prompt-template.txt(the complete Kakeya conjecture prompt), replace the following five places, and hand it to AI to generate a complete single-page project:

• Topic objects: e.g., for a solar eclipse, the Sun, Moon, Earth, light rays, umbra, penumbra
• Core variables: e.g., orbital inclination, time, relative position, magnitude of eclipse
• Motion rules: e.g., orbital motion, shadow cone changes, period
• Timeline: key historical milestones for the topic
• Authoritative materials: official pages, original papers, reliable reviews

The requirements in the template for fact verification, intuitive model, interactive experiment, boundary explanation, responsive checks, and source tracing must be retained as-is.

Method B: Extend an existing sci-viz-lab project

Add a new scene to an existing sci-viz-lab project:

1. Copy templates/scene-template.js to src/scenes/<scene-id>.js
2. Implement the scene interface { id, name, init(container), update(params), dispose(), getDefaultParams() }
3. In src/main.js , registerScene(myScene) register
4. In index.html 's .scene-tabs Add the corresponding Tab in (data-scene matches the scene id )
5. npm run dev Verify locally, then build and release

Scenes are scene-loader.js lazy-loaded: only on activation init, and on switching away dispose, with only one render loop globally.

Instance: sci-viz-lab

• Repository:https://github.com/tjxj/sci-viz-lab
• Online:https://sci-viz-lab.pages.dev
• 10 scenes: Kakeya conjecture, solar eclipse, lunar eclipse, solar system, four seasons, moon phases, tides, satellite orbits, plate motion, refraction of light

The first scene "Kakeya conjecture" includes: a rotatable and zoomable 3D thin-tube experiment (four arrangements), a 2D line-segment overlap and δ-neighborhood canvas, a five-station proof-idea map, a timeline, and traceable sources.

Tech Stack and Deployment

• Tech stack: Vite + Three.js (3D) + HTML Canvas (2D) + vite-plugin-singlefile
• Architecture：src/scenes/ scene plugin architecture,registry.js registry + scene-loader.js switching and render loop
• Visuals: editorial science-handbook style (warm off-white background, deep navy experimental area, red accents, monospace parameter labels)

npm install       # 安装依赖（Node.js >= 20）
npm run dev       # 本地开发
npm run build     # 构建，产出单文件 dist/index.html
npm run deploy    # 发布到 Cloudflare Pages（需先登录 Wrangler）

Completion Criteria

• The page has no horizontal scrolling at desktop and mobile resolutions, controls are keyboard accessible, and prefers-reduced-motion is respected
• All sliders, buttons, dragging, zooming, and reset are verified usable, with no errors in the browser console
• Boundary notes and source links are complete, with no fabricated content
• dist/index.html The single file can be opened directly, and the online address is accessible