tera/scripts/brand-assets/films.mjs

/**
 * Film the engine running, by stepping its clock rather than by recording it.
 *
 *   node scripts/brand-assets/films.mjs                    # every film
 *   node scripts/brand-assets/films.mjs --only fidi-day
 *   node scripts/brand-assets/films.mjs --only fidi-day --frames 24   # a rough cut
 *   node scripts/brand-assets/films.mjs --keep-frames                 # keep the PNGs
 *   node scripts/brand-assets/films.mjs --manifest-only               # captions only
 *   node scripts/brand-assets/films.mjs --publish films/2026-08-06-abc1234
 *
 * `shots.mjs` next door takes the stills. This takes the moving pictures, and
 * the two share `harness.mjs` for the same reason they always did.
 *
 * ### Why this is not Remotion, or Motion Canvas, or HyperFrames
 *
 * All three of those compose an animation *out of code* — React components,
 * canvas nodes, HTML and GSAP — and they are good at it. None of them can help
 * here, because the animation already exists: it is a real-time 3D engine with
 * a sun computed from a clock, and what is missing is not a way to author
 * motion but a way to *record* motion that is already happening. That is a
 * frame-stepper and an encoder, which is this file and ffmpeg.
 *
 * The distinction is worth holding on to, because the day a title card or a
 * cross-fade between two of these films is wanted, one of those tools becomes
 * exactly right — as an editor, downstream of footage this produced. Reaching
 * for one now would mean reimplementing the city in React.
 *
 * ### Why the clock is stepped and not simply left running
 *
 * Real-time capture is not available on this box and would be the wrong idea
 * anyway. A sunset takes an hour, which is not a length of video anybody
 * watches, and the capture loop screenshots far slower than it renders. So the film is rendered offline the
 * way films always have been: set the clock, let the frame settle, expose,
 * advance. The output is smooth 30 fps regardless of what the renderer managed
 * while it was being photographed.
 *
 * Two shims in `filmClock()` make that possible from outside the app, without
 * a reload per frame — a reload costs fifteen seconds and would put a 180-frame
 * film at three quarters of an hour.
 */

import { fileURLToPath } from "node:url";
import { dirname, join, resolve } from "node:path";
import { mkdir, writeFile, rm, access, copyFile } from "node:fs/promises";
import { execFileSync } from "node:child_process";
import { serve, launch, FURNITURE, hide } from "./harness.mjs";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "..", "..");

// ---- The films --------------------------------------------------------------

const VIEWPORT = { width: 1440, height: 900 };
/** A hero is a band, not a window, so it is framed wider than the figures. */
const HERO_VIEWPORT = { width: 1600, height: 900 };
/** Delivered at 1280 wide. The frames are shot at 1440 and scaled once, by ffmpeg. */
const DELIVER_WIDTH = 1280;
const DELIVER_HEIGHT = Math.round((DELIVER_WIDTH * VIEWPORT.height) / VIEWPORT.width);
/**
 * What each film ships as.
 *
 * A figure is one file at 1280. The hero ships **two**, because it autoplays
 * above the fold and a phone at 390 CSS px has no use for a 1440-wide encode —
 * it is the same picture at two and a half times the bytes, on the connection
 * least able to spare them.
 *
 * The CRFs are measured, not guessed. A time-lapse is close to the worst case
 * for inter-frame compression: the camera never moves but every pixel changes
 * every frame as the light does, so the encoder has no static background to
 * lean on. At CRF 22 the hero came out at 2.5 MB; behind a scrim that is 38–96%
 * opaque, CRF 28 was indistinguishable and 987 kB.
 *
 * **The hero CRFs moved in August 2026, and the number that was held constant
 * was the size rather than the CRF.** The engine grew a specular sea with a
 * swell normal map and sun glitter, which is high-frequency detail that changes
 * every frame — the exact thing this encoder has no way to predict — so the same
 * CRF 28 that bought 987 kB before now buys 1.31 MB of the same six seconds.
 * The original decision was about a megabyte above the fold, not about the
 * number 28, so the number moved to keep the megabyte:
 *
 *   1440w  CRF 28 → 1.31 MB   CRF 30 → 1004 kB   CRF 31 → 892 kB
 *   960w   CRF 30 →  502 kB   CRF 32 →  393 kB
 *
 * 30 and 32 are the ones that land back on the sizes the earlier pass measured.
 * Checked rather than assumed: SSIM against a lossless re-encode of the master
 * is 0.962 at CRF 28 and 0.952 at CRF 30, and the two were compared as pixels at
 * 1:1 on frame 161 — the night frame, whose fine window-light speckle on dark
 * ground is where blocking would show first — and are not tellable apart. Under
 * the scrim there is nothing left to tell apart.
 *
 * The figures are untouched at CRF 22. They sit inline at 1280 with nothing over
 * them, they are looked at deliberately rather than glanced past, and they do not
 * download until they are on screen.
 */
const DELIVERABLES = {
  figure: [{ suffix: "", width: DELIVER_WIDTH, crf: 22 }],
  hero: [
    { suffix: "", width: 1440, crf: 30 },
    { suffix: "-sm", width: 960, crf: 32 },
  ],
};
const deliverablesFor = (spec) => (spec.chrome === "bare" ? DELIVERABLES.hero : DELIVERABLES.figure);
const deliverSize = (spec) => {
  const vp = spec.viewport ?? VIEWPORT;
  const w = deliverablesFor(spec)[0].width;
  return { w, h: Math.round((w * vp.height) / vp.width) };
};

