herdr-remote-relay 0.3.12 → 0.3.13

package/dist/protocol/messages.d.ts

@@ -0,0 +1,321 @@
+import type { HostTerminalFont, HostTerminalPalette } from './terminal.js';
+export declare const WS_HOST_PATH = "/ws/host";
+export declare const WS_CLIENT_PATH = "/ws/client";
+/** What a peer may announce in its hello's `capabilities`. */
+export declare const CAPABILITY: {
+    /** Keep browser sessions alive across a host reconnect. */
+    readonly hostHandoff: "host_handoff";
+    /** The host sends heartbeats only while a browser is watching. */
+    readonly idleHeartbeat: "idle_heartbeat";
+    /** The host routes output by 16-bit stream index (v2 frames). */
+    readonly binaryFrameV2: "binary_frame_v2";
+};
+export type ClientRole = 'controller' | 'viewer';
+export interface ClientHelloMessage {
+    type: 'hello';
+    protocol: 1;
+    token?: string;
+    pairCode?: string;
+    clientId: string;
+    cols: number;
+    rows: number;
+    capabilities?: string[];
+}
+export interface ClientClaimControlMessage {
+    type: 'claim_control';
+    force?: boolean;
+}
+export interface ClientReleaseControlMessage {
+    type: 'release_control';
+}
+export interface ClientResizeMessage {
+    type: 'resize';
+    cols: number;
+    rows: number;
+}
+export interface ClientPingMessage {
+    type: 'ping';
+}
+export interface ClientPasteFileMessage {
+    type: 'paste_file';
+    mime: string;
+    dataBase64: string;
+}
+/**
+ * Start Herdr on the workstation this window is paired to. Carries nothing:
+ * the relay routes it to the window's own host, and the host decides where and
+ * as whom Herdr runs.
+ */
+export interface ClientHerdrStartMessage {
+    type: 'herdr_start';
+}
+/** One slice of an announced font file, by the file's hash. */
+export interface ClientHostFontChunkRequestMessage {
+    type: 'host_font_chunk_request';
+    sha256: string;
+    index: number;
+}
+/** Cut `text`'s characters out of an announced large font. */
+export interface ClientHostFontSubsetRequestMessage {
+    type: 'host_font_subset_request';
+    sha256: string;
+    text: string;
+    requestId: string;
+}
+/** Ask the workstation to read its terminal's font settings again. */
+export interface ClientHostFontRefreshMessage {
+    type: 'host_font_refresh';
+}
+export type ClientJsonMessage = ClientHelloMessage | ClientHostFontChunkRequestMessage | ClientHostFontSubsetRequestMessage | ClientHostFontRefreshMessage | ClientClaimControlMessage | ClientReleaseControlMessage | ClientResizeMessage | ClientPingMessage | ClientPasteFileMessage | ClientHerdrStartMessage;
+export interface ServerReadyMessage {
+    type: 'ready';
+    role: ClientRole;
+    controllerId?: string | null;
+    hostId?: string;
+    hostname?: string;
+    clientId?: string;
+    terminalPalette?: HostTerminalPalette | null;
+    terminalFont?: HostTerminalFont | null;
+    /** How many windows share this terminal, this one included. */
+    clientCount?: number;
+}
+export interface ServerPairedMessage {
+    type: 'paired';
+    token: string;
+    deviceId?: string;
+    hostId?: string;
+    expiresAt?: number | string;
+}
+export interface ServerControlStateMessage {
+    type: 'control_state';
+    role: ClientRole;
+    controllerId?: string | null;
+    /** How many windows share this terminal, this one included. */
+    clientCount?: number;
+}
+export interface ServerControlGrantedMessage {
+    type: 'control_granted';
+}
+export interface ServerHostReconnectingMessage {
+    type: 'host_reconnecting';
+    code?: string;
+}
+export interface ServerSessionReadyMessage {
+    type: 'session_ready';
+    clientId?: string;
+}
+export interface ServerSessionRestartedMessage {
+    type: 'session_restarted';
+    streamId?: string;
+    cols?: number;
+    rows?: number;
+    hostname?: string;
+    terminalPalette?: HostTerminalPalette | null;
+    terminalFont?: HostTerminalFont | null;
+}
+export interface ServerExitMessage {
+    type: 'exit';
+    code?: number | null;
+    reason?: string;
+}
+export interface ServerErrorMessage {
+    type: 'error';
+    code: string | number;
+    message: string;
+}
+export interface ServerPongMessage {
+    type: 'pong';
+}
+export interface ServerPasteFileReadyMessage {
+    type: 'paste_file_ready';
+    path: string;
+}
+/** Herdr's own vocabulary for what a pane's agent is doing. */
+export type AgentStatus = 'blocked' | 'done' | 'working' | 'idle' | 'unknown';
+export interface AgentStatusEntry {
+    paneId: string | null;
+    workspaceId: string | null;
+    agent: string | null;
+    title: string | null;
+    status: string | null;
+    focused: boolean;
+}
+/**
+ * What the workstation's agents are doing.
+ *
+ * Broadcast to every window watching this workstation rather than scoped to a
+ * stream: it is a fact about the machine, not about one terminal. The host
+ * reads it from Herdr's socket API.
+ */
+export interface ServerAgentStatusMessage {
+    type: 'agent_status';
+    focusedPaneId?: string | null;
+    focusedAgent?: string | null;
+    counts: Partial<Record<AgentStatus, number>>;
+    total: number;
+    agents: AgentStatusEntry[];
+}
+/**
+ * Whether the workstation's herdr-remote is behind the newest release. Checked
+ * by the host when a window opens and kept by the relay for later windows.
+ */
+export interface ServerUpdateStatusMessage {
+    type: 'update_status';
+    /** The version the workstation is running. */
+    current: string;
+    /** The version on disk; ahead of `current` when an update awaits a restart. */
+    installed: string;
+    latest: string;
+    updateAvailable: boolean;
+    restartPending: boolean;
+}
+/** The workstation re-read its terminal font; sent to every window. */
+export interface ServerTerminalFontMessage {
+    type: 'terminal_font';
+    terminalFont: HostTerminalFont | null;
+}
+export interface ServerHostFontChunkMessage {
+    type: 'host_font_chunk';
+    sha256: string;
+    index: number;
+    total: number;
+    dataBase64: string;
+}
+/**
+ * A cut is ready. Small ones carry their bytes; a large one is pulled like a
+ * font file, by `subsetSha`, a slice at a time.
+ */
+export interface ServerHostFontSubsetMessage {
+    type: 'host_font_subset_ready';
+    requestId: string;
+    sha256: string;
+    subsetSha: string;
+    bytes: number;
+    dataBase64?: string;
+}
+export type ServerJsonMessage = ServerTerminalFontMessage | ServerHostFontSubsetMessage | ServerHostFontChunkMessage | ServerReadyMessage | ServerPairedMessage | ServerControlStateMessage | ServerControlGrantedMessage | ServerHostReconnectingMessage | ServerSessionRestartedMessage | ServerSessionReadyMessage | ServerExitMessage | ServerErrorMessage | ServerPongMessage | ServerPasteFileReadyMessage | ServerAgentStatusMessage | ServerUpdateStatusMessage;
+/**
+ * Every host message about one browser's session names it by stream. The
+ * relay sends both fields with the same value; a host reads `clientId` first.
+ */
+interface StreamAddressed {
+    clientId?: string;
+    streamId?: string;
+}
+export interface HostHelloMessage {
+    type: 'host_hello';
+    protocol: 1;
+    hostId: string;
+    token: string;
+    password?: string | null;
+    hostname?: string;
+    platform?: string;
+    arch?: string;
+    terminalPalette?: HostTerminalPalette | null;
+    terminalFont?: HostTerminalFont | null;
+    capabilities?: string[];
+}
+/** One PTY the host is running, as the relay's status page lists it. */
+export interface HostPtySummary {
+    id: string;
+    pid: number | null;
+    command: string;
+    cols: number;
+    rows: number;
+    cwd?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export interface HostHeartbeatMessage {
+    type: 'heartbeat';
+    load: {
+        load1m?: number;
+        load5m?: number;
+        load15m?: number;
+        rssBytes?: number;
+        heapUsedBytes?: number;
+    };
+    ptys: HostPtySummary[];
+}
+export interface HostShutdownMessage {
+    type: 'host_shutdown';
+}
+export interface HostSessionReadyMessage extends StreamAddressed {
+    type: 'session_ready';
+}
+export interface HostSessionExitMessage extends StreamAddressed {
+    type: 'session_exit';
+    code: number | null;
+}
+export interface HostPasteFileReadyMessage extends StreamAddressed {
+    type: 'paste_file_ready';
+    path: string;
+}
+export interface HostErrorMessage extends StreamAddressed {
+    type: 'error';
+    code: string;
+    message: string;
+}
+export type HostAgentStatusMessage = ServerAgentStatusMessage;
+export type HostUpdateStatusMessage = ServerUpdateStatusMessage;
+export type HostTerminalFontMessage = ServerTerminalFontMessage;
+export type HostFontChunkMessage = ServerHostFontChunkMessage & StreamAddressed;
+export type HostFontSubsetMessage = ServerHostFontSubsetMessage & StreamAddressed;
+export type HostMessage = HostHelloMessage | HostHeartbeatMessage | HostShutdownMessage | HostAgentStatusMessage | HostUpdateStatusMessage | HostTerminalFontMessage | HostSessionReadyMessage | HostSessionExitMessage | HostFontChunkMessage | HostFontSubsetMessage | HostPasteFileReadyMessage | HostErrorMessage;
+export interface RelayHostReadyMessage {
+    type: 'host_ready';
+    protocol: 1;
+    hostId: string;
+    clientCount: number;
+}
+/** How many browsers watch; the host stops its telemetry at zero. */
+export interface RelayClientCountMessage {
+    type: 'client_count';
+    clientCount: number;
+}
+export interface RelaySessionStartMessage extends StreamAddressed {
+    type: 'session_start';
+    cols: number;
+    rows: number;
+    role: ClientRole;
+    /** Present when the host negotiated v2 frames and an index was free. */
+    streamIndex?: number;
+}
+export interface RelaySessionStopMessage extends StreamAddressed {
+    type: 'session_stop';
+}
+export interface RelayResizeMessage extends StreamAddressed {
+    type: 'resize';
+    cols: number;
+    rows: number;
+}
+export interface RelayHerdrStartMessage extends StreamAddressed {
+    type: 'herdr_start';
+}
+export interface RelayHostFontRefreshMessage extends StreamAddressed {
+    type: 'host_font_refresh';
+}
+export interface RelayHostFontChunkRequestMessage extends StreamAddressed {
+    type: 'host_font_chunk_request';
+    sha256: string;
+    index: number;
+}
+export interface RelayHostFontSubsetRequestMessage extends StreamAddressed {
+    type: 'host_font_subset_request';
+    requestId: string;
+    sha256: string;
+    text: string;
+}
+export interface RelayPasteFileMessage extends StreamAddressed {
+    type: 'paste_file';
+    mime: string;
+    dataBase64: string;
+}
+/** Sent instead of `host_ready` when the handshake is refused. */
+export interface RelayErrorMessage {
+    type: 'error';
+    code: string;
+    message: string;
+}
+export type RelayToHostMessage = RelayHostReadyMessage | RelayClientCountMessage | RelaySessionStartMessage | RelaySessionStopMessage | RelayResizeMessage | RelayHerdrStartMessage | RelayHostFontRefreshMessage | RelayHostFontChunkRequestMessage | RelayHostFontSubsetRequestMessage | RelayPasteFileMessage | RelayErrorMessage;
+export {};

package/dist/protocol/messages.js

@@ -0,0 +1,18 @@
+// Every JSON message on the relay's two WebSocket channels, by direction:
+//
+//   host connector ──HostMessage──▶ relay ──ServerJsonMessage──▶ browser
+//   host connector ◀─RelayToHostMessage── relay ◀─ClientJsonMessage── browser
+//
+// Browser-safe: types and constants only. Terminal bytes travel separately as
+// binary frames (see ./frames).
+export const WS_HOST_PATH = '/ws/host';
+export const WS_CLIENT_PATH = '/ws/client';
+/** What a peer may announce in its hello's `capabilities`. */
+export const CAPABILITY = {
+    /** Keep browser sessions alive across a host reconnect. */
+    hostHandoff: 'host_handoff',
+    /** The host sends heartbeats only while a browser is watching. */
+    idleHeartbeat: 'idle_heartbeat',
+    /** The host routes output by 16-bit stream index (v2 frames). */
+    binaryFrameV2: 'binary_frame_v2',
+};

package/dist/protocol/paste.d.ts

@@ -0,0 +1,14 @@
+/** Largest decoded image a browser may paste. */
+export declare const PASTE_MAX_BYTES: number;
+/** Image types a paste may carry, with the extension the host saves them under. */
+export declare const PASTE_IMAGE_EXTENSIONS: {
+    readonly 'image/png': ".png";
+    readonly 'image/jpeg': ".jpg";
+    readonly 'image/webp': ".webp";
+    readonly 'image/gif': ".gif";
+};
+export type PasteImageMimeType = keyof typeof PASTE_IMAGE_EXTENSIONS;
+export declare const PASTE_IMAGE_MIME_TYPES: PasteImageMimeType[];
+export declare function isPasteImageMime(value: unknown): value is PasteImageMimeType;
+/** Whether `bytes` begin with the file signature `mime` promises. */
+export declare function hasImageSignature(mime: string, bytes: Uint8Array): boolean;

package/dist/protocol/paste.js

@@ -0,0 +1,50 @@
+// Rules for an image pasted in a browser: the browser compresses to fit them,
+// the relay refuses what breaks them, and the host checks again before it
+// writes a file. Browser-safe: no Node APIs.
+/** Largest decoded image a browser may paste. */
+export const PASTE_MAX_BYTES = 3 * 1024 * 1024;
+/** Image types a paste may carry, with the extension the host saves them under. */
+export const PASTE_IMAGE_EXTENSIONS = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/webp': '.webp',
+    'image/gif': '.gif',
+};
+export const PASTE_IMAGE_MIME_TYPES = Object.keys(PASTE_IMAGE_EXTENSIONS);
+export function isPasteImageMime(value) {
+    return typeof value === 'string' && Object.hasOwn(PASTE_IMAGE_EXTENSIONS, value);
+}
+/** Whether `bytes` begin with the file signature `mime` promises. */
+export function hasImageSignature(mime, bytes) {
+    switch (mime) {
+        case 'image/png':
+            return (bytes.length >= 8 &&
+                bytes[0] === 0x89 &&
+                bytes[1] === 0x50 &&
+                bytes[2] === 0x4e &&
+                bytes[3] === 0x47);
+        case 'image/jpeg':
+            return bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff;
+        case 'image/webp':
+            return (bytes.length >= 12 &&
+                // 'RIFF'
+                bytes[0] === 0x52 &&
+                bytes[1] === 0x49 &&
+                bytes[2] === 0x46 &&
+                bytes[3] === 0x46 &&
+                // 'WEBP'
+                bytes[8] === 0x57 &&
+                bytes[9] === 0x45 &&
+                bytes[10] === 0x42 &&
+                bytes[11] === 0x50);
+        case 'image/gif':
+            // 'GIF8'
+            return (bytes.length >= 6 &&
+                bytes[0] === 0x47 &&
+                bytes[1] === 0x49 &&
+                bytes[2] === 0x46 &&
+                bytes[3] === 0x38);
+        default:
+            return false;
+    }
+}

