@zem-sh/terminal 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zem-sh/terminal",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Terminal emulator core — the Ghostty VT engine compiled to WebAssembly, GPU text rendering, ligature shaping, themes and font fallback",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -31,8 +31,17 @@ export type {
   TerminalShaderStageMode,
   TerminalShaderStageBackend,
   TerminalShaderStageSource,
+  TerminalAppSession,
 } from "./terminal/runtime/types"
 
+export {
+  createTerminalAppSession,
+  getDefaultTerminalAppSession,
+  prewarmTerminalCore,
+} from "./terminal/runtime/session"
+export type { CreateTerminalAppSessionOptions } from "./terminal/runtime/session"
+export { TERMINAL_WASM_URL } from "./terminal/wasm/wasm-asset"
+
 export {
   shaderStagesForPreset,
   shaderStagesForPresets,
@@ -56,7 +65,7 @@ export {
   TERMINAL_WASM_OPTIMIZE,
   TERMINAL_WASM_SIZE,
   TERMINAL_WASM_SHA256,
-} from "./terminal/wasm/embedded"
+} from "./terminal/wasm/metadata"
 
 // Theme APIs
 export type { ThemeColor, ThemeTerminalColor, GhosttyTheme } from "./theme/ghostty"

package/src/terminal/runtime/create-runtime.ts

@@ -119,7 +119,8 @@ import {
   type RuntimeAppApiRuntime,
   type RuntimeAppApiSharedState,
 } from "./create-runtime/runtime-app-api";