/**
 * `door`, `chapter` and `expect` work exactly as they do in `shots.mjs`: which
 * building the engine is showing, an index into the chapter list, and the
 * `shortLabel` that index is asserted to be before the shutter opens.
 *
 * What is deliberately *not* carried over is `shots.mjs`'s `office` field and
 * the picker press behind it. Every film below is of the building its door opens
 * on, so that press would be a capture path no film exercises — and an untried
 * step in a pipeline is worse than an absent one, because it looks like coverage.
 * A Frontier Valley film means porting those fifteen lines along with it; the
 * office entry at the bottom says why the hangar is the second office film to
 * shoot rather than the first.
 *
 * `from` and `to` are the ends of the stretch of day the camera watches, and
 * every film crops to the part of it that moves. For the city films that means
 * dropping the small hours, which are dark frames indistinguishable from each
 * other; for `office-dusk` it means a window narrow enough that the lights
 * coming on lasts half a second instead of one frame. `hero-soma` is the
 * exception, and argues for itself on its own entry.
 *
 * ### Why there are two posters and only one reel
 *
 * The stills are shot twice, day and night, because a still is one instant and
 * the site serves the instant that matches the reader's theme. The obvious way
 * to carry that over here is a day reel and a night reel per film, and it is the
 * wrong answer twice over: it doubles the render, and it ships two crops of the
 * same day to a reader who is allowed to see only one of them — for a film whose
 * entire subject is that the light changes.
 *
 * Every reel below already spans both. `fidi-day` and `bay-relief-day` open at
 * 04:40 in the dark and close at 22:40 in the dark; `office-dusk` starts in
 * daylight and ends with the building lit from inside; `hero-soma` is a whole
 * day by construction. Nothing about the moving picture is wrong on a dark page.
 *
 * What *is* wrong on a dark page is the frame that sits there before anybody
 * presses anything. `Film` in `project-layout.tsx` ships `preload="none"`, so the
 * poster is what most readers see and the only thing a reduced-motion reader ever
 * sees — and `bay-relief-day`'s poster is ten to two in the afternoon, which on a
 * black page is a lit rectangle.
 *
 * So: **one reel, two posters, both cut from that same reel.** `poster` is the
 * daylight frame and `posterNight` the night one, each a fraction along the same
 * render. It costs no extra filming at all — a poster is one PNG pulled out
 * during encode — and it puts the figure at rest in the reader's own light, which
 * is the thing the stills pipeline gets right and this one did not.
 *
 * Choosing `posterNight` by arithmetic and hoping is how you find out the frame
 * was under a cloud. Shoot with `--keep-frames`, look at the PNGs, and move the
 * fraction; see the flag's own note.
 */