package/dist/protocol/terminal.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The sixteen ANSI slots a host may report, in index order. A palette is
+ * all-or-nothing: half the host's colors mixed with half the browser's would
+ * look worse than either set on its own.
+ */
+export declare const ANSI_PALETTE_KEYS: readonly ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "brightBlack", "brightRed", "brightGreen", "brightYellow", "brightBlue", "brightMagenta", "brightCyan", "brightWhite"];
+export type AnsiPaletteKey = (typeof ANSI_PALETTE_KEYS)[number];
+/** The sixteen ANSI slots, exactly as the host's terminal reported them. */
+export type HostAnsiPalette = Record<AnsiPaletteKey, string>;
+/**
+ * The workstation's terminal colors, answered by the host's own emulator to
+ * the OSC 10/11/12 and OSC 4 queries. The browser renders with these instead
+ * of inventing a palette, which is what makes the web view look like the
+ * session does on the workstation.
+ */
+export interface HostTerminalPalette {
+    background?: string;
+    foreground?: string;
+    cursor?: string;
+    ansi?: HostAnsiPalette;
+}
+/** The faces a host may offer, in the order a browser registers them. */
+export declare const TERMINAL_FONT_STYLES: readonly ["regular", "bold", "italic", "boldItalic"];
+export type HostFontStyle = (typeof TERMINAL_FONT_STYLES)[number];
+export declare const TERMINAL_FONT_FORMATS: readonly ["truetype", "opentype"];
+export type HostFontFormat = (typeof TERMINAL_FONT_FORMATS)[number];
+/** `cjk`: the face Hanzi fall back to; `all`: the family itself, too big to send whole. */
+export declare const TERMINAL_FONT_SUBSET_SCOPES: readonly ["cjk", "all"];
+export type HostFontSubsetScope = (typeof TERMINAL_FONT_SUBSET_SCOPES)[number];
+/** One font file; a CJK face is larger than this and is left to the browser. */
+export declare const MAX_TERMINAL_FONT_BYTES: number;
+/** Raw bytes per `host_font_chunk`; base64 keeps it far below any payload cap. */
+export declare const TERMINAL_FONT_CHUNK_BYTES: number;
+/** One file behind the workstation's terminal font, known here only by hash. */
+export interface HostFontFace {
+    style: HostFontStyle;
+    format: HostFontFormat;
+    bytes: number;
+    sha256: string;
+}
+/** A font too large to send whole, cut to the characters a window draws. */
+export interface HostFontSubsetSource {
+    family: string;
+    style: 'regular';
+    scope: HostFontSubsetScope;
+    /** Identifies the source font; subsets are cached under it. */
+    sha256: string;
+}
+/**
+ * The font the workstation's terminal draws with, read by the host from that
+ * terminal's own settings. `faces` lists the files a browser without the font
+ * may fetch, a slice at a time.
+ */
+export interface HostTerminalFont {
+    family: string;
+    /** In CSS pixels, converted from the terminal's points. */
+    sizePx?: number;
+    /** Which terminal it came from: `gnome-terminal`, `kitty`, … */
+    source?: string;
+    faces: HostFontFace[];
+    subsets?: HostFontSubsetSource[];
+}
+/**
+ * Validates a terminal palette crossing the wire.
+ *
+ * The host reports what its own terminal answered to the OSC color queries,
+ * and the browser paints with it. Anything that is not a plain `#rrggbb`
+ * string is dropped here, so a compromised or buggy host cannot push arbitrary
+ * data into a browser's renderer options.
+ */
+export declare function sanitizeTerminalPalette(value: unknown): HostTerminalPalette | null;
+/**
+ * Validates the terminal font a host reports.
+ *
+ * The browser draws the session in the family the workstation's terminal
+ * uses, and may fetch the font files by their hash. Every field is optional
+ * except the family; anything malformed is dropped rather than repaired.
+ */
+export declare function sanitizeTerminalFont(value: unknown): HostTerminalFont | null;