-export { createTerminalAppSession, getDefaultTerminalAppSession } from "./session";
+export { createTerminalAppSession, getDefaultTerminalAppSession, prewarmTerminalCore } from "./session";
+export type { CreateTerminalAppSessionOptions } from "./session";
 export type {
   TerminalAppElements,
   TerminalAppCallbacks,
@@ -740,6 +741,10 @@ export function createTerminalApp(options: TerminalAppOptions): TerminalApp {
   let fontPromise: Promise<void> | null = null;
   let fontError: Error | null = null;
   let fontLease: TerminalFontResourceLease | null = null;
+  let deferredFontLease: TerminalFontResourceLease | null = null;
+  // Bumped whenever the configured sources change so a late (deferred or
+  // superseded) acquisition cannot install fonts into the new generation.
+  let fontGeneration = 0;
 
   setShaderStages(options.shaderStages ?? []);
 
@@ -866,9 +871,14 @@ export function createTerminalApp(options: TerminalAppOptions): TerminalApp {
   }
 
   function releaseFontLease() {
-    if (!fontLease) return;
-    fontLease.release();
-    fontLease = null;
+    if (fontLease) {
+      fontLease.release();
+      fontLease = null;
+    }
+    if (deferredFontLease) {
+      deferredFontLease.release();
+      deferredFontLease = null;
+    }
   }
 
   function clearFontRuntimeState() {
@@ -886,6 +896,7 @@ export function createTerminalApp(options: TerminalAppOptions): TerminalApp {
 
   async function setFontSources(sources: TerminalFontSource[]) {
     configuredFontSources = normalizeFontSources(sources, undefined);
+    fontGeneration += 1;
     fontPromise = null;
     fontError = null;
     releaseFontLease();
@@ -949,15 +960,80 @@ export function createTerminalApp(options: TerminalAppOptions): TerminalApp {
     appendLog(`[ui] line height ${next.toFixed(2)}`);
   }
 
+  /**
+   * Append late-loaded fallback faces (heavy symbol/emoji/CJK fonts marked
+   * `defer`) to the live font chain. Appending is safe: indices of the faces
+   * already installed do not move, and only the glyph-pick cache needs to be
+   * invalidated so previously-missing glyphs are re-resolved against the new
+   * entries on the next frame.
+   */
+  async function loadDeferredFonts(sources: TerminalFontSource[], generation: number) {
+    let lease: TerminalFontResourceLease | null = null;
+    try {
+      lease = await fontResourceStore.acquire(sources);
+    } catch {
+      return;
+    }
+    if (!lease.faces.length) {
+      lease.release();
+      return;
+    }
+    if (generation !== fontGeneration || !fontState.font) {
+      lease.release();
+      return;
+    }
+
+    releaseDeferredFontLease();
+    deferredFontLease = lease;
+
+    const entries: FontEntry[] = [];
+    for (let i = 0; i < lease.faces.length; i += 1) {
+      const face = lease.faces[i];
+      entries.push(createFontEntry(face.font, face.label));
+    }
+    if (!entries.length) return;
+
+    fontState.fonts.push(...entries);
+    fontState.fontPickCache.clear();
+    needsRender = true;
+    appendLog(`[ui] deferred fallback fonts loaded (+${entries.length})`);
+  }
+
+  function releaseDeferredFontLease() {
+    if (!deferredFontLease) return;
+    deferredFontLease.release();
+    deferredFontLease = null;
+  }
+
   async function ensureFont() {
     if (fontState.font || fontPromise) return fontPromise;
     fontPromise = (async () => {
+      const generation = fontGeneration;
+      const configured = configuredFontSources;
+      // Heavy fallback faces opt out of the critical path: paint with the
+      // primary chain first, then append them in the background. If every
+      // source is deferred (or none is), there is nothing to defer — load the
+      // whole list up front.
+      const deferredSources = configured.filter((source) => source.defer);
+      const eagerSources = configured.filter((source) => !source.defer);
+      const initialSources = eagerSources.length ? eagerSources : configured;
+
       let acquiredLease: TerminalFontResourceLease | null = null;
       try {
-        acquiredLease = await fontResourceStore.acquire(configuredFontSources);
+        acquiredLease = await fontResourceStore.acquire(initialSources);
+        if (generation !== fontGeneration) {
+          acquiredLease.release();
+          return;
+        }
         if (!acquiredLease.faces.length) {
           acquiredLease.release();
           acquiredLease = await fontResourceStore.acquire(FALLBACK_LOCAL_FONT_SOURCES);
+          // A newer font selection superseded this load while the fallback
+          // system fonts were being acquired.
+          if (generation !== fontGeneration) {
+            acquiredLease.release();
+            return;
+          }
         }
         if (!acquiredLease.faces.length) {
           throw new Error("Unable to load any configured font source.");
@@ -988,12 +1064,26 @@ export function createTerminalApp(options: TerminalAppOptions): TerminalApp {
           log("font loaded");
         }
         updateGrid();
+
+        // Start the deferred faces only after the first frame has had a
+        // chance to paint; they are usually large font files.
+        if (deferredSources.length && eagerSources.length) {
+          const startDeferred = () => {
+            void loadDeferredFonts(deferredSources, generation);
+          };
+          if (typeof requestAnimationFrame === "function") {
+            requestAnimationFrame(startDeferred);
+          } else {
+            setTimeout(startDeferred, 16);
+          }
+        }
       } catch (err) {
         if (acquiredLease) {
           acquiredLease.release();
         } else {
           releaseFontLease();
         }
+        if (generation !== fontGeneration) return;
         clearFontRuntimeState();
         const error = err instanceof Error ? err : new Error(String(err));
         fontError = error;
@@ -1005,6 +1095,7 @@ export function createTerminalApp(options: TerminalAppOptions): TerminalApp {
   }
 
   cleanupFns.push(() => {
+    fontGeneration += 1;
     releaseFontLease();
     clearFontRuntimeState();
     configuredFontSources = [];

package/src/terminal/runtime/font-resource-store.ts

@@ -268,9 +268,27 @@ function createUrlByteCache(
   };
 }
 
+type LocalFontQuery = () => Promise<LocalFontFaceData[]>;
+
+/** Resolve the Local Font Access query function once per environment. */
+function resolveLocalFontQuery(): LocalFontQuery | null {
+  const globalAccess = globalThis as GlobalWithLocalFontAccess;
+  const nav = (globalAccess.navigator ??
+    (typeof navigator !== "undefined" ? navigator : undefined)) as NavigatorWithLocalFontAccess;
+  if (!nav) return null;
+  if (typeof globalAccess.queryLocalFonts === "function") {
+    return () => globalAccess.queryLocalFonts!();
+  }
+  if (typeof nav.queryLocalFonts === "function") {
+    return () => nav.queryLocalFonts!();
+  }
+  return null;
+}
+
 async function tryLoadLocalFontBuffer(
   matchers: string[],
   label: string,
+  queryFonts?: LocalFontQuery,
 ): Promise<ArrayBuffer | null> {
   const normalizedMatchers = matchers.map((matcher) => matcher.toLowerCase()).filter(Boolean);
   if (!normalizedMatchers.length) return null;
@@ -279,13 +297,8 @@ async function tryLoadLocalFontBuffer(
   const nav = (globalAccess.navigator ??
     (typeof navigator !== "undefined" ? navigator : undefined)) as NavigatorWithLocalFontAccess;
   if (!nav) return null;
-  const queryLocalFonts =
-    typeof globalAccess.queryLocalFonts === "function"
-      ? globalAccess.queryLocalFonts.bind(globalAccess)
-      : typeof nav.queryLocalFonts === "function"
-        ? nav.queryLocalFonts.bind(nav)
-        : null;
-  if (!queryLocalFonts) return null;
+  const loadFonts = queryFonts ?? resolveLocalFontQuery();
+  if (!loadFonts) return null;
 
   const sourceHint = detectStyleHint(`${label} ${normalizedMatchers.join(" ")}`);
   const queryPermission = nav.permissions?.query;
@@ -299,7 +312,7 @@ async function tryLoadLocalFontBuffer(
   }
 
   try {
-    const fonts = await queryLocalFonts();
+    const fonts = await loadFonts();
     const matches = fonts.filter((font) => {
       const name =
         `${font.family ?? ""} ${font.fullName ?? ""} ${font.postscriptName ?? ""}`.toLowerCase();
@@ -393,6 +406,16 @@ export function createTerminalFontResourceStore(
   const leaseSources = new Map<number, Map<string, number>>();
   let totalCachedSourceBytes = 0;
   let nextLeaseId = 1;
+  // Enumerating installed fonts is expensive and the same list serves every
+  // local matcher. Since sources now load concurrently, share one query per
+  // store instead of issuing one per source.
+  let localFontListPromise: Promise<LocalFontFaceData[]> | null = null;
+  const queryLocalFontList = (): Promise<LocalFontFaceData[]> => {
+    if (localFontListPromise) return localFontListPromise;
+    const query = resolveLocalFontQuery();
+    localFontListPromise = query ? query().catch(() => []) : Promise.resolve([]);
+    return localFontListPromise;
+  };
 
   const removeSourceEntry = (key: string) => {
     const entry = sourceCache.get(key);
@@ -446,6 +469,7 @@ export function createTerminalFontResourceStore(
       return await tryLoadLocalFontBuffer(
         matchers,
         source.label ?? source.matchers[0] ?? "local-font",
+        queryLocalFontList,
       );
     }
     return await loadUrlBuffer(sourceKey, normalizeUrlKey(source.url));
@@ -552,42 +576,55 @@ export function createTerminalFontResourceStore(
   };
 
   const acquire = async (sources: TerminalFontSource[]): Promise<TerminalFontResourceLease> => {
-    const faces: TerminalFontResourceFace[] = [];
-    const sourceRefs = new Map<string, number>();
+    // Load and parse every source concurrently. The store already dedupes
+    // in-flight loads/parses; awaiting them one at a time serialized each
+    // network fetch and parse, which dominated first paint on a cold cache.
+    // `Promise.all` preserves source order, and the ordered chain matters:
+    // primary face first, fallbacks after.
+    const loaded = await Promise.all(
+      sources.map(async (source, sourceIndex) => {
+        const sourceKey = resolveSourceKey(source);
+        const baseLabel = sourceBaseLabel(source, sourceIndex);
+        let buffer: ArrayBuffer | null;
+        try {
+          buffer = await loadSourceBufferCached(source, sourceKey);
+        } catch {
+          buffer = null;
+        }
 
-    for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex += 1) {
-      const source = sources[sourceIndex];
-      const sourceKey = resolveSourceKey(source);
-      const baseLabel = sourceBaseLabel(source, sourceIndex);
-      let buffer: ArrayBuffer | null;
-      try {
-        buffer = await loadSourceBufferCached(source, sourceKey);
-      } catch {
-        buffer = null;
-      }
+        if (!buffer) {
+          if (source.type === "local") {
+            const prefix = source.required
+              ? "required local font missing"
+              : "optional local font missing";
+            console.warn(`[font] ${prefix} (${source.matchers.join(", ")})`);
+          }
+          return null;
+        }
 
-      if (!buffer) {
-        if (source.type === "local") {
-          const prefix = source.required
-            ? "required local font missing"
-            : "optional local font missing";
-          console.warn(`[font] ${prefix} (${source.matchers.join(", ")})`);
+        let parsedFaces: ParsedFontFace[];
+        try {
+          parsedFaces = await parseSourceFacesCached(sourceKey, buffer);
+        } catch {
+          parsedFaces = [];
         }
-        continue;
-      }
+        if (!parsedFaces.length) return null;
+        return { sourceKey, baseLabel, parsedFaces };
+      }),
+    );
 
-      let parsedFaces: ParsedFontFace[];
-      try {
-        parsedFaces = await parseSourceFacesCached(sourceKey, buffer);
-      } catch {
-        parsedFaces = [];
-      }
-      if (!parsedFaces.length) continue;
+    const faces: TerminalFontResourceFace[] = [];
+    const sourceRefs = new Map<string, number>();
+    const usedAt = now();
+    for (let sourceIndex = 0; sourceIndex < loaded.length; sourceIndex += 1) {
+      const result = loaded[sourceIndex];
+      if (!result) continue;
+      const { sourceKey, baseLabel, parsedFaces } = result;
 
       const sourceEntry = sourceCache.get(sourceKey);
       if (sourceEntry) {
         sourceEntry.refCount += 1;
-        sourceEntry.lastUsedAt = now();
+        sourceEntry.lastUsedAt = usedAt;
       }
       sourceRefs.set(sourceKey, (sourceRefs.get(sourceKey) ?? 0) + 1);
 

package/src/terminal/runtime/session.ts

@@ -3,12 +3,19 @@ import { loadTerminalWasm, type TerminalWasm } from "../wasm";
 import { createTerminalFontResourceStore } from "./font-resource-store";
 import type { TerminalAppSession, TerminalWasmLogListener } from "./types";
 
+export type CreateTerminalAppSessionOptions = {
+  /** URL of the `terminal.wasm` asset; defaults to the bundled package asset. */
+  wasmUrl?: string;
+};
+
 /**
  * Create a new app session that lazily loads the WASM module and
  * initializes the WebGPU core on first use. Multiple panes can
  * share a single session to avoid duplicate resource loading.
  */
-export function createTerminalAppSession(): TerminalAppSession {
+export function createTerminalAppSession(
+  options: CreateTerminalAppSessionOptions = {},
+): TerminalAppSession {
   let wasmPromise: Promise<TerminalWasm> | null = null;
   let webgpuCorePromise: Promise<WebGPUCoreState | null> | null = null;
   const wasmLogListeners = new Set<TerminalWasmLogListener>();
@@ -23,7 +30,7 @@ export function createTerminalAppSession(): TerminalAppSession {
   return {
     getWasm: () => {
       if (!wasmPromise) {
-        wasmPromise = loadTerminalWasm({ log: forwardWasmLog });
+        wasmPromise = loadTerminalWasm({ log: forwardWasmLog, wasmUrl: options.wasmUrl });
       }
       return wasmPromise;
     },
@@ -55,3 +62,11 @@ export function getDefaultTerminalAppSession(): TerminalAppSession {
   }
   return defaultTerminalAppSession;
 }
+
+/**
+ * Start loading (and compiling) the terminal WASM core for a session ahead of
+ * the first pane. Idempotent — the session caches its in-flight load.
+ */
+export function prewarmTerminalCore(session?: TerminalAppSession): Promise<TerminalWasm> {
+  return (session ?? getDefaultTerminalAppSession()).getWasm();
+}

package/src/terminal/runtime/types.ts

@@ -147,6 +147,12 @@ export type TerminalUrlFontSource = {
   url: string;
   /** Human-readable label for debug/log output. */
   label?: string;
+  /**
+   * Load after the first frame instead of blocking startup. Use for large,
+   * rarely-needed fallback faces (symbol/emoji/CJK); the primary chain must
+   * stay eager.
+   */
+  defer?: boolean;
 };
 
 /** Font source loaded from an in-memory buffer. */
@@ -156,6 +162,8 @@ export type TerminalBufferFontSource = {
   data: TerminalFontBufferData;
   /** Human-readable label for debug/log output. */
   label?: string;
+  /** Load after the first frame instead of blocking startup. */
+  defer?: boolean;
 };
 
 /** Font source resolved from locally installed fonts via the Local Font Access API. */
@@ -167,6 +175,8 @@ export type TerminalLocalFontSource = {
   label?: string;
   /** If true, font loading fails when no local match is found. */
   required?: boolean;
+  /** Load after the first frame instead of blocking startup. */
+  defer?: boolean;
 };
 
 /**

package/src/terminal/wasm/metadata.ts

@@ -0,0 +1,11 @@
+// Auto-generated by build:wasm script. Do not edit by hand.
+// Build provenance only — intentionally free of the binary so importing
+// it does not pull the WASM into an application bundle.
+// Source: wasm/zig-out/bin/terminal.wasm
+export const GHOSTTY_VERSION: string = "1.3.2-dev";
+export const GHOSTTY_COMMIT: string = "e1d31deaaed21aa9225afca78d778fb373c95852";
+export const GHOSTTY_PATCH_SHA256: string = "252172b9c6868bccc0277ab5141e8725fe76a9b619788eccdc6e227686f80da0";
+export const ZIG_VERSION: string = "0.15.2";
+export const TERMINAL_WASM_OPTIMIZE: string = "ReleaseSafe";
+export const TERMINAL_WASM_SIZE: number = 1042257;
+export const TERMINAL_WASM_SHA256: string = "cb2873ac405e163941beb090d68c4acf990957fda51e42d72a1218baa67496de";

package/src/terminal/wasm/runtime/terminal-wasm.ts

@@ -1,5 +1,4 @@
-import { decodeBase64Bytes } from "../../utils/base64";
-import { WASM_BASE64 } from "../embedded";
+import { TERMINAL_WASM_URL } from "../wasm-asset";
 import { resolveWasmAbi } from "./abi";
 import { readKittyPlacements } from "./kitty";
 import { readRenderState } from "./render-state";
@@ -45,9 +44,9 @@ export class TerminalWasm {
     this.renderViewCaches = new Map();
   }
 
-  /** Load and instantiate the embedded WASM module. */
+  /** Load and instantiate the terminal WASM module. */
   static async load(options: TerminalWasmOptions = {}): Promise<TerminalWasm> {
-    const bytes = decodeBase64Bytes(WASM_BASE64);
+    const bytes = await loadWasmBytes(options.wasmUrl);
     let memory: WebAssembly.Memory | null = null;
     const log = options.log;
 
@@ -282,7 +281,25 @@ export class TerminalWasm {
   }
 }
 
-/** Load and instantiate the embedded WASM module (convenience function). */
+/** Load and instantiate the terminal WASM module (convenience function). */
 export async function loadTerminalWasm(options: TerminalWasmOptions = {}): Promise<TerminalWasm> {
   return TerminalWasm.load(options);
 }
+
+/**
+ * Fetch the WASM binary from its asset URL. The binary is a separate asset
+ * rather than an embedded base64 string so browsers can cache and compile it
+ * independently, and the JS bundle stays out of the multi-megabyte range.
+ */
+async function loadWasmBytes(wasmUrl?: string): Promise<BufferSource> {
+  const url = wasmUrl ?? TERMINAL_WASM_URL;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`failed to load terminal WASM from ${url}: HTTP ${response.status}`);
+  }
+  const buffer = await response.arrayBuffer();
+  if (!buffer.byteLength) {
+    throw new Error(`terminal WASM asset is empty: ${url}`);
+  }
+  return buffer;
+}

package/src/terminal/wasm/runtime/types.ts

@@ -176,6 +176,11 @@ export type TerminalWasmExports = WebAssembly.Exports & {
 /** Construction options for WASM runtime. */
 export type TerminalWasmOptions = {
   log?: (message: string) => void;
+  /**
+   * URL of the `terminal.wasm` asset. Defaults to the copy shipped in the
+   * package's `assets` directory (resolved by the bundler).
+   */
+  wasmUrl?: string;
 };
 
 export type RenderPtrs = {

package/src/terminal/wasm/wasm-asset.ts

@@ -0,0 +1,10 @@
+/**
+ * URL of the standalone terminal WASM asset, emitted next to the bundle by the
+ * consuming bundler (`new URL(..., import.meta.url)` is understood by Vite and
+ * most other modern bundlers). Kept in its own module so applications can pass
+ * an explicit `wasmUrl` when they copy the asset themselves.
+ */
+export const TERMINAL_WASM_URL = new URL(
+  "../../../assets/terminal.wasm",
+  import.meta.url,
+).href;