const FILMS = [
  {
    id: "fidi-day",
    door: "tera",
    city: "sf",
    chapter: 3,
    expect: "FiDi",
    from: "2026-08-06T04:40:00-07:00",
    to: "2026-08-06T22:40:00-07:00",
    frames: 180,
    fps: 30,
    title: "Eighteen hours over the Financial District",
    /**
     * Which frame becomes the poster — the one worth stopping on, twice.
     *
     * 0.935 is half past nine, the hour the shot list uses for night, with the
     * sun twelve degrees under and the tower windows carrying the frame.
     *
     * `poster` used to be 0.86 and the comment beside it said "a few minutes
     * before sunset: the last of the low sun down the length of Montgomery".
     * That reading was true of the renderer it was chosen on and is not true of
     * this one. 0.86 is 20:09 with the sun at **+0.4°** — on the ACES pipeline
     * and the world-space sky dome the towers at that instant are unlit
     * silhouettes, and the frame measures a mean luminance of 33 out of 255
     * against the night poster's 21. A *day* poster is what a light-mode reader
     * is served, and it is what most readers of this film see for most of the
     * time it is on their screen, because `preload="none"` means the poster is
     * usually the whole film. A pair that is 33 and 21 is not a pair.
     *
     * 0.76 is twenty past six, sun about twenty degrees up: the towers are lit,
     * they are throwing down the length of the grid, the Bay Bridge is in the
     * frame, and it measures 86. Checked by extracting the candidates from the
     * CRF-18 master rather than by arithmetic, which is the same discipline the
     * night poster already had.
     */
    poster: 0.76,
    posterNight: 0.935,
    place: "Financial District, San Francisco",
    caption:
      "One camera, eighteen hours, six seconds. Nothing here is keyframed: every frame is the engine asked for a different instant, and the light, the shadows, the sky, the map in the corner and the window lights all follow from that one number. The readout at the top of the panel is the film captioning itself — the hour, how high the sun is, which band of twilight that puts it in, and how much of the moon is lit.",
    alt: "A time-lapse of the San Francisco financial district seen from above. Shadow sweeps across the towers as the sun crosses the sky, the water changes colour, and after sunset the tower windows light up one by one.",
  },
  {
    /**
     * The hero on lumbridgecorp.com, and the only film shot `bare`.
     *
     * The figures keep the app's panel because the clock in it is the caption.
     * A hero has its own headline sitting on top of the picture, and a second
     * column of interface underneath that headline is not atmosphere, it is
     * two interfaces arguing.
     *
     * The camera is SoMa rather than the whole board. **The original reason for
     * that is dead and the conclusion survived it**, which is worth writing down
     * so the question is not reopened a third time on the old evidence.
     *
     * Whole board was rejected in August 2026 because at that standoff the edge
     * of the terrain plate showed against the sky across the top of the frame.
     * That seam no longer exists: the sea now runs eighteen board spans and ends
     * past the fog far plane, and the sky is a world-space dome rather than a
     * screen-space gradient. So the camera was shot again — `--frames 24`,
     * midnight to midnight, against `Whole Board`, `The Bay` and `Marin` — and
     * all three lost, for reasons that have nothing to do with the old one:
     *
     * - **Whole Board** is now a weather picture, not a city one. The camera sits
     *   above the cloud deck and `atmosphere.ts` models the marine layer from its
     *   own diurnal curve, so most of the day is white. It is also, precisely,
     *   `bay-relief-day`'s camera — a hero that duplicates a figure two screens
     *   further down is a wasted first impression.
     * - **The Bay** (chapter 11, three crossings ahead and two behind) is the
     *   handsomest of the four and still wrong for a hero: the sea is specular
     *   now, so the sun's glitter path lands as a blown white bloom across the
     *   middle third of the frame for most of the afternoon — which is exactly
     *   where the headline goes, and exactly what `npm run check:hero` measures.
     *   Both bridges are hairlines at 280 units of standoff. Keep it in mind as a
     *   *figure*, where nothing sits on top of it.
     * - **Marin** is outside the pack's single `focusRegions` rectangle, so the
     *   terrain there is on the 450 m coarse lattice: a flat green blob for
     *   Tamalpais and a staircase for the coast.
     *
     * Close in, SoMa still fills the frame to every edge at every hour, and it
     * gained the subject it used to lack — the Bay Bridge is a real suspension
     * bridge in the right third of the frame now, with towers and cables, and
     * the sea under it reflects.
     *
     * It is also the only one that runs **midnight to midnight**. The others
     * crop to the part of the day that moves; this one cannot, because the page
     * seeks it to the reader's own local hour and a film that starts at 04:40
     * has no frame to show someone at two in the morning. 180 frames across 24
     * hours is exactly eight minutes a frame, and the last frame lands at 23:52
     * rather than midnight so the loop closes without showing the same minute
     * twice.
     */
    id: "hero-soma",
    door: "tera",
    city: "sf",
    chapter: 2,
    expect: "SoMa",
    from: "2026-08-06T00:00:00-07:00",
    to: "2026-08-06T23:52:00-07:00",
    frames: 180,
    fps: 30,
    viewport: HERO_VIEWPORT,
    chrome: "bare",
    /**
     * Whole-day, so this is the only film where the poster hours are a free
     * choice rather than a crop of one. 0.33 is ten to eight in the morning —
     * the relief hour — and 0.90 is half past nine at night.
     */
    poster: 0.33,
    posterNight: 0.901,
    title: "San Francisco, one whole day",
    place: "SoMa, San Francisco",
    caption:
      "A full day of San Francisco every six seconds, starting at whatever hour it is where you are. The sun, the moon and the window lights are computed from a clock rather than themed — the one claim this engine makes that a picture can settle on its own.",
    alt: "A time-lapse of downtown San Francisco from above, running through a whole day: dark before dawn, long shadows at sunrise, flat midday light over the tower cluster and the Bay Bridge, then dusk and the windows lighting up one by one.",
  },
  {
    id: "bay-relief-day",
    door: "tera",
    city: "sf",
    chapter: 0,
    expect: "Whole Board",
    from: "2026-08-06T04:40:00-07:00",
    to: "2026-08-06T22:40:00-07:00",
    frames: 180,
    fps: 30,
    /**
     * The region shot, which is now the weather film as much as the light one.
     *
     * This is the only one of the three city cameras that is *above* the cloud
     * deck — `clouds.ts` sizes its own hard case off exactly this chapter, "the
     * camera 430 units above the ground with the cloud base at 52" — so it is
     * the only one that watches the marine layer from on top rather than from
     * under it. And with no weather feed wired, which is what a capture against
     * a local `dist/` always is, there is a marine layer to watch: `atmosphere.ts`
     * models the cover from the layer's own diurnal curve on apparent solar time
     * rather than defaulting to an empty sky. Over San Francisco on this date the
     * model runs about 0.88 before dawn, thins to 0.27 by mid-afternoon, and is
     * back over 0.8 by nine.
     *
     * **Do not judge this one from a rough cut**, and the reason is a trap worth
     * writing down. Cover is eased toward its target over a six-second time
     * constant in *real* time (`COVER_TAU` in `clouds.ts`), while a frame costs
     * about half a second of real time no matter how many hours of sky it steps
     * over — measured here at 0.51 s, by differencing an 8-frame run against a
     * 28-frame one. So the deck always runs *behind* the day, and how far behind
     * is decided by the frame count rather than by the weather. At `--frames 40`
     * one frame is twenty-eight minutes of sky, the layer never gets near its
     * target, and the board reads as permanently socked in — which it is not.
     * At 180 frames a frame is six minutes and the lag through the steepest part
     * of the burn-off works out around a fifth of cover: trailing, but the deck
     * visibly opens and shuts. The frame count is part of what this picture *is*,
     * not just how smooth it is.
     *
     * The poster moved off 0.20 for a related reason: 0.20 is twenty past eight
     * in the morning, which is now a white rectangle. 0.51 is ten to two, the
     * clearest the board gets.
     *
     * The night poster is the one place on this film where the cloud model has
     * to be argued with rather than admired, and it is the reason
     * `--keep-frames` exists at all.
     *
     * The arithmetic answer was 0.894 — a quarter to nine, after sunset and
     * before the layer was expected to close. Looking at the kept PNGs said
     * otherwise: by 20:44 the deck is already back over the board and the frame
     * is a featureless purple wash, which is the old 0.20 failure with the
     * colours inverted. Frames 148 through 172 were compared as pictures, and
     * **every post-sunset frame on this camera is under cloud** — that is not a
     * bad hour to have picked, it is what this film is about, and the caption
     * already says the deck closes in again after sunset.
     *
     * So the night poster is chosen for what survives the cloud rather than for
     * a clear sky that is not on offer. 0.96 is 21:57, sun 18.6° under: dark
     * enough to belong on a black page, and late enough that the built ground
     * reads through the gaps as speckled clusters — San Jose, the East Bay, the
     * peninsula — which is the last line of the caption arriving as a picture.
     * Five aircraft and their tracks are in it too.
     *
     * If the cloud model is ever retuned, re-shoot with `--keep-frames` and look
     * again rather than trusting this number.
     */
    title: "A day across the whole board",
    poster: 0.51,
    posterNight: 0.96,
    place: "San Francisco Bay Area",
    caption:
      "Relief is easiest to read when the light moves, and this camera is high enough to read the weather the same way. With nobody to ask for an observation — which is what a fresh clone of this engine has, and what this camera had — the sky is modelled from the Pacific marine layer's own daily curve instead of left empty: the deck that covers the board before dawn burns back through the afternoon and closes in again after sunset. Under it, shadow runs the length of two mountain ranges and back — and at the end the thing the terrain never told you comes through the gaps, which is the cities, which are somewhere else entirely.",
    alt: "A time-lapse of the whole San Francisco Bay Area from above, seen from over a cloud deck. The cloud covers the board at dawn, thins through the middle of the day to let long shadows rake across the hills and the bay show through, then closes back in at dusk, after which the built-up ground reads as scattered clusters of light between the dark ranges.",
  },
  {
    /**
     * The one film the stills cannot stand in for.
     *
     * **This entry was rewritten from scratch in August 2026, because the
     * building it described was demolished.** It used to be forty-eight metres
     * by eighteen, two storeys with fourteen metres of interstitial between
     * them, four Optimus units walking two floor plates — and the camera was
     * `chapter: 0`, `expect: "The Floor"`. `The Floor` does not exist any more.
     * Chapter 0 is `Front Door` now, and the `expect` guard is what stopped this
     * script rather than letting it photograph an arrival pose and caption it
     * with an open-plan office that is gone. That is the entire reason the guard
     * is there; do not weaken it.
     *
     * What stands at `lumbridge-hq` today is a twelve by nine metre live/work
     * studio on one level: a two-place agent bench, a demo lounge with a real
     * sofa facing a shared wall, a kitchen island with stools, a sleeping alcove
     * and a bath. The id is unchanged on purpose — journey snapshots, presence,
     * media grants and self-hosted deployments all address it — so the film id
     * stays `office-dusk` too, and nothing on the site has to be renamed.
     *
     * `office-floor` in `shots.mjs` is this exact camera at two hours — 11:20
     * and 21:30 — and that pair is a fair account of both of them. What a pair
     * cannot show is the part in between, which is the part that is actually the
     * claim: the building has no night theme, it has a sun going down, and the
     * fittings come up as it does. An event with a duration wants the medium
     * that has one.
     *
     * **The window is cut to the switch-over, not to the working day.**
     * `luminaires.ts` ramps the house lights from nothing at six degrees of
     * solar elevation to full at zero, and over this building's own coordinate
     * — Transbay, 37.79N, which the rebuild did not move — on this date that
     * band is 19:38 to 20:12: thirty-four minutes. Spread across the eighteen-
     * hour window the city films use it would be six frames and a blink. Across
     * these six hours it is seventeen, a little over half a second, with another
     * thirty-nine frames of twilight behind it in which the fittings hold the
     * room on their own. Dawn does the same thing in reverse and is deliberately
     * out of frame: one legible switch-over beats two unreadable ones.
     *
     * The other end is chosen too. Solar noon here is 13:15 with the sun at 69°,
     * which is straight down into an open-topped model and flat on every surface
     * — the interior version of the midday problem the shot list keeps away
     * from. By half past three the sun is at 54° and falling, and the shadows on
     * the floor have somewhere to go for the whole reel.
     *
     * The last frame is 21:30, which is `office-floor`'s night frame exactly. So
     * the film ends on the still, and anyone who suspects one of them is lying
     * can put them side by side.
     *
     * `chapter: 1` — `The Whole Studio` — is the only camera that holds all
     * twelve metres and every zone at once, which is what makes this read as a
     * *building* changing state rather than as one lamp coming on. The Front
     * Door is the arrival pose and needs no click, which is why it was tempting;
     * it is also framed at 11.8 units on the threshold and cuts the kitchen off.
     *
     * Lumbridge HQ rather than Frontier Valley or the LA courtyard, and the
     * hangar is still the better second film than first — reaching either needs
     * the office-picker press this script does not have. See the note above
     * `FILMS`.
     */
    id: "office-dusk",
    door: "office",
    chapter: 1,
    expect: "Studio",
    from: "2026-08-06T15:30:00-07:00",
    to: "2026-08-06T21:30:00-07:00",
    frames: 180,
    fps: 30,
    /**
     * Both picked off the kept PNGs rather than off the clock, and one of them
     * moved because of it.
     *
     * 0.25 — five past five, sun at 34° — was the arithmetic answer and it is
     * the flat one: the light is nearly down the camera's own axis, the walls
     * are one value and the floor has no shadow on it. That is the midday
     * problem in miniature, which is the thing the 15:30 start was chosen to
     * avoid, arriving anyway because the poster was chosen separately from the
     * window. 0.53 is twenty to seven with the sun at 13°, warm and raking the
     * length of the floor, and the panel still reads `day` beside it.
     *
     * 0.90 is five to nine: sun 12° under, the sky behind the glass gone deep
     * blue, and the room lit entirely by its own fittings. It is the same claim
     * as the title, at rest.
     */
    poster: 0.53,
    posterNight: 0.9,
    title: "Six hours in the studio, and the lights taking over",
    place: "SF HQ · Studio, Transbay",
    caption:
      "Twelve metres by nine, one level, and a sun that belongs to the building rather than to the picture: the pack declares where on the earth it stands, so this floor is lit by the real afternoon over Transbay and switches to its own fittings as that afternoon ends. The changeover is a ramp across six degrees of solar elevation rather than a theme, which is why it takes a film to show it at all. The panel beside it is reading the same clock, and the studio hardware under it says in as many words that its levels are simulated.",
    alt: "A time-lapse of a small live/work studio seen from outside as an open-topped model: a two-place desk with monitors and task chairs, a glass-walled lounge with a sofa, a kitchen island, a bookshelf and a bed in an alcove, all on one floor. Afternoon daylight rakes across the floor and the sky behind the building warms to orange and then goes deep blue; the ceiling fittings come up as it does, until the room is lit entirely from within. Two humanoid robots move about the floor and a dog crosses it.",
  },
];

