HyperFrames Animation Production — HF-PCHEM-001 (Codex edition)

You are working in an empty project folder. Part A tells you how to work; Part B is the specification. Follow both. Part A comes from producing and reviewing this same video once; it lists the traps we actually hit, so treat it as requirements, not suggestions.

PART A — HOW TO WORK

A1. Environment (do this first, then report what you found)
* Check Node.js (HyperFrames needs version 22 or later), FFmpeg and FFprobe.
* Install the framework locally and pin the version that produced the reference video:
  npm init -y
  npm install -D hyperframes@0.8.208
* Run `npx hyperframes doctor`. If it reports no Chrome, run `npx hyperframes browser` (see its --help) to install the headless browser used for rendering.
* Set DO_NOT_TRACK=1 for every hyperframes command.
* Learn the framework from its own documentation before writing code: `npx hyperframes --help`, `npx hyperframes docs` (topics: compositions, gsap, rendering, troubleshooting, data-attributes, examples) and node_modules/hyperframes/README.md. Scaffolding with `npx hyperframes init --non-interactive` is allowed.
* If a command needs network access or a permission you do not have, ask me. If a required tool is missing, stop and tell me. Do not switch to another video tool or skip the render.

A2. Architecture
* One file (for example js/physics.js) computes every physical number that appears on screen. The markup holds placeholders that are filled from it. Never type a physical number by hand into the HTML.
* Everything that moves or depends on the physics is drawn by one pure function render(t) of the root-timeline time t, called from the onUpdate of a single GSAP tween that spans the whole film. Seeking to any frame must paint that frame.
* Determinism: seeded random generator only. No Math.random, Date, performance.now, timers, requestAnimationFrame or network calls in any script.
* HyperFrames 0.8.208 traps:
  - Register the root timeline (window.__timelines[...] = tl) in an inline <script> inside index.html. In an external .js file the linter does not see it and the check fails.
  - System fonts need one @font-face with local() per weight (for example 'Segoe UI Bold' for 700, 'Segoe UI Black' for 800-900), otherwise bold text silently renders regular.
  - When the same element gets several tweens, set immediateRender: false on them.

A3. The molecular picture must be honest
* A 2D gas of discs is not a monatomic gas: it has gamma = 2 and cools far below the 3D value, so forcing it onto the 3D curve secretly pumps energy in. Use 3D hard spheres in a thin slab seen from above (slab depth = 2 sphere diameters, the screen shows x and y), so collisions share energy among x, y and z.
* The free-expansion gas (B) gets no correction of any kind; its kinetic energy must be conserved by the dynamics alone.
* If you scale A's velocities so that the dots follow the ideal-gas temperature, keep the factor small, record both the net correction and the sum of all its ups and downs as fractions of the initial kinetic energy, and disclose it on screen in one short English line, as well as in SCIENCE_QA.md. A small factor per frame can still add up to a large intervention.
* Collisions depend on the 3D separation. Do not claim that discs which overlap on screen have collided.
* A fixed time step leaves a small residual overlap between spheres. Measure it in every recorded frame and bound it in a test.
* Do not attribute a deviation from the ideal-gas result to one mechanism (for example excluded volume) unless controls separate it from the others: time step, piston speed, number of molecules, initial state. If you have not done that, say that the cause is not established.
* Never change a random seed to make a number look better. Report what the chosen seed gives and how much other seeds vary.
* Label the speed distribution as theory ("Maxwell-Boltzmann (theory)") unless it is a histogram of the simulated molecules.

