@weftjs/warp
The frame protocol: negotiation, frames, and the codec. Also versioned, and for the same reason.
Read out of packages/warp/src/index.ts, the package’s public entry, so this page is the surface itself rather than a description of it.
bool
function
export function bool(f: AnyFrame, key: string): boolean | undefined { … }A header read as a boolean. Absent and malformed are both undefined: a header is text.
Specified inspec/warp/warp-1.md
codeForKind
function
export function codeForKind(kind: FrameKind): number { … }The binary code for a kind. Retired codes are never reused — see spec/VERSIONING.md.
concatBytes
function
export function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array { … }Two buffers as one. A decoder holds a partial frame across chunks and this is how it grows.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
createBinaryDecoder
function
export function createBinaryDecoder(options: DecoderOptions = {}): Decoder { … }The length-prefixed binary decoder. What a socket uses.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
createTextDecoder
function
export function createTextDecoder(options: DecoderOptions = {}): Decoder { … }The newline-delimited text decoder. What an event stream uses, where a frame is a line.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
decodeHeader
function
export function decodeHeader(text: string): Header { … }A header line as names and values, with numbers and booleans parsed back.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
decodeTextFrame
function
export function decodeTextFrame(line: string): AnyFrame { … }One line as a frame. An unknown kind comes back as an unknown frame rather than an error.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
directionOf
function
export function directionOf(kind: FrameKind): Direction { … }Which way this kind travels.
directionOfCode
function
export function directionOfCode(code: number): Direction { … }Which way a code travels, without needing to know the kind it names.
encodeBinaryFrame
function
export function encodeBinaryFrame(f: Frame): Uint8Array { … }One frame as length-prefixed bytes: code, header length, body length, then the two.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
encodeHeader
function
export function encodeHeader(header: Header): string { … }A header as one line. Keys are sorted, so the same header is always the same bytes.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
encodeStream
function
export function encodeStream(frames: Frame[], mode: 'binary' | 'text' = 'binary'): Uint8Array { … }A whole stream, preamble included. What a test and a server both send.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
encodeTextFrame
function
export function encodeTextFrame(f: Frame): string { … }Text framing: one frame per line, for dev tooling and traces. Bodies are encoded into the line, so text framing is not byte-transparent and production uses binary.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
frame
function
export function frame(kind: FrameKind, header: Header = {}, body?: Uint8Array, bodyIsText = false): Frame { … }A frame, with the direction check the kind implies already done.
Specified inspec/kernel/budgets.md
isUnknown
function
export function isUnknown(value: AnyFrame): value is UnknownFrame { … }Whether this frame is one this version does not define.
An unknown frame is skipped intact rather than dropped, which is what makes a minor additive: an older reader passes a newer frame along instead of ending the stream over it.
kindForCode
function
export function kindForCode(code: number): FrameKind | undefined { … }The kind a code names, or nothing — in which case the frame is carried as unknown.
list
function
export function list(f: AnyFrame, key: string): string[] { … }A comma-separated header as a list. Empty when absent, so a caller needs no guard.
Specified inspec/client/adoption.md·spec/compiler/supported-subset.md·spec/ir/template-ir-2.md·spec/warp/warp-1.md
negotiate
function
export function negotiate(hello: ClientHello, server: ServerCapabilities): Negotiation { … }Capability variance, one mechanism: nothing here fails — a missing capability costs a form, a fill, or an animation, never correctness.
Raised in this fileE_WARP_MAJOR
Specified inspec/FINDINGS.md·spec/kernel/transport.md·spec/warp/warp-1.md
num
function
export function num(f: AnyFrame, key: string): number | undefined { … }A header read as a number. Absent and unparseable are both undefined.
Specified inspec/warp/warp-1.md
preamble
function
export function preamble(major = WARP_MAJOR, minor = WARP_MINOR): Uint8Array { … }The eight bytes that open a stream: magic and version, so a wrong stream is refused at once.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
readResident
function
export function readResident(f: Frame): ClientHello { … }A client hello back out of a RESIDENT frame.
Raised in this fileE_WARP_MAJOR
reservedHeader
function
export function reservedHeader(key: string): boolean { … }True for a header key the frame reserved for itself rather than for a slot.
Specified inspec/VERSIONING.md
residentFrame
function
export function residentFrame(hello: ClientHello): Frame { … }A RESIDENT frame from a client hello.
Raised in this fileE_WARP_MAJOR
resumeFrame
function
export function resumeFrame(input: { epoch: string; tpl?: string; since?: number }): Frame { … }A frozen and evicted webview reconnects with the last epoch it committed and the templates it still holds, and the server continues from there rather than restarting.
Raised in this fileE_WARP_MAJOR
str
function
export function str(f: AnyFrame, key: string): string | undefined { … }A header read as text.
warpFrame
function
export function warpFrame(n: Negotiation): Frame { … }The first frame the server sends: versions and strategy, and — since ok/fatal were added — whether anything was settled at all. See spec/kernel/transport.md.
Raised in this fileE_WARP_MAJOR
ClientHello
interface
export interface ClientHello {
warp: string
ir: string
/** Coarse, bucketed digest of held template versions. Never a precise set. */
tpl?: string
forms?: WireForm[]
transport?: Transport
/** Incremental declarative-shadow-DOM parsing, not merely DSD support. */
dsd?: boolean
/** Same-document View Transitions, for committing an epoch without a flash. */
vt?: boolean
/** Service workers. Unavailable in generic WKWebView and suppressed by many in-app browsers. */
sw?: boolean
/** Persistent storage the resident-template set can live in when there is no service worker. */
idb?: boolean
rtt?: number
ect?: string
cpu?: number
engine?: string
caps?: string[]
}What a client announces: its versions, the forms it accepts, and the templates it holds.
Raised in this fileE_WARP_MAJOR
Decoder
interface
export interface Decoder {
push(chunk: Uint8Array): AnyFrame[]
end(): void
peer: { major: number; minor: number } | null
}A streaming decoder: push bytes, take whole frames, and read back what the peer announced.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
DecoderOptions
interface
export interface DecoderOptions {
/** Reject frames travelling the wrong way, which is a protocol violation, not a version gap. */
expect?: 'up' | 'down'
/** Refuse a stream whose preamble announces a different major. */
major?: number
}What a decoder refuses, as opposed to what it cannot read.
Raised in this fileE_BAD_MAGIC·E_EMPTY_FRAME·E_HEADER_TOO_LARGE·E_REPEATED_PREAMBLE·E_TRUNCATED_FRAME·E_WARP_MAJOR·E_WRONG_DIRECTION
Frame
interface
export interface Frame {
kind: FrameKind
header: Header
body?: Uint8Array
/** Set when the body is UTF-8 text rather than opaque bytes. */
bodyIsText?: boolean
}One frame: a kind, a header of names, and an optional body.
Negotiation
interface
export interface Negotiation {
ok: boolean
spec: string
warp: string
ir: string
forms: WireForm[]
/** How this response will be delivered, after the client's transport is taken into account. */
strategy: 'stream' | 'collapse' | 'socket'
/** Who fills an out-of-order hole: the parser, or the ~1 KB filler script. */
fill: 'dsd' | 'script'
commit: 'view-transition' | 'instant'
/** Where a returning client may keep resident templates. */
residency: 'service-worker' | 'indexeddb' | 'http-cache'
/** Whether a severed channel may continue instead of restarting. Webviews get frozen often. */
resumable: boolean
downgrades: string[]
fatal?: string
}What was settled: the versions, the forms, and the strategy both ends agreed on.
Raised in this fileE_WARP_MAJOR
Specified inspec/VERSIONING.md
ServerCapabilities
interface
export interface ServerCapabilities {
warp: string
ir: string
forms: WireForm[]
}What this server can offer, so the intersection is a fact rather than an assumption.
Raised in this fileE_WARP_MAJOR
UnknownFrame
interface
export interface UnknownFrame {
kind: 'UNKNOWN'
code: number
header: Header
body?: Uint8Array
bodyIsText?: boolean
}A frame kind this build does not know. Skippable, which is the whole point of length prefixes.
AnyFrame
type
export type AnyFrame = Frame | UnknownFrameA frame this version understands, or one it does not. Both are carried; only one is read.
Direction
type
export type Direction = 'up' | 'down'Which way a frame kind travels. Declared per kind, so a frame sent the wrong way is refused.
FrameKind
type
export type FrameKind = keyof typeof FRAMESEvery frame this version defines. An unknown code is carried rather than refused.
Header
type
export type Header = Record<string, HeaderValue>A frame's header: names, never content. Whatever is large belongs in the body.
HeaderValue
type
export type HeaderValue = string | number | booleanWhat a header value can be. Everything is text on the wire; these are what it parses back to.
Transport
type
export type Transport = 'stream' | 'buffered' | 'socket' | 'turn'How the document itself reached the client. See spec/warp/warp-1.md: buffered and turn.
Raised in this fileE_WARP_MAJOR
WireForm
type
export type WireForm = 'html' | 'bundle' | 'split' | 'patch' | 'delta' | 'remote'The forms a client may accept. Mirrors the IR's own list, because the wire is the contract.
Raised in this fileE_WARP_MAJOR
FRAME_HEADER_BYTES
const
export const FRAME_HEADER_BYTES = 8The fixed part of a binary frame: code, flags, and the two lengths.
FRAMES
const
export const FRAMES = {
RESIDENT: { code: 0x01, dir: 'up' },
HELD: { code: 0x02, dir: 'up' },
REFRESH: { code: 0x03, dir: 'up' },
/** Stage data for a route, do not paint — at three grains: `tpl`, `at`, `plan`. See `spec/warp/warp-1.md`. */
WARM: { code: 0x04, dir: 'up' },
INTENT: { code: 0x05, dir: 'up' },
RESUME: { code: 0x07, dir: 'up' },
WARP: { code: 0x10, dir: 'down' },
SHELL: { code: 0x11, dir: 'down' },
SLOT: { code: 0x12, dir: 'down' },
HTML: { code: 0x13, dir: 'down' },
TPL: { code: 0x14, dir: 'down' },
DATA: { code: 0x15, dir: 'down' },
DELTA: { code: 0x16, dir: 'down' },
PATCH: { code: 0x17, dir: 'down' },
SIGNAL: { code: 0x18, dir: 'down' },
COMMIT: { code: 0x19, dir: 'down' },
MOD: { code: 0x1a, dir: 'down' },
CSS: { code: 0x1b, dir: 'down' },
STALE: { code: 0x1c, dir: 'down' },
/** The answer to `WARM at=`: what the r
…Codes below 0x10 travel client to server, codes from 0x10 up travel server to client. See spec/warp/warp-1.md.
HELD_ONLY
const
export const HELD_ONLY = '$only'$ is reserved because a HELD frame's headers are slot names. $only means the whole of what the client holds. See spec/warp/warp-1.md.
PREAMBLE_BYTES
const
export const PREAMBLE_BYTES = 8How many bytes open a stream, so a decoder knows when it can start reading.
RETIRED
const
export const RETIRED: readonly { code: number; was: string; until: string }[] = [
{ code: 0x06, was: 'ACK, in the up direction', until: 'warp 1.2.0' },
]Codes that meant something once and are not to be reused — the one version mistake a length prefix can't catch.
Specified inspec/FINDINGS.md·spec/VERSIONING.md
WARP_FORMS
const
export const WARP_FORMS: WireForm[] = ['html', 'bundle', 'split', 'patch', 'delta']No default: this package owns the Warp version, not the IR version. See spec/FINDINGS.md for the bug that happened when it tried to.
Raised in this fileE_WARP_MAJOR
WARP_MAGIC
const
export const WARP_MAGIC = 'WRP1'Binary stream preamble: magic, then the major and minor the sender is speaking.
WARP_MAJOR
const
export const WARP_MAJOR = 1The major. A different one is refused rather than negotiated: majors are wire breaks.
WARP_MINOR
const
export const WARP_MINOR = 8The minor. Additive, so a peer on a lower one skips what it does not know.
WARP_SPEC
const
export const WARP_SPEC = 'weft.warp/1'The protocol name, in every preamble. A different name is a different protocol.
WARP_VERSION
const
export const WARP_VERSION = '1.8.0'The version this build speaks.