// ---- Arguments --------------------------------------------------------------

function flag(name, fallback = null) {
  const i = process.argv.indexOf(`--${name}`);
  return i > -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith("--")
    ? process.argv[i + 1]
    : fallback;
}

const only = flag("only")?.split(",").map((s) => s.trim());
/**
 * Override the frame count for a rough cut.
 *
 * Filming costs about half a second a frame at 1440x900 on the GPU, so a
 * 180-frame film is a minute and a half; on the software fallback it is seven
 * seconds a frame and twenty-two minutes. `--frames 24` is the cheapest
 * possible way to discover that a camera is pointed at the wrong thing. A rough cut also skips the site, because a 24-frame stutter is not
 * something to publish by accident.
 */
const frameOverride = flag("frames") ? Number(flag("frames")) : null;
/**
 * Leave the PNG frames on disk instead of deleting them after the encode.
 *
 * This exists because of one specific, expensive asymmetry. Everything about a
 * film can be changed after the fact for the price of an ffmpeg run — the CRF,
 * the delivered width, the caption, which files ship — because the master is a
 * near-lossless archive and the deliverables come off it. **The poster fractions
 * could not**, because the poster is cut from the PNGs and the PNGs were gone
 * the moment `encode()` returned. Moving a poster cost a re-shoot.
 *
 * That was survivable with one poster and a fraction picked off a rough cut. It
 * stopped being survivable with two, because a night poster cannot be chosen by
 * arithmetic: `bay-relief-day` at half past nine is under a closed marine layer
 * and looks like nothing, and you cannot know that from the clock. So: shoot
 * once with `--keep-frames`, look at the candidate frames, and if a fraction is
 * wrong, change it and re-run that one film.
 *
 * The frames are not small — measured on this pass, 180 PNGs of the FiDi camera
 * at 1440x900 came to 122 MB, and the hero at 1600x900 rather more — which is
 * why this is a flag and not the default. They live in `films/.frames/<id>/`,
 * and the next run of the same film deletes them whether or not it was asked to
 * keep its own, so a full set never accumulates twice.
 */
