Teaching Animation with HyperFrames — filled-in example: CO₂ liquefaction

PART A — HOW TO WORK (keep as is)

A1. Environment (do this first and report what you found)
* Check Node.js (HyperFrames needs version 22 or later), FFmpeg and FFprobe.
* Install the framework locally, pinned: npm init -y, then npm install -D hyperframes@0.8.208
* Run `npx hyperframes doctor`. If it reports no Chrome, run `npx hyperframes browser` (see its --help).
* 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` and node_modules/hyperframes/README.md.
* 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
* Every number that appears on screen is computed in one file (for example js/physics.js) from the source named in B4, or read from a data file generated from that source. Never type a physical number by hand into the HTML.
* Everything that moves 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, so that seeking to any frame paints 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, not in an external .js file.
  - System fonts need one @font-face with local() per weight, otherwise bold text silently renders regular.
  - When the same element gets several tweens, set immediateRender: false on them.

A3. Scientific honesty
* Use the data source named in B4. If you need a value it does not give, say so and ask; do not estimate silently.
* Label anything that is a picture rather than a measurement or a calculation (for example "Illustrative molecules"). If you adjust or simplify anything to make it look right, disclose it on screen in one short line and in SCIENCE_QA.md, with its size.
* Do not explain a result by one mechanism unless you have checked it. If the cause is not established, say so.
* Never change a random seed or a parameter only to make a number look better.

A4. Verification you must build and run
* tools/check.mjs, a content gate that exits 1 on any failure. It recomputes or re-reads every on-screen number from an independent source (a second calculation, or the reference tables in B4 saved to disk), runs the real drawing code against a stub DOM and reads the displayed values back at regular times. It also checks the on-screen language, units and signs, and every item of B6.
* tools/mutation_test.mjs, which copies the project, breaks one thing per copy and requires the gate to fail every time. Break at least one thing per item of B6. A gate that passes broken code is not a gate.
* `npx hyperframes check` with 0 errors.
* Render: npx hyperframes render --quality delivery --fps 30 -o renders/[file name].mp4
* Verify the MP4 itself: ffprobe (codec, resolution, frame rate, duration, frame count), a full decode with `ffmpeg -v error -i <file> -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 teacher should know about. Do not report completion before the MP4 exists and has passed the checks above.

PART B — YOUR VIDEO (filled in for this example)

B1. Basics
* Title: "Can Pressure Alone Turn a Gas into a Liquid?" Subtitle: "Compressing CO₂ at two temperatures"
* Course and level: university physical chemistry or general chemistry (real gases, critical point)
* On-screen language: English; narration: none
* Duration: about 90 seconds; 1920 × 1080, 16:9, 30 fps, MP4
* Must be understandable without narration: yes

B2. Learning goal
A gas can be liquefied by compression only below its critical temperature; for CO₂ that is 31 °C.

B3. Misconceptions to address
* "Any gas turns into a liquid if you squeeze it hard enough."
* "A very dense fluid must be a liquid."
* "Pressure keeps rising the whole time you compress a gas."

B4. Scientific setup and data source
* System: two vertical cylinders with frictionless pistons, each holding 1 mol of CO₂. Cylinder A sits in a 20 °C water bath, cylinder B in a 40 °C water bath; the baths keep the temperatures constant. Both start at the same molar volume, 500 cm³ mol⁻¹, and are compressed slowly to 55 cm³ mol⁻¹.
* Model: real CO₂, not an ideal gas.
* Source of every number: the Span-Wagner reference equation of state for CO₂, evaluated with CoolProp (the same equation the NIST Chemistry WebBook uses). Save NIST WebBook tables (saturation, and the 20 °C and 40 °C isotherms) to disk and check the data against them. Critical temperatures of the other gases in scene 6 from the same source.
* Units: p in bar, molar volume in cm³ mol⁻¹, temperatures in °C on screen.
* Molecules are illustrative dots, not a simulation; label them. Their counts must still follow the physics: in A, the number of dots in the liquid follows the lever rule, so the dot density of liquid and vapor differ by the real density ratio.

B5. Storyboard
* Scene 1, 0-10 s, The Question: the title, then the two cylinders with "20 °C bath" and "40 °C bath", "1 mol CO₂", a pressure gauge on each, and the line "Same amount of CO₂, same starting volume; each bath holds its temperature constant".
* Scene 2, 10-30 s, Squeeze Both: both pistons move down together. A pressure-volume diagram beside them traces both isotherms live. A: the pressure rises, droplets appear ("Droplets appear at 57.3 bar"), the pressure then stays flat while the liquid grows ("Pressure stays constant while the vapor condenses"), and once all of it is liquid the pressure climbs steeply while the piston hardly moves ("All liquid: hard to compress"). B: the pressure rises smoothly, no droplets ever ("No droplets: one fluid all the way"); at the end it is nearly as dense as the liquid but has no surface.
* Scene 3, 30-36 s, Pause and Predict: motion stops; "Same CO₂, same squeeze. Why did only the 20 °C sample turn into a liquid?"
* Scene 4, 36-60 s, The Critical Point: more isotherms appear on the diagram (10, 20, 25, 31 and 40 °C) with the liquid-vapor coexistence region shaded. Text in sequence: "Below 31 °C every isotherm has a flat step: liquid and vapor coexist." "The step shrinks as the temperature rises and vanishes at the critical point." "Above T_c = 31.0 °C no pressure can split CO₂ into a liquid and a vapor." Mark the critical point (31.0 °C, 73.8 bar).
* Scene 5, 60-75 s, Attraction versus Motion: both pistons move back up a little; in A part of the liquid evaporates again at the same constant pressure, leaving liquid and vapor with a visible surface; B stays one uniform fluid. Text: "A liquid forms when attractions can hold molecules together against their thermal motion." "Above T_c the molecules move too fast: squeezing makes CO₂ denser, but it never separates."
* Scene 6, 75-90 s, Takeaway: a table of critical temperatures with an everyday example for each (propane, CO₂, methane, nitrogen) and whether pressure alone liquefies it at 20 °C. Large text: "Pressure liquefies a gas only below its critical temperature." Closing line: "AI-Assisted Physical Chemistry Education".

B6. Scientific accuracy requirements
* All displayed pressures, volumes and temperatures agree with the reference data, and the data agree with the saved NIST tables.
* A: while liquid and vapor coexist the pressure equals the vapor pressure at 20 °C (57.3 bar) and does not change; droplets appear exactly when the volume reaches the saturated-vapor volume.
* A: the liquid fraction follows the lever rule; no liquid before saturation, no vapor after the saturated-liquid volume.
* B: no liquid surface at any time. Crossing the critical pressure above T_c is not a phase transition; if the label changes from "gas" to "supercritical fluid", say that it is only a name.
* The temperature of each cylinder never changes on screen.
* The critical point shown is 31.0 °C and 73.8 bar, and only the isotherms below it have a flat step.
* The molecules are labelled illustrative.

B7. Visual design
* Light background, navy text, blue for A (20 °C), warm orange for B (40 °C).
* The liquid in A must be clearly visible as a separate layer with a surface; B must never look layered.
* The pressure-volume diagram is large enough to read from the back of a lecture hall.

B8. Deliverables and acceptance
* The MP4, the full HyperFrames source project, STORYBOARD.md, SCIENCE_QA.md (every number with its source and every simplification), at least four key-frame screenshots taken from the MP4, render commands and verification results.
* The video plays from start to end without errors, all on-screen text is in English, and the science is consistent with B4 and B6.
* Make reasonable creative decisions yourself. Produce the finished video, not a proposal.