Write the frontend as TypeScript LitElements

.github/workflows/browser-tests.yml

@@ -34,10 +34,10 @@ jobs:
       - name: Restore Cargo cache
         uses: Swatinem/rust-cache@v2
 
-      - name: Install Node.js 22
+      - name: Install Node.js 24
         uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
           cache-dependency-path: frontend/package-lock.json
 

.github/workflows/documentation-contracts.yml

@@ -19,10 +19,10 @@ jobs:
           ref: ${{ github.sha }}
           persist-credentials: false
 
-      - name: Install Node.js 22
+      - name: Install Node.js 24
         uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: 24
 
       - name: Test documentation contracts
         run: node --test docs/tests/*.test.mjs

.github/workflows/frontend-tests.yml

@@ -19,17 +19,25 @@ jobs:
           ref: ${{ github.sha }}
           persist-credentials: false
 
-      - name: Install Node.js 22
+      - name: Install Node.js 24
         uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: 24
           cache: npm
           cache-dependency-path: frontend/package-lock.json
 
       - name: Install dependencies
         run: npm ci
         working-directory: frontend
 
+      - name: Check frontend types
+        run: npm run typecheck
+        working-directory: frontend
+
+      - name: Lint frontend TypeScript
+        run: npm run lint
+        working-directory: frontend
+
       - name: Test frontend units
         run: npm run test:unit
         working-directory: frontend

.github/workflows/macos-packaging-contracts.yml

@@ -19,10 +19,10 @@ jobs:
           ref: ${{ github.sha }}
           persist-credentials: false
 
-      - name: Install Node.js 22
+      - name: Install Node.js 24
         uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: 24
 
       # These verify shell scripts, workflow definitions, and documentation, so
       # they need no macOS host. The Swift programs and the packaging-metadata

.github/workflows/macos-release.yml

@@ -78,12 +78,18 @@ jobs:
           # Packaging requires a clean main worktree on this runner.
           git checkout -B main "${REQUESTED_SHA}"
 
-      - name: Install Node.js 22
+      - name: Install Node.js 24
         uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: 24
           package-manager-cache: false
 
+      # The server embeds Lit and tslib from frontend/node_modules and
+      # compiles its TypeScript modules with the TypeScript installed there.
+      - name: Install frontend build dependencies
+        run: npm ci --omit=dev
+        working-directory: frontend
+
       - name: Bump the release version locally
         if: startsWith(inputs.action, 'release-')
         id: bump

.github/workflows/repository-tooling-tests.yml

@@ -19,10 +19,10 @@ jobs:
           ref: ${{ github.sha }}
           persist-credentials: false
 
-      - name: Install Node.js 22
+      - name: Install Node.js 24
         uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: 24
 
       - name: Test repository tooling
         run: node --test scripts/tests/*.test.mjs

.github/workflows/rust-checks.yml

@@ -30,6 +30,19 @@ jobs:
       - name: Restore Cargo cache
         uses: Swatinem/rust-cache@v2
 
+      - name: Install Node.js 24
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      # The server embeds Lit and tslib from frontend/node_modules and
+      # compiles its TypeScript modules with the TypeScript installed there.
+      - name: Install frontend build dependencies
+        run: npm ci --omit=dev
+        working-directory: frontend
+
       - name: Check formatting
         run: cargo fmt --check
 

.gitignore

@@ -1,5 +1,6 @@
 /target
 /frontend/node_modules
+/frontend/tests/unit-build
 /playwright-report
 /test-results
 /frontend/tests/e2e/*-snapshots

CONTRIBUTING.md

@@ -9,7 +9,7 @@ the changed boundary, and record what was and was not verified.
 The supported contributor baseline is:
 
 - the Rust toolchain pinned by `rust-toolchain.toml`;
-- Node.js 22 and npm;
+- Node.js 24 or newer and npm;
 - Git;
 - CMake and the Xcode Command Line Tools on macOS;
 - the authenticated standalone Codex CLI for Codex live work;
@@ -29,6 +29,9 @@ xcode-select --install
 
 The npm package lives in `frontend/`, so JavaScript and browser commands run
 from that directory while Rust commands stay at the repository root. The
+server embeds Lit from `frontend/node_modules` and runs Node.js to build the
+frontend's TypeScript modules, so run `npm ci` there before the first Cargo
+build in a checkout or worktree, and keep Node.js on `PATH` while building. The
 ordinary browser suite also needs Playwright's Chromium build:
 
 ```sh

caffold/Cargo.toml

@@ -58,6 +58,9 @@ whisper-rs = { version = "0.16.0", features = ["tracing_backend"] }
 [target.'cfg(target_os = "macos")'.dependencies]
 whisper-rs = { version = "0.16.0", features = ["metal"] }
 
+[build-dependencies]
+serde_json = "1.0.140"
+
 [dev-dependencies]
 tempfile = "3.20.0"
 tokio = { version = "1.45.1", features = ["test-util"] }

caffold/build.rs

@@ -1,7 +1,8 @@
+use serde_json::Value;
 use std::{
     env, fs,
-    path::PathBuf,
-    process::Command,
+    path::{Path, PathBuf},
+    process::{Command, Stdio},
     time::{SystemTime, UNIX_EPOCH},
 };
 
@@ -10,6 +11,23 @@ fn main() {
     println!("cargo:rerun-if-changed=src");
     println!("cargo:rerun-if-changed=Cargo.toml");
 
+    let out_dir = PathBuf::from(env::var_os("OUT_DIR").expect("Cargo OUT_DIR must be set"));
+
+    for package in ["lit", "tslib", "typescript"] {
+        if let Err(problem) = check_installed_package(package) {
+            println!("cargo::error={problem}; run `npm ci` in frontend/ before building");
+            return;
+        }
+    }
+    let frontend = out_dir.join("frontend");
+    if let Err(problem) = compile_frontend(&frontend) {
+        for line in problem.lines() {
+            println!("cargo::error={line}");
+        }
+        return;
+    }
+    write_source_map_table(&out_dir, &frontend);
+
     let commit =
         git_output(&["rev-parse", "--short=8", "HEAD"]).unwrap_or_else(|| "unknown".to_string());
     let dirty = git_output(&["status", "--porcelain", "--untracked-files=no"])
@@ -28,14 +46,122 @@ fn main() {
     let module = format!(
         "export const BUILD_INFO = Object.freeze({{\n  id: {build_id:?},\n  label: {build_id:?},\n  version: {version:?},\n  commit: {commit_label:?},\n  number: {build_number},\n}});\n"
     );
-    let out_dir = PathBuf::from(env::var_os("OUT_DIR").expect("Cargo OUT_DIR must be set"));
     fs::write(out_dir.join("build-info.js"), module).expect("build info module must be written");
 
     println!("cargo:rustc-env=CAFFOLD_BUILD_ID={build_id}");
     println!("cargo:rustc-env=CAFFOLD_BUILD_LABEL={build_id}");
     println!("cargo:rustc-env=CAFFOLD_BUILD_NUMBER={build_number}");
 }
 
+// The static asset table embeds Lit and tslib from frontend/node_modules, and
+// the TypeScript there compiles the frontend modules; each must be the version
+// frontend/package.json names.
+fn check_installed_package(name: &str) -> Result<(), String> {
+    let wanted = read_json("../frontend/package.json")
+        .and_then(|package| package["dependencies"][name].as_str().map(str::to_owned))
+        .ok_or_else(|| format!("frontend/package.json does not name a {name} version"))?;
+    let installed = read_json(&format!("../frontend/node_modules/{name}/package.json"))
+        .and_then(|package| package["version"].as_str().map(str::to_owned));
+    match installed {
+        Some(installed) if installed == wanted => Ok(()),
+        Some(installed) => Err(format!(
+            "frontend/node_modules holds {name} {installed}, but frontend/package.json needs {wanted}"
+        )),
+        None => Err(format!(
+            "frontend/node_modules does not hold {name} {wanted}"
+        )),
+    }
+}
+
+// The static asset table embeds each frontend TypeScript module as the
+// JavaScript and source map tsc writes to the same path under `output`. The
+// page modules and the service worker are typed for different globals, so
+// each has its own project; a type error in either stops the build.
+fn compile_frontend(output: &Path) -> Result<(), String> {
+    if output.exists() {
+        fs::remove_dir_all(output)
+            .map_err(|error| format!("{} could not be cleared: {error}", output.display()))?;
+    }
+    let compilers = ["tsconfig.json", "tsconfig.worker.json"].map(|project| {
+        let child = Command::new("node")
+            .arg("../frontend/node_modules/typescript/bin/tsc")
+            .arg("--project")
+            .arg(format!("../frontend/{project}"))
+            .args(["--noEmit", "false", "--outDir"])
+            .arg(output)
+            .stdout(Stdio::piped())
+            .spawn();
+        (project, child)
+    });
+    let mut problems = Vec::new();
+    for (project, child) in compilers {
+        let compiled = child
+            .and_then(|child| child.wait_with_output())
+            .map_err(|error| {
+                format!(
+                    "Node.js must be on PATH to compile the frontend's TypeScript modules: {error}"
+                )
+            })?;
+        if !compiled.status.success() {
+            problems.push(format!(
+                "tsc could not compile frontend/{project} ({})",
+                compiled.status
+            ));
+            problems.extend(
+                String::from_utf8_lossy(&compiled.stdout)
+                    .lines()
+                    .map(str::to_owned),
+            );
+        }
+    }
+    if problems.is_empty() {
+        Ok(())
+    } else {
+        Err(problems.join("\n"))
+    }
+}
+
+// The static asset table answers `<module>.js.map` from this table of every
+// source map tsc wrote.
+fn write_source_map_table(out_dir: &Path, frontend: &Path) {
+    let mut maps = Vec::new();
+    collect_source_maps(frontend, frontend, &mut maps);
+    maps.sort();
+    let arms: String = maps
+        .iter()
+        .map(|map| {
+            let file = format!("/frontend/{map}");
+            format!(
+                "        {map:?} => Some(include_bytes!(concat!(env!(\"OUT_DIR\"), {file:?}))),\n"
+            )
+        })
+        .collect();
+    let table = format!(
+        "fn compiled_source_map(path: &str) -> Option<&'static [u8]> {{\n    match path {{\n{arms}        _ => None,\n    }}\n}}\n"
+    );
+    fs::write(out_dir.join("source_maps.rs"), table).expect("source map table must be written");
+}
+
+fn collect_source_maps(root: &Path, directory: &Path, maps: &mut Vec<String>) {
+    for entry in fs::read_dir(directory).expect("compiled frontend must be readable") {
+        let path = entry
+            .expect("compiled frontend entry must be readable")
+            .path();
+        if path.is_dir() {
+            collect_source_maps(root, &path, maps);
+        } else if path.to_string_lossy().ends_with(".js.map") {
+            let relative = path
+                .strip_prefix(root)
+                .expect("map must be under the compiled frontend");
+            maps.push(relative.to_string_lossy().into_owned());
+        }
+    }
+}
+
+fn read_json(path: &str) -> Option<Value> {
+    serde_json::from_str(&fs::read_to_string(path).ok()?).ok()
+}
+
 fn git_output(args: &[&str]) -> Option<String> {
     let output = Command::new("git").args(args).output().ok()?;
     output

caffold/src/app/shell.rs

@@ -276,8 +276,12 @@ mod tests {
         let first = render_service_worker(source, "first-build").unwrap();
         let second = render_service_worker(source, "second\"\\\nbuild").unwrap();
 
-        assert!(first.starts_with("const CACHE_NAME = \"caffold-shell-first-build\";"));
-        assert!(second.starts_with("const CACHE_NAME = \"caffold-shell-second\\\"\\\\\\nbuild\";"));
+        assert!(
+            first.starts_with("\"use strict\";\nconst CACHE_NAME = \"caffold-shell-first-build\";")
+        );
+        assert!(second.starts_with(
+            "\"use strict\";\nconst CACHE_NAME = \"caffold-shell-second\\\"\\\\\\nbuild\";"
+        ));
         assert_ne!(first, second);
         assert!(!first.contains("__CAFFOLD_BUILD_ID__"));
         assert!(!second.contains("__CAFFOLD_BUILD_ID__"));

caffold/src/fs/syntax.rs

@@ -111,7 +111,7 @@ fn is_long_line(line: &str) -> bool {
 }
 
 /// The six colors the viewers have. Their numbers are the order in which
-/// `frontend/components/file-viewer/syntax-spans.js` names its classes.
+/// `frontend/components/file-viewer/syntax-spans.ts` names its classes.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum SyntaxColor {
     Comment = 0,