const keepFrames = process.argv.includes("--keep-frames");
const outRoot = resolve(flag("out", join(ROOT, "films")));
const siteDir = resolve(flag("site", join(ROOT, "..", "lumbridge-v4")));
/** Rewrite the site's manifest from the film list without filming anything. */
const manifestOnly = process.argv.includes("--manifest-only");
/**
 * Publish an existing render directory to the site instead of shooting a new one.
 *
 * There has to be a way to put reels that already exist in front of the site
 * without re-shooting them — otherwise the answer to "how did those files get
 * there" becomes `cp`, and a hand-copied artefact is exactly the thing this
 * pipeline exists to not have.
 */
const publishFrom = flag("publish");
const wanted = only ? FILMS.filter((f) => only.includes(f.id)) : FILMS;

if (only) {
  const unknown = only.filter((id) => !FILMS.some((f) => f.id === id));
  if (unknown.length) {
    console.error(`unknown film(s): ${unknown.join(", ")}`);
    process.exit(1);
  }
}

const git = (...args) => execFileSync("git", args, { cwd: ROOT, encoding: "utf8" }).trim();
const commit = git("rev-parse", "--short", "HEAD");
const dirty = git("status", "--porcelain").length > 0;
const today = new Date().toISOString().slice(0, 10);

// ---- The two shims ----------------------------------------------------------

/**
 * A clock the harness can move, and an app that notices when it does.
 *
 * **The skew is a live global, not a constant.** `shots.mjs` bakes one instant
 * into the page at load, which is right for a still and useless here: 180
 * stills would be 180 page loads. Reading `__teraSkew` on every call means the
 * whole page can be walked through a day without reloading.
 *
 * **`setInterval(…, 60_000)` is compressed to 120 ms.** This is the load-bearing
 * half. `main.ts` recomputes the sun on a once-a-minute wall-clock tick — which
 * is exactly right for a map somebody is looking at, and means a shifted clock
 * would otherwise sit unrendered for up to a minute per frame. Only the 60-second
 * interval is touched, by value, so nothing else in the app has its timing
 * changed underneath it.
 *
 * Both are capture-harness lies told to the page, and neither is shipped: the
 * deployed bundle has no idea this file exists.
 */
function filmClock() {
  return `{
  globalThis.__teraSkew = 0;
  const Real = Date;
  globalThis.Date = class extends Real {
    constructor(...a) { super(...(a.length ? a : [Real.now() + globalThis.__teraSkew])); }
    static now() { return Real.now() + globalThis.__teraSkew; }
  };
  const realSetInterval = globalThis.setInterval.bind(globalThis);
  globalThis.setInterval = (fn, ms, ...rest) =>
    realSetInterval(fn, ms === 60000 ? 120 : ms, ...rest);
}`;
}