A4. Verification you must build and run
* tools/check.mjs, a content gate that exits 1 on any failure. It recomputes every on-screen number from constants written out again in the check itself (not imported from the physics file), runs the real drawing code against a stub DOM, and reads the displayed values back every 0.5 s. It also checks: English only, no hand-typed numbers in the markup, the sign rows (A: q = 0, w < 0, dU < 0; B: q = 0, w = 0, dU = 0), B's energy conservation, equipartition (in-plane share of the kinetic energy near 2/3), molecules inside the walls, the residual sphere overlap, and that the on-screen disclosure is present.
* tools/mutation_test.mjs, which copies the project, breaks one thing per copy and requires the gate to fail every time. Include at least: mean kinetic energy doubled, live work fixed at zero, A's distribution drawn at the start temperature, the correction applied to B too, collisions that ignore depth, molecules leaking through the piston, the disclosure removed. A gate that passes broken code is not a gate.
* `npx hyperframes check` (lint, runtime, layout, contrast) with 0 errors.
* Render: npx hyperframes render --quality delivery --fps 30 -o renders/adiabatic_expansion_EN.mp4
* Verify the MP4 itself: ffprobe (codec, 1920x1080, 30 fps, duration, frame count), a full decode with `ffmpeg -v error -i renders/adiabatic_expansion_EN.mp4 -f null -` (no errors), and key frames extracted from the MP4, not from the browser preview, into screenshots/.
* Look at the key frames. If your tools cannot show you images, say so in the report instead of claiming a visual check.

A5. Report
* What you verified and how (commands and results), what you could not verify, and every simplification a chemist should know about. Do not report completion before the MP4 exists and has passed the checks above.

PART B — SPECIFICATION (unchanged from the original brief)

Project Title
Why Does a Gas Cool Down Without Losing Heat?
Subtitle: Reversible Adiabatic Expansion vs. Free Expansion
1. Objective
Create a polished, 90-second, fully English educational animation using HyperFrames.
The animation will be presented to university administrators as a demonstration of AI-assisted physical chemistry education.
The goal is to visually connect:

* Microscopic molecular motion
* Macroscopic temperature and work
* The First Law of Thermodynamics

Language requirement: All visible text must be in English. This includes titles, labels, explanations, subtitles, equations, and closing messages. Do not include any Chinese text.
The video must be understandable without narration. If narration is added, it must also be in English.
2. Technical Specifications

* Framework: HyperFrames
* Duration: Approximately 90 seconds
* Resolution: 1920 × 1080
* Aspect ratio: 16:9
* Frame rate: 30 fps
* Format: MP4
* Style: Modern scientific visualization
* Background: Light, clean, professional
* Typography: Large, highly readable English text
* Animation: Smooth, deterministic, scientifically meaningful

Use HTML, CSS, SVG, Canvas, GSAP, or other technologies supported by the installed HyperFrames workflow.
3. Scientific Setup
Show two ideal-gas systems with identical initial conditions.
System A — Reversible Adiabatic Expansion
A thermally insulated cylinder contains an ideal gas. A frictionless piston moves outward quasi-statically as the gas performs work.

* q = 0
* w < 0
* ΔU = w < 0
* Temperature decreases

System B — Adiabatic Free Expansion
An ideal gas initially occupies half of an insulated rigid container. The other half is vacuum. The partition is removed.

* q = 0
* w = 0
* ΔU = 0
* Temperature remains unchanged

Assume a closed system, ideal-gas behavior, and no additional forms of energy transfer.
For comparison, both systems can begin at 300 K and expand to twice their initial volume. For System A, choose a constant heat-capacity ratio if numerical final temperatures are displayed. Otherwise, use a qualitative temperature decrease.
Do not invent numerical temperatures without calculating them consistently.
4. Detailed Storyboard
Scene 1 — 0–12 s: The Question
Large opening title:
"Why Does a Gas Cool Down Without Losing Heat?"
Display two insulated containers side by side.
Left label:
"Reversible Adiabatic Expansion"
Right label:
"Free Expansion into Vacuum"
Both initially show:
"T = 300 K"
"q = 0"
Scene 2 — 12–30 s: Two Different Expansions
Left side:

* The piston moves outward slowly.
* Gas molecules collide with the piston and cylinder walls.
* An arrow indicates work done by the gas.
* The temperature indicator gradually decreases.
* The molecular speed distribution shifts toward lower speeds.

