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 --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. SwiftShader draws about three frames a second with no GPU, so a
 * screen recording would be a slideshow; and a sunset takes an hour, which is
 * not a length of video anybody watches. 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 --------------------------------------------------------------

/**
 * `chapter` and `expect` work exactly as they do in `shots.mjs` — an index into
 * the chapter list, and the `shortLabel` it is asserted to be.
 *
 * `from` and `to` are the ends of the day the camera watches. They are not
 * midnight to midnight: the hours either side of dawn and dusk are the whole
 * point and the small hours are eighteen identical dark frames, so the window
 * is cropped to the part that moves.
 */
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. */
    poster: 0.86,
    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 and the window lights all follow from that one number. The clock in the corner is the film captioning itself.",
    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.",
  },
  {
    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 is the one where the day does the most work. Shadow
    // sweeps the length of two mountain ranges, and then the thing the relief
    // was hiding turns up: the cities, which are somewhere else entirely.
    title: "A day across the whole board",
    poster: 0.2,
    place: "San Francisco Bay Area",
    caption:
      "Relief is easiest to read when the light moves. Shadow runs the length of two mountain ranges and back, and then at the end the thing the terrain never told you appears on its own: the cities, which are somewhere else entirely.",
    alt: "A time-lapse of the whole San Francisco Bay Area from above. Long shadows rake across the hills as the sun crosses, and after dark the built-up ground emerges as scattered clusters of light between the ranges.",
  },
];

const VIEWPORT = { width: 1440, 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);

// ---- 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 seven seconds a frame at 1440x900 on this box, so a
 * 180-frame film is some twenty-two minutes. `--frames 24` is three, and it 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;
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.
 *
 * Filming is twenty-two minutes a reel, so there has to be a way to put reels
 * that already exist in front of the site without paying that again — 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 at three frames a second.
  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: 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,
      { 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);

    // The clock stays. It is the caption the film writes for itself, and the
    // only thing on screen that proves the light is following a real time
    // rather than a hand-keyed fade.
    await hide(page, [...FURNITURE.transient, ...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 an MP4, plus the poster a `<video>` shows before anybody presses
 * play.
 *
 * `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 the video will not begin until the whole
 * thing has arrived.
 */
function encode(dir, out, fps, frames, posterAt) {
  const ff = (...args) => execFileSync("ffmpeg", ["-y", "-loglevel", "error", ...args]);
  ff(
    "-framerate", String(fps),
    "-i", join(dir, "f-%04d.png"),
    "-vf", `scale=${DELIVER_WIDTH}:-2:flags=lanczos`,
    "-c:v", "libx264",
    "-preset", "slow",
    "-crf", "22",
    "-pix_fmt", "yuv420p",
    "-movflags", "+faststart",
    `${out}.mp4`,
  );
  const posterFrame = Math.min(frames - 1, Math.round((frames - 1) * posterAt));
  ff(
    "-i", join(dir, `f-${String(posterFrame).padStart(4, "0")}.png`),
    "-vf", `scale=${DELIVER_WIDTH}:-2:flags=lanczos`,
    "-quality", "82",
    `${out}-poster.webp`,
  );
  return posterFrame;
}

// ---- 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");
}

async function publish(fromDir) {
  await mkdir(publicDir, { recursive: true });
  for (const spec of FILMS) {
    for (const name of [`${spec.id}.mp4`, `${spec.id}-poster.webp`]) {
      const src = join(fromDir, name);
      if (!(await exists(src))) throw new Error(`${src} is not there — film it first`);
      await copyFile(src, join(publicDir, name));
    }
  }
  console.log(`site    ${FILMS.length} film(s) → ${publicDir}`);
  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 posterFrame = encode(framesDir, out, spec.fps, shot, spec.poster);
    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, poster from frame ${posterFrame}`);
    console.log(`        ${out}.mp4`);
  }

  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, out } of made) {
      await copyFile(`${out}.mp4`, join(publicDir, `${spec.id}.mp4`));
      await copyFile(`${out}-poster.webp`, join(publicDir, `${spec.id}-poster.webp`));
    }
    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`)},
    poster: ${JSON.stringify(`/films/${f.id}-poster.webp`)},
    width: ${DELIVER_WIDTH},
    height: ${DELIVER_HEIGHT},
    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 ~22 minutes a
 * film costs to shoot.
 *
 * 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;
  poster: 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)!;
`;
}