/** Put the page's clock at `instant`, and wait until the frame showing it has been painted. */
async function expose(page, instant) {
  await page.evaluate((t) => {
    globalThis.__teraSkew = t - performance.timeOrigin - performance.now();
  }, instant);
  // Long enough for the compressed interval to fire and recompute the sun...
  await page.waitForTimeout(260);
  // ...and then two straddled frames, so what is on screen is what we just asked
  // for rather than the one before it. A `waitForTimeout` alone cannot promise
  // that when the renderer is slower than the loop asking for frames.
  await page.evaluate(
    () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))),
  );
}

// ---- Filming ----------------------------------------------------------------

async function film(browser, spec, dir) {
  const host = spec.door === "office" ? "office.lumbridgecorp.com" : "tera.lumbridgecorp.com";
  const query = spec.city ? `?city=${spec.city}` : "";
  const frames = frameOverride ?? spec.frames;
  const page = await browser.newPage({
    viewport: spec.viewport ?? VIEWPORT,
    deviceScaleFactor: 1,
    // As in `shots.mjs`: the chapter cut has to be a cut, not a twenty-second
    // flight the film would open in the middle of.
    reducedMotion: "reduce",
  });
  const problems = [];
  page.on("pageerror", (e) => problems.push(String(e)));

  try {
    await page.addInitScript(filmClock());
    await page.goto(`http://${host}:5210/${query}`, { waitUntil: "networkidle" });
    await page.waitForFunction(
      () =>
        document.getElementById("boot")?.hidden === true &&
        document.querySelectorAll("#chapters .chapter").length > 0,
      undefined,
      { timeout: 180_000 },
    );
    await page.waitForTimeout(4000);

    const label = await page.evaluate(
      ({ i, press }) => {
        const button = [...document.querySelectorAll("#chapters .chapter")][i];
        if (!button) return null;
        if (press) button.click();
        return button.textContent.replace(/^\d+/, "").trim();
      },
      { i: spec.chapter, press: spec.chapter > 0 },
    );
    if (label !== spec.expect) {
      throw new Error(`chapter ${spec.chapter} is "${label}", not "${spec.expect}"`);
    }
    await page.waitForTimeout(2500);

    // For a figure the clock stays: it is the caption the film writes for
    // itself, and the only thing on screen proving the light follows a real
    // time rather than a hand-keyed fade. A `bare` film is going behind
    // somebody else's headline and takes all of it off.
    //
    // Both lists come from `harness.mjs` rather than being extended here, and
    // that is worth one line of defence because this pass nearly did extend
    // them. `#mode-dock` — the View / Drive / Explore / Fly / Walk pill along
    // the bottom of the canvas — arrived after those lists were written, and it
    // was sitting in the bottom centre of the first hero rough cut of this pass:
    // a picture that is meant to carry nothing but a headline, with a control
    // pill in it, rendering perfectly and looking entirely deliberate. That is
    // the hazard `FURNITURE`'s own comment names, and the answer to it is the
    // one shared list, not a private patch in each script that photographs the
    // app. It is in `FURNITURE.BARE` now, along with `#play-hud`.
    //
    // It is *not* in `CLUTTER`, so the figures keep it, and that is deliberate
    // rather than an omission: the figures keep the panel because the dock and
    // the panel are both true and readable instruments — the dock says this
    // board can be driven, flown and walked, which is a claim the page makes in
    // words a couple of paragraphs away. `CLUTTER` drops what is untrue outside
    // the capture or unreadable inside it, and the dock is neither.
    await hide(page, [
      ...FURNITURE.transient,
      ...(spec.chrome === "bare" ? FURNITURE.BARE : FURNITURE.CLUTTER),
    ]);

    const start = new Date(spec.from).getTime();
    const end = new Date(spec.to).getTime();
    const step = (end - start) / (frames - 1);

    for (let i = 0; i < frames; i++) {
      await expose(page, start + step * i);
      await page.screenshot({
        path: join(dir, `f-${String(i).padStart(4, "0")}.png`),
        timeout: 120_000,
        animations: "disabled",
      });
      if (i % 20 === 0 || i === frames - 1) {
        process.stdout.write(`\r   frame ${i + 1}/${frames}   `);
      }
    }
    process.stdout.write("\n");
    if (problems.length) throw new Error(`the page threw while filming: ${problems[0]}`);
    return frames;
  } finally {
    await page.close();
  }
}

/**
 * Frames to a master, the master to deliverables, and a poster off the frames.
 *
 * Two stages rather than one, deliberately. The master is a near-lossless
 * archive encode that stays in the render directory; every shipped file is
 * derived from it. That makes "the hero is too heavy, try CRF 28" a ten-second
 * job instead of a re-shoot, and — the part that matters —
 * it means what is on the site is always exactly what this script produces,
 * rather than something hand-rolled with ffmpeg the day the size became a
 * problem.
 *
 * `yuv420p` and `+faststart` are not decoration: without the first, Safari and
 * a good deal of Android will not decode the file at all, and without the
 * second the index sits at the end and playback waits for the whole download.
 *
 * The posters come off the PNGs, not off the master, because they are stills and
 * have no reason to inherit a video codec's compromises. There are two of them —
 * a daylight frame and a night one, cut from the same reel, so that the figure at
 * rest is in the reader's own light; the note above `FILMS` argues for that over
 * a second reel.
 *
 * The price of cutting them from the PNGs used to be that the frames were deleted
 * the moment this returned, so **moving a poster fraction cost a re-shoot** where
 * moving a CRF costs ten seconds. `--keep-frames` is the answer to that; see its
 * note. Everything else about a film can still be changed for free.
 */