Overlay:
"Gas performs work on its surroundings."
Right side:

* The partition is removed.
* Gas molecules spread into the vacuum.
* The average molecular kinetic energy remains constant.
* Temperature remains at 300 K.

Overlay:
"No work is done against external pressure."
The two simulations must run simultaneously.
Scene 3 — 30–50 s: Predict and Reveal
Pause the animation briefly.
Display:
"Both processes are adiabatic. Why are their temperature changes different?"
Then reveal:
Left:
"Temperature decreases"
Right:
"Temperature remains constant"
Use a clear visual contrast between the two outcomes.
Scene 4 — 50–70 s: The First Law
Display the central equation:
ΔU = q + w
Then animate q = 0 for both processes.
Left:
"Work done by the gas"
"w < 0"
"ΔU < 0"
Right:
"Expansion against vacuum"
"w = 0"
"ΔU = 0"
Include an internal-energy indicator that decreases on the left but remains unchanged on the right.
The energy visualization must be synchronized with the molecular animation.
Scene 5 — 70–83 s: Microscopic Explanation
Display:
"Internal energy and temperature are linked."
For an ideal gas with constant heat capacity:
ΔU = nCᵥΔT
Then display the mean translational kinetic energy relation:
⟨Eₖ⟩ = 3/2 kᴮT
Use molecular motion to show that lower temperature corresponds to lower average molecular translational kinetic energy.
Avoid suggesting that every individual molecule slows down by the same amount.
Scene 6 — 83–90 s: Final Takeaway
Show a clean side-by-side comparison.
Reversible Adiabatic Expansion
q = 0
w < 0
ΔT < 0
Ideal-Gas Free Expansion
q = 0
w = 0
ΔT = 0
Conclude with large text:
"Adiabatic Does Not Mean Isothermal."
Closing line:
AI-Assisted Physical Chemistry Education
5. Visual Design
Use a premium educational animation style rather than a conventional slide presentation.
Visual priorities:

1. Molecular particles move smoothly and meaningfully.
2. The piston and removable partition are unmistakably different.
3. The two systems remain visually synchronized.
4. Energy, temperature, and work are represented visually.
5. Equations appear when they become relevant.
6. Text is readable on classroom projectors.
7. The animation emphasizes understanding rather than decorative effects.

Suggested palette: white, light blue, navy, cyan, and warm orange.
6. Scientific Accuracy Requirements
Verify that:

* The sign convention ΔU = q + w is consistent throughout.
* Reversible adiabatic expansion is distinguished from irreversible free expansion.
* Free expansion is not shown as a continuous equilibrium path on a P–V diagram.
* The constant-temperature conclusion for free expansion is explicitly associated with an ideal gas.
* Molecular kinetic energy and temperature are represented statistically.
* No heat transfer is depicted in either system.
* Any displayed numerical temperatures are physically consistent.

7. Implementation and Deliverables
First inspect the installed HyperFrames environment and official workflow documentation.
Then implement and render the complete animation.
Deliver:

* `adiabatic_expansion_EN.mp4`
* Full HyperFrames source project
* `STORYBOARD_EN.md`
* `SCIENCE_QA.md`
* At least four screenshots of key frames
* Render commands and verification results

Render the actual MP4 and inspect key frames before reporting completion.
Do not stop after creating a storyboard, code draft, or browser preview.
8. Acceptance Criteria
The project is complete when:

* The video plays from beginning to end without errors.
* All visible text is in English.
* Both gas systems are visually compared.
* Molecular behavior and thermodynamic equations are consistent.
* The video communicates the scientific explanation without requiring narration.
* The final MP4 is ready for presentation to university administrators.

Make reasonable creative decisions independently. Prioritize scientific accuracy, instructional clarity, and visual polish.
Final instruction: Produce the finished video, not merely a proposal.