package/dist/protocol/terminal.js

@@ -0,0 +1,150 @@
+// The workstation's terminal palette and font, as a host reports them and a
+// browser receives them. Browser-safe: no Node APIs, so the web app imports it.
+/**
+ * The sixteen ANSI slots a host may report, in index order. A palette is
+ * all-or-nothing: half the host's colors mixed with half the browser's would
+ * look worse than either set on its own.
+ */
+export const ANSI_PALETTE_KEYS = [
+    'black',
+    'red',
+    'green',
+    'yellow',
+    'blue',
+    'magenta',
+    'cyan',
+    'white',
+    'brightBlack',
+    'brightRed',
+    'brightGreen',
+    'brightYellow',
+    'brightBlue',
+    'brightMagenta',
+    'brightCyan',
+    'brightWhite',
+];
+/** The faces a host may offer, in the order a browser registers them. */
+export const TERMINAL_FONT_STYLES = ['regular', 'bold', 'italic', 'boldItalic'];
+export const TERMINAL_FONT_FORMATS = ['truetype', 'opentype'];
+/** `cjk`: the face Hanzi fall back to; `all`: the family itself, too big to send whole. */
+export const TERMINAL_FONT_SUBSET_SCOPES = ['cjk', 'all'];
+/** One font file; a CJK face is larger than this and is left to the browser. */
+export const MAX_TERMINAL_FONT_BYTES = 16 * 1024 * 1024;
+/** Raw bytes per `host_font_chunk`; base64 keeps it far below any payload cap. */
+export const TERMINAL_FONT_CHUNK_BYTES = 256 * 1024;
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+/**
+ * A family name ends up inside a CSS `font-family` list in the browser. Quotes,
+ * separators and escapes are what would let a name break out of its slot, and
+ * no real family needs them.
+ */
+const FONT_FAMILY_FORBIDDEN = /["'\\;,{}<>@\u0000-\u001f\u007f]/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isOneOf(list, value) {
+    return list.includes(value);
+}
+function hexColor(value) {
+    return typeof value === 'string' && HEX_COLOR.test(value) ? value.toLowerCase() : undefined;
+}
+/**
+ * Validates a terminal palette crossing the wire.
+ *
+ * The host reports what its own terminal answered to the OSC color queries,
+ * and the browser paints with it. Anything that is not a plain `#rrggbb`
+ * string is dropped here, so a compromised or buggy host cannot push arbitrary
+ * data into a browser's renderer options.
+ */
+export function sanitizeTerminalPalette(value) {
+    if (!isRecord(value))
+        return null;
+    const palette = {};
+    for (const key of ['background', 'foreground', 'cursor']) {
+        const color = hexColor(value[key]);
+        if (color)
+            palette[key] = color;
+    }
+    const ansi = value.ansi;
+    if (isRecord(ansi)) {
+        const collected = {};
+        for (const key of ANSI_PALETTE_KEYS) {
+            const color = hexColor(ansi[key]);
+            if (color)
+                collected[key] = color;
+        }
+        if (Object.keys(collected).length === ANSI_PALETTE_KEYS.length) {
+            palette.ansi = collected;
+        }
+    }
+    return Object.keys(palette).length > 0 ? palette : null;
+}
+function familyName(value) {
+    const family = typeof value === 'string' ? value.trim() : '';
+    if (!family || family.length > 128 || FONT_FAMILY_FORBIDDEN.test(family))
+        return null;
+    return family;
+}
+/**
+ * Validates the terminal font a host reports.
+ *
+ * The browser draws the session in the family the workstation's terminal
+ * uses, and may fetch the font files by their hash. Every field is optional
+ * except the family; anything malformed is dropped rather than repaired.
+ */
+export function sanitizeTerminalFont(value) {
+    if (!isRecord(value))
+        return null;
+    const family = familyName(value.family);
+    if (!family)
+        return null;
+    const size = Number(value.sizePx);
+    const sizePx = Number.isFinite(size) && size >= 4 && size <= 96 ? Math.round(size * 10) / 10 : null;
+    const source = typeof value.source === 'string' && /^[a-z0-9-]{1,32}$/.test(value.source)
+        ? value.source
+        : null;
+    const faces = [];
+    const seen = new Set();
+    for (const face of Array.isArray(value.faces) ? value.faces.slice(0, 16) : []) {
+        if (!isRecord(face))
+            continue;
+        const { style, format, bytes, sha256 } = face;
+        if (!isOneOf(TERMINAL_FONT_STYLES, style) || seen.has(style))
+            continue;
+        if (!isOneOf(TERMINAL_FONT_FORMATS, format))
+            continue;
+        if (typeof bytes !== 'number' || !Number.isInteger(bytes))
+            continue;
+        if (bytes <= 0 || bytes > MAX_TERMINAL_FONT_BYTES)
+            continue;
+        if (typeof sha256 !== 'string' || !SHA256_HEX.test(sha256))
+            continue;
+        seen.add(style);
+        faces.push({ style, format, bytes, sha256 });
+    }
+    // Large fonts (CJK above all) are offered a few characters at a time.
+    const subsets = [];
+    for (const entry of Array.isArray(value.subsets) ? value.subsets.slice(0, 16) : []) {
+        if (!isRecord(entry))
+            continue;
+        const name = familyName(entry.family);
+        const { scope, sha256 } = entry;
+        if (!name || entry.style !== 'regular')
+            continue;
+        if (!isOneOf(TERMINAL_FONT_SUBSET_SCOPES, scope))
+            continue;
+        if (typeof sha256 !== 'string' || !SHA256_HEX.test(sha256))
+            continue;
+        if (subsets.some((known) => known.scope === scope))
+            continue;
+        subsets.push({ family: name, style: 'regular', scope, sha256 });
+    }
+    return {
+        family,
+        ...(sizePx !== null && { sizePx }),
+        ...(source !== null && { source }),
+        faces,
+        subsets,
+    };
+}