function encode(dir, out, fps, frames, posters, deliverables) {
  const ff = (...args) => execFileSync("ffmpeg", ["-y", "-loglevel", "error", ...args]);
  const master = `${out}-master.mp4`;
  ff(
    "-framerate", String(fps),
    "-i", join(dir, "f-%04d.png"),
    "-c:v", "libx264",
    "-preset", "slow",
    "-crf", "18",
    "-pix_fmt", "yuv420p",
    master,
  );
  for (const d of deliverables) {
    ff(
      "-i", master,
      "-vf", `scale=${d.width}:-2:flags=lanczos`,
      "-c:v", "libx264",
      "-preset", "slow",
      "-crf", String(d.crf),
      "-pix_fmt", "yuv420p",
      "-movflags", "+faststart",
      `${out}${d.suffix}.mp4`,
    );
  }
  const cut = (at, suffix) => {
    const frame = Math.min(frames - 1, Math.max(0, Math.round((frames - 1) * at)));
    ff(
      "-i", join(dir, `f-${String(frame).padStart(4, "0")}.png`),
      "-vf", `scale=${deliverables[0].width}:-2:flags=lanczos`,
      "-quality", "82",
      `${out}${suffix}.webp`,
    );
    return frame;
  };
  return {
    day: cut(posters.day, "-poster"),
    night: cut(posters.night, "-poster-night"),
  };
}

/**
 * Every file a film ships, in one place.
 *
 * `publish()` and the end-of-run copy both walk this, so a new deliverable —
 * the night poster was one — cannot be added to the encoder and forgotten in
 * the copy, which would leave the manifest naming a `<img>` that 404s while
 * every other check passed.
 */
const shippedNames = (spec) => [
  ...deliverablesFor(spec).map((d) => `${spec.id}${d.suffix}.mp4`),
  `${spec.id}-poster.webp`,
  `${spec.id}-poster-night.webp`,
];

// ---- Run --------------------------------------------------------------------

const exists = (p) => access(p).then(() => true, () => false);
const publicDir = join(siteDir, "apps", "web", "public", "films");
const dataDir = join(siteDir, "apps", "web", "src", "data");
const haveSite = () => exists(join(siteDir, "apps", "web"));

async function writeManifest() {
  await mkdir(dataDir, { recursive: true });
  await writeFile(join(dataDir, "films.ts"), manifest());
  return join(dataDir, "films.ts");
}

/**
 * Copy a render directory to the site, then rewrite the manifest.
 *
 * A film that is not in `fromDir` but is already published is **left alone**
 * rather than treated as an error. A one-reel render is the normal way to add
 * or replace one, and demanding that
 * every reel be present in the same directory would mean re-shooting the whole
 * set to change any of it. What is not tolerated is a film that exists in
 * neither place: the manifest is about to name it, so that is a hard failure
 * rather than a broken `<video>` discovered later.
 */
async function publish(fromDir) {
  await mkdir(publicDir, { recursive: true });
  let copied = 0;
  const kept = [];
  /**
   * Every file, not just the first one.
   *
   * This used to test `names[0]` — the main mp4 — and take its presence as proof
   * the whole set was there. That was true for exactly as long as the set never
   * changed. The moment the night poster was added, an older render directory or
   * an already-published film from before the change satisfied `names[0]`
   * perfectly and was waved through **missing a file the manifest was about to
   * name**, which is a 404 behind an `<img>` that nothing else in this pipeline
   * would have caught. A render that predates a deliverable has to be re-shot,
   * and the way to find that out is here rather than in a browser.
   */
  const complete = async (dir, names) => {
    for (const name of names) if (!(await exists(join(dir, name)))) return false;
    return true;
  };
  for (const spec of FILMS) {
    const names = shippedNames(spec);
    if (await complete(fromDir, names)) {
      for (const name of names) await copyFile(join(fromDir, name), join(publicDir, name));
      copied += 1;
      continue;
    }
    if (await complete(publicDir, names)) {
      kept.push(spec.id);
      continue;
    }
    const partial = (await exists(join(fromDir, names[0]))) || (await exists(join(publicDir, names[0])));
    throw new Error(
      partial
        ? `${spec.id} is present but incomplete — it is missing at least one of ` +
          `${names.join(", ")}, so it predates a deliverable this script now ships. Re-film it.`
        : `${spec.id} is neither in ${fromDir} nor already published — film it before the ` +
          `manifest names it`,
    );
  }
  console.log(`site    ${copied} film(s) copied → ${publicDir}`);
  if (kept.length) console.log(`        kept already-published: ${kept.join(", ")}`);
  console.log(`        manifest → ${await writeManifest()}`);
}

if (manifestOnly || publishFrom) {
  if (!(await haveSite())) {
    console.log(`site    skipped — no checkout at ${siteDir}`);
  } else if (publishFrom) {
    await publish(resolve(publishFrom));
  } else {
    console.log(`manifest → ${await writeManifest()} (nothing re-filmed)`);
  }
  process.exit(0);
}

const app = await serve(join(ROOT, "dist"), 5210, { spa: true });
const browser = await launch();

