@weftjs/client
The runtime: adoption, the signal graph, deltas, epochs, residency and navigation. Every capability is its own entry, so a page pays for what it uses.
Read out of packages/client/src/index.ts, the package’s public entry, so this page is the surface itself rather than a description of it.
adopt
function
export function adopt(options: AdoptOptions): Adopted { … }Adoption, which is the whole bet: no component code runs. See spec/client/adoption.md.
applyDelta
function
export function applyDelta(adopted: Adopted, delta: DeltaPayload): number { … }The delta form, applied: one write per changed value, no region re-projected. See spec/kernel/surgical.md.
Specified inspec/FINDINGS.md·spec/ir/template-ir-2.md
applyPatch
function
export function applyPatch(root: Element, patch: PatchPayload): number { … }Apply a patch and return how many holes it touched. The rung that needs nothing resident.
baseMatches
function
export function baseMatches(held: string, delta: DeltaPayload): boolean { … }Whether a delta's base is the render this client actually holds.
batch
function
export function batch(work: () => void): void { … }Several writes as one notification, so a subscriber sees the end state and not each step.
Specified inspec/client/signals.md·spec/kernel/locus.md
bindDerived
function
export function bindDerived(
decls: readonly ClientDerived[] | undefined,
signals: Record<string, Readable<unknown>> | undefined,
): Record<string, Readable<unknown>> { … }Turns the template's derived table into readables. Only the decls that reach a signal are bound. See spec/client/adoption.md.
collectMarkers
function
export function collectMarkers(root: Element, listRoots: Set<Element>): Comment[] { … }Marker comments in document order, skipping list-hole subtrees. Exported for the same reason elementAt is. See spec/client/adoption.md.
computed
function
export function computed<T>(fn: () => T): Computed<T> { … }A value derived from other values. Lazy: recomputes on read, only after a pull confirms something it reads changed. See spec/client/signals.md.
Specified inspec/client/signals.md
createChannelClient
function
export function createChannelClient(options: ChannelClientOptions): ChannelClient { … }A client over a set of regions. Frames in, applied updates out.
Raised in this fileE_UNKNOWN
Specified inspec/kernel/transport.md
createEpochs
function
export function createEpochs(host?: ViewTransitionHost): Epochs { … }An epoch table. The host is injected so a test can commit without a real view transition.
Specified inspec/kernel/locus.md
createExposure
function
export function createExposure(initial: Record<string, string> = {}): Exposure { … }The table, and why it starts empty. See spec/kernel/composition.md: "The exposed set, routed".
Raised in this fileE_NOT_EXPOSED
createKnown
function
export function createKnown(): Known { … }An empty registry. It answers "what do I know about this URL" and touches nothing else.
createStaging
function
export function createStaging<T>(options: StagingOptions<T>): Staging<T> { … }A staging table. Nothing here touches the DOM; a claim is what a caller paints.
Specified inspec/client/navigation.md
digest
function
export function digest(versions: string[]): string { … }A precise list of held template versions is an identifying surface, so only a prefix of each is advertised. See spec/client/adoption.md.
Raised in this fileE_IDB_BLOCKED
discoverFrame
function
export function discoverFrame(prefix: string): { kind: string; header: Record<string, string> } { … }The frame that asks about a subtree: the design's router.discover('/checkout/*'), on the wire.
effect
function
export function effect(fn: () => void): () => void { … }Runs now, tracking whatever it reads, and again whenever any of it changes. The auto-tracking front door; subscribe is the narrow one.
Specified inspec/client/signals.md
elementAt
function
export function elementAt(
root: Element,
path: number[],
origin: 'container' | 'element',
): Element | undefined { … }A row is addressed relative to itself. Exported because the patch form addresses the DOM the same way. See spec/client/adoption.md.
evaluate
function
export function evaluate(expr: ClientExpr, read: (id: string) => Json | undefined): Json { … }The client half of a derived value. The expression arrived on the wire, so nothing is compiled here and no component runs — evaluating it is a walk over four node shapes, and wrapping that walk in a computed is what makes the result reactive.
Specified inspec/kernel/budgets.md
exposedFrames
function
export function exposedFrames(
exposure: Exposure,
report?: (line: string) => void,
): (frame: { kind: string; header: Record<string, string | number | boolean>; body?: Uint8Array }) => void { … }SIGNAL frames, routed into the exposure table. Through onFrame, not a case in the channel client: a page composing no region shouldn't carry the handler.
Raised in this fileE_NOT_EXPOSED
heldBy
function
export function heldBy(digestValue: string): Set<string> { … }The versions a RESIDENT digest says a client holds. Coarse on purpose: it is a fingerprint.
Raised in this fileE_IDB_BLOCKED
isHeld
function
export function isHeld(held: Set<string>, version: string): boolean { … }Whether that digest covers this version.
Raised in this fileE_IDB_BLOCKED
openResident
function
export async function openResident(): Promise<ResidentStore> { … }Where a resident template lives between visits. IndexedDB rather than a service worker. See spec/client/adoption.md.
Raised in this fileE_IDB_BLOCKED
patchApplies
function
export function patchApplies(held: string, patch: PatchPayload): boolean { … }Whether a patch is addressed to the render this region is actually showing.
patchFrames
function
export function patchFrames(
target: (slot: string) => PatchTarget | undefined,
onPatched?: (slot: string, writes: number, next: string) => void,
): (
frame: { kind: string; header: Record<string, string | number | boolean>; body?: Uint8Array },
applied: { writes: number; refused: { slot: string; reason: string }[] },
) => void { … }The channel handler, registered through onFrame. See spec/kernel/budgets.md.
plainClick
function
export function plainClick(click: ClickFacts): boolean { … }A plain primary click. Anything else belongs to the browser.
planFrames
function
export function planFrames(
known: Known,
onPlan?: (arrival: PlanArrival) => void,
): (frame: { kind: string; header: Record<string, string | number | boolean>; body?: Uint8Array }) => void { … }Discovery's own frame handler, passed to the channel as part of onFrame. See spec/kernel/budgets.md.
rankOf
function
export function rankOf(pattern: string, path: string): number { … }How specifically a pattern matches a path, or -1 for no match. Re-implements the router's specificity rule. See spec/kernel/routing.md.
signal
function
export function signal<T>(initial: T): Signal<T> { … }A value and its edges. Built on the shape of the TC39 Signals proposal so it can be deleted rather than migrated when that ships.
Specified inspec/compiler/supported-subset.md
soleText
function
export function soleText(element: Element): Text { … }The text node a binding owns, created if the render left the element empty.
stagingKey
function
export function stagingKey(href: string, here: string): string { … }The key a staged route is held under: absolute, and without the fragment the server never sees.
textAfter
function
export function textAfter(marker: Comment): Text { … }The value's own text node, created if the value rendered empty.
untrack
function
export function untrack<T>(fn: () => T): T { … }Reads inside fn establish no dependency.
warmFrame
function
export function warmFrame(at: string, epoch: string): { kind: string; header: Record<string, string> } { … }The frame that asks for a route: the design's WARM, at the grain it always described.
Acked
interface
export interface Acked {
intent: string
ok: boolean
epoch?: string
code?: string
detail?: string
}The outcome of an intent this client sent, and whether its epoch survives.
Raised in this fileE_UNKNOWN
Adopted
interface
export interface Adopted {
/** Writes a value into every node the server rendered it into. */
write(binding: string, value: Json): void
target(binding: string): Target | undefined
/** One value can occupy several holes — a quantity is a field, a label, and a flag. */
targets(binding: string): Target[]
/** Per-row bindings for the template's list hole, in document order. */
rows: Adopted[]
/** Component instances, by the binding their hole carries. */
instances: Record<string, Adopted>
template: ClientTemplate
}What was attached, so a caller can detach it again when a region is replaced.
AdoptOptions
interface
export interface AdoptOptions {
root: Element
template: ClientTemplate
resident?: Resident
signals?: Record<string, Readable<unknown>>
onIntent?: (intent: string, event: Event) => void
/**
* `container` — `root`'s element children are the template's top-level nodes, which is
* how a region is adopted. `element` — `root` *is* the template's single top-level
* element, which is how one row of a list is adopted out of its parent's children.
*/
origin?: 'container' | 'element'
/** Set on the instance that has children to hold, and on nothing else. */
frame?: ChildrenFrame | undefined
/** Set only when this pass is filling somebody else's children hole. */
into?: Tables | undefined
}What adoption needs: the template, the values it was rendered with, and where to attach.
Applied
interface
export interface Applied {
/** DOM writes actually performed. A staged frame performs none, which is the point. */
writes: number
staged: string[]
committed: string[]
stale: string[]
templates: string[]
refused: { slot: string; reason: string }[]
errors: { code: string; detail: string }[]
/** Intent outcomes. A failed one names the epoch that was discarded because of it. */
acked: Acked[]
discarded: string[]
/**
* Routes the server answered a stage for, refused or otherwise. Filled by `navFrames`, which is
* navigation's handler rather than this file's — see `onFrame`.
*/
navs: StagedNav[]
}What an arriving frame did to the page — which region, which form, how long.
Raised in this fileE_UNKNOWN
ChannelClient
interface
export interface ChannelClient {
apply(frames: readonly ChannelFrame[]): Promise<Applied>
/** The HELD header the server needs: what this client is showing, per slot. See `spec/warp/warp-1.md`: HELD, `$only`. */
held(options?: { only?: boolean }): Record<string, string | boolean>
/** The INTENT frame to send, and — when `epoch` is given — the client's own guess staged into that epoch first. See `spec/kernel/transport.md`. */
intent(id: string, input: unknown, options?: OptimisticOptions): ChannelFrame
/** Stage a locally-computed change without an intent. A guess with nothing to confirm it. */
stage(epoch: string, slot: string, changed: Record<string, Json>): void
}The client half of the protocol, and deliberately not a transport. Opening a connection is the front door's job.
Raised in this fileE_UNKNOWN
ChannelClientOptions
interface
export interface ChannelClientOptions {
epochs: Epochs
/** Regions this client is holding, by slot name. */
regions(): Region[]
/** A template arrived. Returning is enough; persistence is the resident store's job. */
onTemplate?(template: ClientTemplate): void | Promise<void>
/** A region the server says is stale. The client decides: now, on focus, or never. */
onStale?(slot: string, reason: string): void
/** A frame this build does not route. The extension point a capability that owns a frame kind uses. See `spec/kernel/budgets.md`. */
onFrame?(frame: ChannelFrame, applied: Applied): void
/** Markup for a slot the server could not send a delta for. */
onHtml?(slot: string, html: string, base: string): void
onError?(code: string, detail: string): void
/** An intent came back. Called for both outcomes, because a failure is news too. */
onAck?(ack:
…What the runtime needs to route frames into regions: the regions, and where to apply them.
Raised in this fileE_UNKNOWN
ChannelFrame
interface
export interface ChannelFrame {
kind: FrameKindText
header: Record<string, string | number | boolean>
body?: Uint8Array
}A frame as the client sees it: the kind, its header, and an already-decoded body.
Raised in this fileE_UNKNOWN
ChildrenFrame
interface
export interface ChildrenFrame {
template: ClientTemplate
signals?: Record<string, Readable<unknown>> | undefined
into: Tables
outer?: ChildrenFrame | undefined
}The markup a call site wrote between a component's tags, carried down to the instance that has to hold it. See spec/client/adoption.md.
Claimed
interface
export interface Claimed<T> {
value: T | null
/** `staged` was already resolved, `awaited` had to wait for it, `cold` was never staged. */
how: 'staged' | 'awaited' | 'cold'
}A staged route being taken: the value, and whether it was ready before the click.
ClickFacts
interface
export interface ClickFacts {
/** True for anything but a plain primary click: the reader is asking for a tab, not a page. */
modified?: boolean
button?: number
}What a click is: the modifiers that mean the reader asked the browser, not this framework.
ClientDerived
interface
export interface ClientDerived {
id: string
expr: ClientExpr
}A derived value as an expression tree, which is what travels instead of code.
ClientHole
interface
export interface ClientHole {
index: number
kind: HoleKind
binding: string
path: number[]
attr?: string
anchor?: number
nested?: string
/** For a `component` hole: child prop name to the parent binding that supplies it. */
props?: Record<string, string>
/**
* For a `component` hole: the template holding the markup the call site wrote between the
* tags. It stays in the caller's binding namespace, so nothing about it is renamed.
*/
children?: string
}The client's view of a hole: everything but the bytes, which it already holds.
ClientTemplate
interface
export interface ClientTemplate {
version: string
holes: ClientHole[]
wiring: ClientWiring[]
derived?: ClientDerived[]
}A sealed template as the client receives it: no effects, no provenance, no build metadata.
ClientWiring
interface
export interface ClientWiring {
path: number[]
op: 'text' | 'attr' | 'prop' | 'bool' | 'event' | 'list'
binding: string
attr?: string
event?: string
intent?: string
anchor?: number
}One binding to attach: where it is, what it writes, and which value feeds it.
CommitOptions
interface
export interface CommitOptions {
/** Wrap the commit in a same-document View Transition where the engine has them. */
transition?: boolean
}How to commit: with a view transition where the engine has one, instantly where it does not.
CommitResult
interface
export interface CommitResult {
epoch: string
slots: string[]
writes: number
/** False when the engine has no View Transitions, or when one was not asked for. */
animated: boolean
}What the commit did, and whether the engine animated it.
DeltaPayload
interface
export interface DeltaPayload {
tpl: string
base: string
changed: Record<string, Json>
}A delta as it arrives: the template, the base it applies to, and the changed values.
Epochs
interface
export interface Epochs {
stage(epoch: string, write: Staged): void
commit(epoch: string, options?: CommitOptions): Promise<CommitResult>
discard(epoch: string): number
staged(epoch: string): string[]
readonly open: string[]
}Staged values, committed atomically or discarded. See spec/kernel/transport.md.
Exposure
interface
export interface Exposure {
/** The signal behind an exposed name. Refuses a name the shell did not expose. */
read(name: string): Readable<string>
/** What the shell offers. For a devtools page, and for a region asking what it may have. */
readonly names: string[]
/** The shell's declaration: every exposed name, at the values this page rendered with. Replaces, never merges. */
declare(values: Record<string, string>): void
/** A new value for an exposed name. False for a name outside the declared set — returns rather than throws, deliberately. */
set(name: string, value: string): boolean
}The one channel between a shell and the regions inside it, on the client. See spec/kernel/composition.md: "The exposed set, routed".
Raised in this fileE_NOT_EXPOSED
Known
interface
export interface Known {
/** Record what a PLAN carried. A pattern arriving twice replaces what was held for it. */
learn(routes: readonly KnownRoute[]): void
/** What is known about a URL, by the most specific pattern that matches it. */
route(href: string, here?: string): KnownRoute | undefined
/** Prefixes already asked about, so a second hover over the same subtree asks nothing. */
asked(prefix: string): boolean
ask(prefix: string): void
readonly patterns: string[]
readonly size: number
}What this client has been told about routes it has not been to. Deliberately not a router.
KnownRoute
interface
export interface KnownRoute {
pattern: string
/** The shell template's version. The client's only question is whether it matches its own. */
shell: string
/** Whether that shell is the one this page is in, as the server decided it. */
shared: boolean
slots?: readonly string[]
css?: string
tpl?: readonly string[]
next?: readonly string[]
/** Whether staging this route from the page the client is on is worth the request. See `spec/client/navigation.md`. */
stage?: boolean
}The part of the plan this client did not have, and what it is for. See spec/client/navigation.md: "What the client knows before it asks".
LinkFacts
interface
export interface LinkFacts {
href: string
/** `target`, `rel` and `download` as the markup wrote them. A link that says it leaves is left. */
target?: string
rel?: string
download?: boolean
}What a link is, reduced to what decides whether the framework may answer the click.
OptimisticOptions
interface
export interface OptimisticOptions {
epoch?: string
/** The client's guess, per slot: the values it expects the mutation to produce. */
optimistic?: Record<string, Record<string, Json>>
}What to stage while an intent is in flight, and under which epoch.
Raised in this fileE_UNKNOWN
PatchPayload
interface
export interface PatchPayload {
tpl: string
base: string
/** Holes whose subtree owns its own markers, so this counts anchors the way adoption did. */
opaque: number[][]
writes: PatchWrite[]
}A patch: the markup of the holes that changed, for a client holding no template.
PatchTarget
interface
export interface PatchTarget {
/** The region's root element, which is where every address in the patch starts. */
root: Element
/** The base this region is showing. A patch computed from another one is refused. */
base: string
}Where a patch write lands, resolved against the live DOM.
PatchWrite
interface
export interface PatchWrite {
path: number[]
op: PatchOp
attr?: string
anchor?: number
value?: string
}One hole's new markup, addressed by path rather than by value.
PlanArrival
interface
export interface PlanArrival {
/** What was asked about. Empty for the frame that follows the handshake. */
prefix: string
routes: KnownRoute[]
/** False when the server truncated the answer, so this is not the whole subtree. */
complete: boolean
}What a PLAN frame carried, and which prefix it was answering.
Readable
interface
export interface Readable<T> {
(): T
subscribe(run: Subscriber): () => void
}Anything a wiring entry can bind to: a signal, or a value computed from signals.
Specified inspec/kernel/composition.md
Region
interface
export interface Region {
slot: string
adopted: Adopted
/** The base render this region is currently showing. A delta whose base disagrees is refused. */
base: string
}One live region on this page: what it holds, and what it will accept next.
Raised in this fileE_UNKNOWN
ResidentStore
interface
export interface ResidentStore {
all(): Promise<Resident>
put(template: ClientTemplate): Promise<void>
/** How the set is advertised to the server. Coarse on purpose. */
digest(versions: string[]): string
readonly durable: boolean
}Where templates a client already holds are kept: IndexedDB, then memory, then nothing.
Raised in this fileE_IDB_BLOCKED
Signal
interface
export interface Signal<T> extends Readable<T> {
set(next: T): void
}A readable value that can be written. Writing marks its readers stale and recomputes nothing.
StagedMarkup
interface
export interface StagedMarkup {
slot: string
html: string
/** The render the region will be showing once this is painted. */
base: string
paint(html: string, base: string): void
}A region staged as markup rather than as values, for a form no template can project.
StagedWrite
interface
export interface StagedWrite {
slot: string
adopted: Adopted
delta: DeltaPayload
}A change held for a slot, in one of the two forms a slot's next state can arrive in. See spec/kernel/transport.md.
Staging
interface
export interface Staging<T> {
/** Begin staging, or join the staging already in flight for this URL. Paints nothing. */
stage(url: string): Promise<T | null>
/** The resolved answer, if there is one and it has not expired. Never a stale one. */
ready(url: string): T | undefined
/**
* What a click asks for: the staged answer if it is there, the one in flight if it is not,
* and a null the caller turns into a real navigation if there is neither.
*/
claim(url: string): Promise<Claimed<T>>
state(url: string): StageState
discard(url: string): boolean
clear(): void
/** URLs currently staged, in the order they were staged. */
readonly open: string[]
readonly staged: number
readonly awaited: number
readonly cold: number
}Routes fetched and painted nowhere. An epoch one level up: keyed by URL, capped, claimed by a click.
StagingOptions
interface
export interface StagingOptions<T> {
/** Fetch the route's answer. Given an `AbortSignal` since an evicted or superseded staged route is one nobody will read. */
load(url: string, signal: AbortSignal): Promise<T | null>
/** How many routes may be staged at once. See `spec/client/navigation.md`. */
max?: number
/** How long a resolved answer may be committed after it arrived. See `spec/client/navigation.md`. */
ttlMs?: number
/** Called for an answer dropped without being committed — evicted, expired, discarded. May need to release more than the value itself. */
release?(value: T): void
now?(): number
}What staging needs: how to fetch a route, and how much to keep.
Tables
interface
export interface Tables {
targets: Map<string, Target[]>
rows: Adopted[]
instances: Record<string, Adopted>
}Where an adoption pass files what it finds. Its own, unless it is filling somebody's children.
Types
11ClientExpr
type
export type ClientExpr =
| { k: 'ref'; id: string }
| { k: 'lit'; v: Json }
| { k: 'un'; op: string; a: ClientExpr }
| { k: 'bin'; op: string; a: ClientExpr; b: ClientExpr }
| { k: 'cond'; a: ClientExpr; b: ClientExpr; c: ClientExpr }The client's mirror of the IR's derived-expression encoding.
Computed
type
export type Computed<T> = Readable<T>A value derived from others. Readable, never writable — the expression is the definition.
FrameKindText
type
export type FrameKindText = stringThe client half of the channel. See spec/kernel/transport.md: "Epochs, over the wire".
Raised in this fileE_UNKNOWN
HoleKind
type
export type HoleKind =
| 'text'
| 'attr'
| 'attr-bool'
| 'attr-presence'
| 'node'
| 'list'
| 'slot'
| 'component'
| 'children'
/**
* Not an IR hole kind: the shape `locate` uses when a wiring entry's op is `prop`. The
* server rendered an attribute; the client writes the property behind it.
*/
| 'prop'The hole kinds a client has to understand. Fewer than the server's: it never cuts a document.
Json
type
export type Json = string | number | boolean | null | Json[] | { [k: string]: Json }What a value can be, mirroring the IR's own type — the client holds templates as data.
PatchOp
type
export type PatchOp = 'text' | 'markup' | 'replace' | 'append' | 'truncate' | 'attr' | 'bool' | 'presence'The patch form, applied — the DOM and nothing else, no binding table needed. See spec/kernel/surgical.md.
Resident
type
export type Resident = Record<string, ClientTemplate>Templates the client holds, by version. A TPL frame adds to this.
Staged
type
export type Staged = StagedWrite | StagedMarkupOne staged change: a value write, or markup for a whole region.
Specified inspec/client/navigation.md
StageState
type
export type StageState = 'none' | 'fetching' | 'ready' | 'failed'A route fetched, resolved, and painting nothing — an epoch, one level up. See spec/client/navigation.md.
Subscriber
type
export type Subscriber = () => voidSomething to run when a value it read has changed.
Target
type
export type Target =
| { kind: 'text'; node: Text }
| { kind: 'attr'; element: Element; attr: string }
| { kind: 'bool'; element: Element; attr: string }
/** A control's live state, which stops agreeing with its attribute once a user edits it. */
| { kind: 'prop'; element: Element; attr: string }What one wiring entry writes to: a text node, an attribute, a property, or an event.
DEFAULT_STAGING
const
export const DEFAULT_STAGING: Required<Pick<StagingOptions<unknown>, 'max' | 'ttlMs'>> = {
max: 4,
ttlMs: 30_000,
}How many routes are held staged, and for how long. A staged route nobody clicks is memory.