try {
  const outDir = join(outRoot, `${today}-${commit}${dirty ? "-dirty" : ""}`);
  await mkdir(outDir, { recursive: true });
  const made = [];

  for (const spec of wanted) {
    console.log(`film    ${spec.id} — ${spec.title}`);
    const framesDir = join(outRoot, ".frames", spec.id);
    await rm(framesDir, { recursive: true, force: true });
    await mkdir(framesDir, { recursive: true });

    const shot = await film(browser, spec, framesDir);
    const out = join(outDir, spec.id);
    const posterFrames = encode(
      framesDir,
      out,
      spec.fps,
      shot,
      { day: spec.poster, night: spec.posterNight },
      deliverablesFor(spec),
    );
    if (!keepFrames) await rm(framesDir, { recursive: true, force: true });
    made.push({ spec, out });

    const seconds = (shot / spec.fps).toFixed(1);
    console.log(`        ${shot} frames → ${seconds}s at ${spec.fps}fps`);
    console.log(`        posters from frames ${posterFrames.day} (day) and ${posterFrames.night} (night)`);
    console.log(`        ${out}.mp4`);
    if (keepFrames) console.log(`        frames kept → ${framesDir}`);
  }

  await writeFile(
    join(outDir, "README.txt"),
    `Rendered from tera ${commit}${dirty ? " (working tree had uncommitted changes)" : ""} on ${today}.\n` +
      `Every frame is the running dist/ with its own clock stepped; nothing is keyframed.\n` +
      `Regenerate: node scripts/brand-assets/films.mjs\n`,
  );
  console.log(`\nout     ${outDir}`);

  if (!(await haveSite())) {
    console.log(`site    skipped — no checkout at ${siteDir} (pass --site <dir>)`);
  } else if (frameOverride) {
    // A rough cut is for looking at, not for publishing.
    console.log(`site    skipped — this was a ${frameOverride}-frame rough cut`);
  } else {
    await mkdir(publicDir, { recursive: true });
    for (const { spec } of made) {
      for (const name of shippedNames(spec)) {
        await copyFile(join(outDir, name), join(publicDir, name));
      }
    }
    console.log(`site    ${made.length} film(s) → ${publicDir}`);
    // As in `shots.mjs`: a partial run must not rewrite a manifest that would
    // then name films this run did not make.
    if (only) {
      console.log("        manifest left alone (partial run; re-run without --only)");
    } else {
      console.log(`        manifest → ${await writeManifest()}`);
    }
  }
} finally {
  await browser.close();
  app.close();
}

// ---- The generated manifest -------------------------------------------------

function manifest() {
  const entries = FILMS.map(
    (f) => `  {
    id: ${JSON.stringify(f.id)},
    place: ${JSON.stringify(f.place)},
    title: ${JSON.stringify(f.title)},
    src: ${JSON.stringify(`/films/${f.id}.mp4`)},${
      deliverablesFor(f).some((d) => d.suffix === "-sm")
        ? `\n    srcSmall: ${JSON.stringify(`/films/${f.id}-sm.mp4`)},`
        : ""
    }
    poster: ${JSON.stringify(`/films/${f.id}-poster.webp`)},
    posterNight: ${JSON.stringify(`/films/${f.id}-poster-night.webp`)},
    width: ${deliverSize(f).w},
    height: ${deliverSize(f).h},
    seconds: ${Number((f.frames / f.fps).toFixed(2))},
    from: ${JSON.stringify(f.from)},
    to: ${JSON.stringify(f.to)},
    caption: ${JSON.stringify(f.caption)},
    alt: ${JSON.stringify(f.alt)},
  },`,
  ).join("\n");

  return `/**
 * Generated. Do not edit — \`scripts/brand-assets/films.mjs\` in the tera repo
 * rewrites this file wholesale.
 *
 * To change a film or its caption: edit \`FILMS\` in that script and run it.
 * A caption-only change can use \`--manifest-only\` and skip the shoot entirely —
 * which is a minute and a half a film on the GPU and twenty-two without one.
 *
 * Every frame of every film below is a screenshot of tera's built \`dist/\` at
 * the commit named here, with the app's own clock stepped between frames.
 * Nothing is keyframed and nothing is an illustration.
 */

/** A union rather than \`string\`, so a page naming a film that is gone fails typecheck. */
export type FilmId =
${FILMS.map((f) => `  | ${JSON.stringify(f.id)}`).join("\n")};

export interface Film {
  id: FilmId;
  /** Where this is, in words a reader would use. */
  place: string;
  /** One line, for the figure's heading. */
  title: string;
  src: string;
  /** A narrower encode for small screens, where one exists. Same film, fewer bytes. */
  srcSmall?: string;
  /**
   * The daylight poster, and the night one cut from the same reel.
   *
   * Pick by the reader's resolved theme, the way \`shots.ts\` consumers already
   * do — \`useResolvedTheme()\` in \`apps/web/src/theme.ts\`, never a
   * \`prefers-color-scheme\` media query, which sees the OS and is blind to the
   * site's own toggle.
   *
   * This matters more than a poster usually would. \`Film\` ships
   * \`preload="none"\`, so the poster is what most readers see before they press
   * anything, and it is the *only* thing a reduced-motion reader ever sees. The
   * reel itself is single-variant on purpose: every film here spans the whole
   * change of light, so the moving picture is right on either page.
   */
  poster: string;
  posterNight: string;
  width: number;
  height: number;
  /** Running time. Used to decide whether a pause control is required; it is. */
  seconds: number;
  /** The ends of the day the camera watched, ISO. */
  from: string;
  to: string;
  caption: string;
  /** Describes what happens, not just what is shown — it stands in for the film. */
  alt: string;
}

/** The tera commit these were filmed from. */
export const FILMS_COMMIT = ${JSON.stringify(commit)};
/** True if that commit is not the whole story — the tree had uncommitted work. */
export const FILMS_DIRTY = ${dirty};
/** The day the camera rolled, ISO. */
export const FILMS_CAPTURED = ${JSON.stringify(today)};

export const FILMS: Film[] = [
${entries}
];

/** Total, because \`FilmId\` cannot name a film that is not in \`FILMS\`. */
export const filmById = (id: FilmId): Film => FILMS.find((f) => f.id === id)!;
`;
}