@weftjs/ir
The sealed template format and the one rendering function. Versioned, because a wire format cannot be versioned retroactively.
Read out of packages/ir/src/index.ts, the package’s public entry, so this page is the surface itself rather than a description of it.
accepts
function
export function accepts(
doc: { spec?: unknown; irVersion?: unknown },
reader = {
spec: TEMPLATE_IR_SPEC,
version: TEMPLATE_IR_VERSION,
},
): AcceptResult { … }The compatibility contract. Major is a hard wire break; minor is additive. See spec/VERSIONING.md.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
applyDelta
function
export function applyDelta(base: Values, delta: DeltaPayload, ir?: TemplateIR, resolve?: Resolver): Values { … }Applies a path-keyed delta (rows[3].qty) onto a base value set, inverting projections given a template. See spec/ir/template-ir-2.md.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
Specified inspec/FINDINGS.md·spec/ir/template-ir-2.md
assertSameTemplate
function
export function assertSameTemplate(ir: TemplateIR, payload: { tpl: string }): void { … }A delta is only applicable to the template version it was computed against.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
assertValidTemplate
function
export function assertValidTemplate(ir: TemplateIR): TemplateIR { … }The same rules as a gate. A validator that accepted an invalid document would be a spec bug.
Raised in this fileE_ANCHOR_KIND·E_ANCHOR_OP·E_ANCHOR_SHAPE·E_CHILDREN_KIND·E_CHILDREN_SHAPE·E_COMPONENT_NESTED·E_COMPONENT_PROPS·E_DERIVED_DUPLICATE·E_DERIVED_EXPR·E_DERIVED_FORWARD_READ·E_DERIVED_ID·E_FORM_FLOOR·E_FORM_UNPROVABLE·E_HOLE_ATTR·E_HOLE_BINDING·E_HOLE_INDEX·E_ID_MISSING·E_ISOLATED_KIND·E_NESTED_KIND·E_NESTED_SHAPE·E_PATH_SHAPE·E_PROPS_KIND·E_RAW_UNVOUCHED·E_RESIDENCY·E_SEGMENT_COUNT·E_VERSION_MISMATCH·E_VERSION_SHAPE·E_VERSION_UNSEALED·E_WIRING_ATTR·E_WIRING_EVENT·E_WIRING_INTENT·E_WIRING_UNKNOWN_BINDING
baseRenderId
function
export function baseRenderId(ir: TemplateIR, values: Values): string { … }The content address of one render, which is what a client names when it asks for a delta.
byteLength
function
export function byteLength(
ir: TemplateIR,
supplied: Values,
resolve?: Resolver,
frame?: ChildrenFrame,
): number { … }How many bytes a render would produce, without producing them.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
cacheClassOf
function
export function cacheClassOf(effects: EffectSet): CacheClass { … }Everything about cacheability is derived from what a render read, never declared by an author.
Specified inspec/compiler/effects.md·spec/kernel/cache.md·spec/kernel/composition.md
canonicalJson
function
export function canonicalJson(value: Json | undefined): string { … }Deterministic JSON: object keys sorted, so a hash is stable across emitters.
changedBindings
function
export function changedBindings(prev: Values, next: Values): Set<BindingId> { … }Top-level bindings whose values differ. Canonical JSON, so key order is not a change.
Raised in this fileE_NESTED_UNRESOLVED
childrenFrame
function
export function childrenFrame(
hole: Hole,
values: Values,
resolve: ((version: string) => TemplateIR | undefined) | undefined,
outer: ChildrenFrame | undefined,
): ChildrenFrame | undefined { … }The frame a component hole opens for its instance: absent when the call site wrote none.
Raised in this fileE_NESTED_UNRESOLVED
clearMigrations
function
export function clearMigrations(): void { … }Drops every registered step. For tests: a migration table that leaks between them proves nothing.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
clientOwned
function
export function clientOwned(
decls: readonly DerivedDecl[],
signals: readonly { id: BindingId }[],
): Set<BindingId> { … }The derived ids the client owns: those that reach a signal, directly or through another derived value. See spec/ir/template-ir-2.md.
clientView
function
export function clientView(ir: TemplateIR): ClientView { … }The template as a client needs it, and no more. See spec/ir/template-ir-2.md.
Raised in this fileE_ENCODING_UNSUPPORTED·E_INVALID_DOCUMENT·E_NOT_A_DOCUMENT
Specified inspec/ir/template-ir-2.md
compareVersions
function
export function compareVersions(a: string, b: string): number { … }Negative, zero or positive, by major then minor then patch.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
componentValues
function
export function componentValues(hole: Hole, values: Values): Values { … }The values a component instance is rendered with. A missing prop is null rather than absent, so the child renders a hole, not "undefined".
Raised in this fileE_NESTED_UNRESOLVED
concat
function
export function concat(parts: Uint8Array[]): Uint8Array { … }Several buffers as one.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
createSegmentMemo
function
export function createSegmentMemo(options: SegmentMemoOptions = {}): SegmentMemo { … }A content-addressed memo over nested templates — list rows and component instances. See spec/kernel/surgical.md.
Raised in this fileE_NESTED_UNRESOLVED
deltaPayload
function
export function deltaPayload(
ir: TemplateIR,
base: string,
prev: Values,
next: Values,
resolve?: (version: string) => TemplateIR | undefined,
): DeltaPayload { … }The delta between two value sets for one template. See spec/kernel/surgical.md: a pure function of two content-addressed states.
Raised in this fileE_NESTED_UNRESOLVED
derivableForms
function
export function derivableForms(holes: Hole[]): WireForm[] { … }Which wire forms this template can serve, derived rather than declared. See spec/ir/template-ir-2.md.
Raised in this fileE_NESTED_UNRESOLVED
Specified inspec/kernel/surgical.md
derivedPlan
function
export function derivedPlan(decls: readonly DerivedDecl[]): DerivedPlan { … }Which derived values a change can reach, computed once per template rather than per render. See spec/kernel/surgical.md.
Raised in this fileE_NESTED_UNRESOLVED
Specified inspec/kernel/surgical.md
diffValues
function
export function diffValues(prev: Values, next: Values, prefix = ''): Values { … }Path-keyed diff (rows[3].qty). A length change is structural and sends the list whole. See spec/ir/template-ir-2.md.
Raised in this fileE_NESTED_UNRESOLVED
draftTemplate
function
export function draftTemplate(t: DraftTemplate): TemplateIR { … }An unsealed template: everything but the content-addressed version.
Raised in this fileE_NESTED_UNRESOLVED
escapeBytes
function
export function escapeBytes(s: string, attr: boolean): Uint8Array { … }Escapes only when a scan proves it necessary — the runtime half of escape elision. See spec/ir/template-ir-2.md.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
escapeString
function
export function escapeString(s: string, attr: boolean): string { … }HTML-escape, with the attribute rules where they differ. Called only when a scan proved it necessary.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
evalDerived
function
export function evalDerived(expr: DerivedExpr, read: (id: BindingId) => Json | undefined): Json { … }Total: a binding that is not there reads as null rather than throwing. See spec/ir/template-ir-2.md.
Specified inspec/FINDINGS.md·spec/kernel/budgets.md
explain
function
export function explain(effects: EffectSet): string { … }A one-line account of why a fragment is cacheable the way it is.
Specified inspec/compiler/effects.md
fastHash
function
export function fastHash(input: string): string { … }FNV-1a over two 32-bit lanes. Used only where a collision is cheap. See spec/ir/template-ir-2.md.
flagAxes
function
export function flagAxes(effects: EffectSet): string[] { … }Flag axes partition the graph, so they are listed separately from the key.
Specified inspec/compiler/effects.md
fromJSON
function
export function fromJSON(input: unknown): ParseResult { … }A plain object back to a template, applying whatever migrations the version needs.
Raised in this fileE_ENCODING_UNSUPPORTED·E_INVALID_DOCUMENT·E_NOT_A_DOCUMENT
isStatic
function
export function isStatic(effects: EffectSet): boolean { … }Reads nothing, so its key is its content address and it could be a file.
isTruthy
function
export function isTruthy(v: Json | undefined): boolean { … }Whether a boolean or presence attribute is written at all.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
keyComponents
function
export function keyComponents(effects: EffectSet): string[] { … }The reads a cache key has to include the *values* of. See spec/kernel/cache.md.
Specified inspec/FINDINGS.md·spec/compiler/effects.md·spec/kernel/cache.md
migrate
function
export function migrate(
doc: Record<string, unknown>,
target = TEMPLATE_IR_VERSION,
): { doc: Record<string, unknown>; applied: string[] } { … }Chains registered migrations until the document reaches the reader's version.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
Specified inspec/VERSIONING.md
parse
function
export function parse(text: string): ParseResult { … }Text back to a template.
Raised in this fileE_ENCODING_UNSUPPORTED·E_INVALID_DOCUMENT·E_NOT_A_DOCUMENT
Specified inspec/VERSIONING.md
parseVersion
function
export function parseVersion(v: string): SemVer { … }A version string as numbers. Refuses anything that is not major.minor.patch.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
patchPayload
function
export function patchPayload(
ir: TemplateIR,
base: string,
prev: Values,
next: Values,
resolve?: (version: string) => TemplateIR | undefined,
): PatchPayload { … }What changed between two renders of one template, as writes into the DOM the first one produced.
Raised in this fileE_PATCH_UNADDRESSABLE
Specified inspec/kernel/surgical.md
rawValue
function
export function rawValue(h: Hole): boolean { … }A hole whose *value* is markup: raw(). The nested kinds are trusted-raw as well and are not this case — their markup comes from a template, which is what makes it addressable.
Raised in this fileE_NESTED_UNRESOLVED
readsOf
function
export function readsOf(expr: DerivedExpr, out: BindingId[] = []): BindingId[] { … }Every binding the expression reads, in first-seen order and without duplicates.
Specified inspec/compiler/supported-subset.md·spec/ir/template-ir-2.md
registerMigration
function
export function registerMigration(from: string, to: string, run: Migration): void { … }Register a step from one minor to the next. Refuses a step that does not go forward, or crosses a major.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
Specified inspec/VERSIONING.md
render
function
export function render(ir: TemplateIR, values: Values, resolve?: Resolver): Uint8Array { … }The one rendering function, called by both server (html) and client (data) — what makes the two provably equal. See spec/kernel/surgical.md.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
Specified inspec/FINDINGS.md·spec/ir/template-ir-2.md·spec/kernel/ports.md·spec/kernel/surgical.md
renderHole
function
export function renderHole(hole: Hole, value: Json | undefined, resolve?: Resolver): Uint8Array { … }One hole's bytes, for a consumer that walks a template itself rather than rendering it. See spec/ir/template-ir-2.md.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
Specified inspec/ir/template-ir-2.md
renderHoleIn
function
export function renderHoleIn(
hole: Hole,
values: Values,
resolve?: Resolver,
frame?: ChildrenFrame,
): Uint8Array { … }One hole's bytes, given the template's **whole** value set — unlike renderHole, this also handles component, variant and children holes. See spec/ir/template-ir-2.md. The values must already have been through resolveDerived; a caller that walks the template owns that step.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
Specified inspec/ir/template-ir-2.md
renderIncremental
function
export function renderIncremental(input: IncrementalInput): IncrementalRender { … }A render that consults the memo for nested templates and recomputes only reachable derived values. Byte-identical to render(), gated.
Raised in this fileE_NESTED_UNRESOLVED
renderInto
function
export function renderInto(
ir: TemplateIR,
values: Values,
out: Uint8Array,
offset = 0,
resolve?: Resolver,
): number { … }Writes into a caller-owned buffer and returns the byte count. Throws OVERFLOW if it does not fit.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
renderSubtree
function
export function renderSubtree(
ir: TemplateIR,
index: number,
supplied: Values,
resolve?: Resolver,
): Uint8Array { … }The markup one hole produced, including a nested template's. What the patch form sends and compares.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
requiresTtl
function
export function requiresTtl(effects: EffectSet): boolean { … }Reading the clock forces a TTL: a cache policy without one would never expire.
Specified inspec/compiler/effects.md·spec/kernel/cache.md·spec/kernel/composition.md
resetMigrations
function
export function resetMigrations(): void { … }Clears test-local migrations and puts the built-in chain back.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
resolveDerived
function
export function resolveDerived(decls: readonly DerivedDecl[], values: Values): Values { … }Fills every derived binding into the value set, in declaration order. Always recomputed, never trusted from a reused value set.
resolveDerivedFrom
function
export function resolveDerivedFrom(
plan: DerivedPlan,
previousResolved: Values,
next: Values,
changed: ReadonlySet<BindingId>,
): IncrementalDerived { … }Resolve derived values against a previous resolved set. Identical to a full resolveDerived, gated by a fixture.
Raised in this fileE_NESTED_UNRESOLVED
Specified inspec/kernel/surgical.md
seal
function
export async function seal(ir: TemplateIR): Promise<TemplateIR> { … }Stamp a template with a hash of its own content. After this, its version *is* its identity.
segmentKey
function
export function segmentKey(tpl: string, values: Values): string { … }The content address of a rendered nested template. Pure function in, pure function out.
Raised in this fileE_NESTED_UNRESOLVED
Specified inspec/kernel/surgical.md
short
function
export function short(hash: string, n = 6): string { … }A hash shortened for a log or a report. Never for a key.
stringify
function
export function stringify(ir: TemplateIR, forward?: Record<string, Json>): string { … }A template as text. Keys are ordered, so the same template is always the same bytes.
Raised in this fileE_ENCODING_UNSUPPORTED·E_INVALID_DOCUMENT·E_NOT_A_DOCUMENT
Specified inspec/VERSIONING.md
templateFingerprint
function
export function templateFingerprint(ir: TemplateIR): Uint8Array { … }The bytes a template version is a hash of. meta is excluded on purpose. See spec/ir/template-ir-2.md.
templateVersion
function
export async function templateVersion(ir: TemplateIR): Promise<string> { … }Template versions get a real digest: SHA-256 truncated to 128 bits. See spec/ir/template-ir-2.md.
toJSON
function
export function toJSON(ir: TemplateIR, forward: Record<string, Json> = {}): SerializedTemplate { … }A template as a plain object. forward carries fields a newer reader added, unchanged.
Raised in this fileE_ENCODING_UNSUPPORTED·E_INVALID_DOCUMENT·E_NOT_A_DOCUMENT
unionEffects
function
export function unionEffects(sets: readonly EffectSet[]): EffectSet { … }What a fragment reads includes what the fragments it renders read. See spec/compiler/effects.md.
validateTemplate
function
export function validateTemplate(ir: TemplateIR): ValidationResult { … }Every structural rule, against one template. Returns findings rather than throwing.
Raised in this fileE_ANCHOR_KIND·E_ANCHOR_OP·E_ANCHOR_SHAPE·E_CHILDREN_KIND·E_CHILDREN_SHAPE·E_COMPONENT_NESTED·E_COMPONENT_PROPS·E_DERIVED_DUPLICATE·E_DERIVED_EXPR·E_DERIVED_FORWARD_READ·E_DERIVED_ID·E_FORM_FLOOR·E_FORM_UNPROVABLE·E_HOLE_ATTR·E_HOLE_BINDING·E_HOLE_INDEX·E_ID_MISSING·E_ISOLATED_KIND·E_NESTED_KIND·E_NESTED_SHAPE·E_PATH_SHAPE·E_PROPS_KIND·E_RAW_UNVOUCHED·E_RESIDENCY·E_SEGMENT_COUNT·E_VERSION_MISMATCH·E_VERSION_SHAPE·E_VERSION_UNSEALED·E_WIRING_ATTR·E_WIRING_EVENT·E_WIRING_INTENT·E_WIRING_UNKNOWN_BINDING
valueText
function
export function valueText(v: Json | undefined): string { … }The text a value contributes, before escaping. Exported for a consumer writing through a DOM API — the patch form's writes.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
varyOn
function
export function varyOn(effects: EffectSet): string[] { … }A shared response keyed by a request value has to say so, or a CDN will serve it to everyone.
Specified inspec/compiler/effects.md·spec/kernel/cache.md·spec/kernel/composition.md
verifySealed
function
export async function verifySealed(ir: TemplateIR): Promise<ValidationResult> { … }Confirms the content address actually addresses this content.
Raised in this fileE_ANCHOR_KIND·E_ANCHOR_OP·E_ANCHOR_SHAPE·E_CHILDREN_KIND·E_CHILDREN_SHAPE·E_COMPONENT_NESTED·E_COMPONENT_PROPS·E_DERIVED_DUPLICATE·E_DERIVED_EXPR·E_DERIVED_FORWARD_READ·E_DERIVED_ID·E_FORM_FLOOR·E_FORM_UNPROVABLE·E_HOLE_ATTR·E_HOLE_BINDING·E_HOLE_INDEX·E_ID_MISSING·E_ISOLATED_KIND·E_NESTED_KIND·E_NESTED_SHAPE·E_PATH_SHAPE·E_PROPS_KIND·E_RAW_UNVOUCHED·E_RESIDENCY·E_SEGMENT_COUNT·E_VERSION_MISMATCH·E_VERSION_SHAPE·E_VERSION_UNSEALED·E_WIRING_ATTR·E_WIRING_EVENT·E_WIRING_INTENT·E_WIRING_UNKNOWN_BINDING
ChildrenFrame
interface
export interface ChildrenFrame {
ir: TemplateIR
values: Values
outer?: ChildrenFrame
}The markup a call site wrote between a component's tags, and the value set it reads. A frame, not a hole value — see spec/ir/template-ir-2.md.
Raised in this fileE_NESTED_UNRESOLVED
ClientView
interface
export interface ClientView {
version: string
holes: Hole[]
wiring: WiringEntry[]
derived: DerivedDecl[]
}What a TPL frame carries: addressing and wiring, deliberately not the segments or the effect set. See spec/ir/template-ir-2.md.
Raised in this fileE_ENCODING_UNSUPPORTED·E_INVALID_DOCUMENT·E_NOT_A_DOCUMENT
DeltaPayload
interface
export interface DeltaPayload {
spec: typeof PAYLOAD_SPEC
irVersion: string
form: 'delta'
tpl: string
base: string
changed: Values
}The changed values of a region, against the base render the client says it holds.
Raised in this fileE_NESTED_UNRESOLVED
DerivedDecl
interface
export interface DerivedDecl {
id: BindingId
expr: DerivedExpr
}A value computed from other bindings, as a tree rather than as code — no closure on the wire, no hydration to recompute.
DerivedPlan
interface
export interface DerivedPlan {
/** Derived ids to recompute, in declaration order, for a given set of changed bindings. */
affectedBy(changed: ReadonlySet<BindingId>): BindingId[]
readonly order: readonly DerivedDecl[]
}// ── level two: derived values ────────────────────────────────────────────────────────
Raised in this fileE_NESTED_UNRESOLVED
DraftTemplate
interface
export interface DraftTemplate {
id: string
segments: (Uint8Array | string)[]
holes: Hole[]
wiring?: WiringEntry[]
signals?: SignalDecl[]
derived?: DerivedDecl[]
forms?: WireForm[]
effects?: EffectSet
meta?: Record<string, Json>
}A template before it is sealed. seal fills in the version, which is why that is absent here.
Raised in this fileE_NESTED_UNRESOLVED
EffectSet
interface
export interface EffectSet {
reads: string[]
writes: string[]
envelope: string[]
residency: 'server' | 'client' | 'either'
}What a fragment reads, writes and does to the envelope, inferred by the compiler. See spec/kernel/cache.md.
Raised in this fileE_NESTED_UNRESOLVED
Hole
interface
export interface Hole {
index: number
kind: HoleKind
escape: EscapeClass
binding: BindingId
path: number[]
attr?: string
provenance?: string
/** For `list`: the version items project through. For `component`/`variant`: the version rendered/written. See `spec/ir/template-ir-2.md`. */
nested?: string
/** For `component`/`variant`: child prop name to the parent binding that supplies it. See `spec/ir/template-ir-2.md`. */
props?: Record<string, BindingId>
/** For `component`: the template version holding the markup the call site wrote between the tags. See `spec/ir/template-ir-2.md`. */
children?: string
/** For `component`: the instance is its own cache unit and the parent does not render it. See `spec/ir/template-ir-2.md`. */
isolated?: boolean
/** For `list`: the binding each item is supplied as, when a row interpolates the item itself. See `sp
…One gap in a sealed template: what fills it, how it escapes, and where it is in the DOM.
Raised in this fileE_NESTED_UNRESOLVED
IncrementalDerived
interface
export interface IncrementalDerived {
values: Values
recomputed: BindingId[]
reused: BindingId[]
}Which derived values a recompute could skip, because nothing they read changed.
Raised in this fileE_NESTED_UNRESOLVED
IncrementalInput
interface
export interface IncrementalInput {
ir: TemplateIR
values: Values
memo: SegmentMemo
resolve?: Resolver
/** The previous render's resolved values, for level two. Without one every derived value is recomputed. */
previous?: { resolved: Values; supplied: Values }
/** Precomputed dependency graph. Built from `ir.derived` when absent. */
plan?: DerivedPlan
}The previous values and the memo, which is everything an incremental render needs extra.
Raised in this fileE_NESTED_UNRESOLVED
IncrementalRender
interface
export interface IncrementalRender {
bytes: Uint8Array
stats: IncrementalStats
/** The resolved value set, so the next round has a previous to compare against. */
resolved: Values
}The bytes, plus how many nested templates were reused rather than rendered.
Raised in this fileE_NESTED_UNRESOLVED
IncrementalStats
interface
export interface IncrementalStats {
/** Nested templates served from the memo, and rendered. */
segments: { reused: number; rendered: number }
derived: { reused: number; recomputed: number }
/** Holes whose shape changed rather than whose values did. See `spec/kernel/surgical.md`. */
structural: string[]
}// ── level three: template segments ───────────────────────────────────────────────────
Raised in this fileE_NESTED_UNRESOLVED
IrError
interface
export interface IrError {
code: string
at: string
message: string
}One thing wrong with a document: the code, where it is, and a sentence.
Raised in this fileE_ANCHOR_KIND·E_ANCHOR_OP·E_ANCHOR_SHAPE·E_CHILDREN_KIND·E_CHILDREN_SHAPE·E_COMPONENT_NESTED·E_COMPONENT_PROPS·E_DERIVED_DUPLICATE·E_DERIVED_EXPR·E_DERIVED_FORWARD_READ·E_DERIVED_ID·E_FORM_FLOOR·E_FORM_UNPROVABLE·E_HOLE_ATTR·E_HOLE_BINDING·E_HOLE_INDEX·E_ID_MISSING·E_ISOLATED_KIND·E_NESTED_KIND·E_NESTED_SHAPE·E_PATH_SHAPE·E_PROPS_KIND·E_RAW_UNVOUCHED·E_RESIDENCY·E_SEGMENT_COUNT·E_VERSION_MISMATCH·E_VERSION_SHAPE·E_VERSION_UNSEALED·E_WIRING_ATTR·E_WIRING_EVENT·E_WIRING_INTENT·E_WIRING_UNKNOWN_BINDING
ParseResult
interface
export interface ParseResult {
ir: TemplateIR
/** Fields a newer minor added. Kept so a re-emit does not silently drop them. */
forward: Record<string, Json>
migrationsApplied: string[]
mode: 'exact' | 'upgrade' | 'forward'
}A parsed document, plus how it was accepted — exact, migrated, or read forward.
Raised in this fileE_ENCODING_UNSUPPORTED·E_INVALID_DOCUMENT·E_NOT_A_DOCUMENT
PatchPayload
interface
export interface PatchPayload {
spec: typeof PAYLOAD_SPEC
irVersion: string
form: 'patch'
tpl: string
base: string
/** Paths of the holes whose subtree owns its own markers, so a client with no template arrives at the same ordinals. */
opaque: number[][]
writes: PatchWrite[]
}A patch: the markup of the holes that changed, and nothing about the ones that did not.
Raised in this fileE_PATCH_UNADDRESSABLE
PatchWrite
interface
export interface PatchWrite {
/** Element children only, from the region root — the address adoption already walks. */
path: number[]
op: PatchOp
attr?: string
/** Marker ordinal, for a text hole that is not the only child of its element. */
anchor?: number
/** Absent means remove: a boolean that went false, or a presence attribute with no value. */
value?: string
}One hole's markup, addressed by path — the rung that needs no resident template.
Raised in this fileE_PATCH_UNADDRESSABLE
SegmentMemo
interface
export interface SegmentMemo {
get(key: string): Uint8Array | undefined
set(key: string, bytes: Uint8Array): void
readonly hits: number
readonly misses: number
readonly size: number
}The design's second and third memoisation levels — opt-in, per-slot. See spec/kernel/surgical.md.
Raised in this fileE_NESTED_UNRESOLVED
SegmentMemoOptions
interface
export interface SegmentMemoOptions {
/** Bytes. An unbounded memo inside a 128 MB isolate is an outage waiting for traffic. */
maxBytes?: number
}How much of the memo to keep, which is a memory-for-renders trade and nothing else.
Raised in this fileE_NESTED_UNRESOLVED
SemVer
interface
export interface SemVer {
major: number
minor: number
patch: number
}A parsed version. Nothing here compares versions as strings, because 2.10 sorts wrong.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
SerializedTemplate
interface
export interface SerializedTemplate {
spec: string
irVersion: string
id: string
version: string
encoding: 'base64'
segments: string[]
holes: Json
wiring: Json
signals: Json
derived: Json
forms: Json
effects: Json
meta?: Json
[k: string]: Json | undefined
}A sealed template as JSON: segments base64, everything else as written.
Raised in this fileE_ENCODING_UNSUPPORTED·E_INVALID_DOCUMENT·E_NOT_A_DOCUMENT
SignalDecl
interface
export interface SignalDecl {
id: BindingId
type: 'string' | 'number' | 'boolean' | 'json'
init?: Json
}Client-owned state the server renders at its initial value and then stops owning.
Raised in this fileE_NESTED_UNRESOLVED
TemplateIR
interface
export interface TemplateIR {
spec: typeof TEMPLATE_IR_SPEC
irVersion: string
id: string
version: string
segments: Uint8Array[]
holes: Hole[]
wiring: WiringEntry[]
signals: SignalDecl[]
/** Values computed from other bindings. See `spec/ir/template-ir-2.md`: ownership follows the reads. */
derived: DerivedDecl[]
forms: WireForm[]
effects: EffectSet
meta?: Record<string, Json>
}A sealed template: pre-encoded UTF-8 segments with holes between them, and a version that is a hash of its own content. See spec/ir/template-ir-2.md.
Raised in this fileE_NESTED_UNRESOLVED
ValidationResult
interface
export interface ValidationResult {
ok: boolean
errors: IrError[]
}Whether a document is valid, and everything wrong with it if not.
Raised in this fileE_ANCHOR_KIND·E_ANCHOR_OP·E_ANCHOR_SHAPE·E_CHILDREN_KIND·E_CHILDREN_SHAPE·E_COMPONENT_NESTED·E_COMPONENT_PROPS·E_DERIVED_DUPLICATE·E_DERIVED_EXPR·E_DERIVED_FORWARD_READ·E_DERIVED_ID·E_FORM_FLOOR·E_FORM_UNPROVABLE·E_HOLE_ATTR·E_HOLE_BINDING·E_HOLE_INDEX·E_ID_MISSING·E_ISOLATED_KIND·E_NESTED_KIND·E_NESTED_SHAPE·E_PATH_SHAPE·E_PROPS_KIND·E_RAW_UNVOUCHED·E_RESIDENCY·E_SEGMENT_COUNT·E_VERSION_MISMATCH·E_VERSION_SHAPE·E_VERSION_UNSEALED·E_WIRING_ATTR·E_WIRING_EVENT·E_WIRING_INTENT·E_WIRING_UNKNOWN_BINDING
WiringEntry
interface
export interface WiringEntry {
/**
* Indices into *element* children, not childNodes. Element positions do not move
* when a text value renders empty, so an element path is stable across value sets.
*/
path: number[]
op: WiringOp
/** Unused for `event` ops, which name an intent instead. */
binding: BindingId
attr?: string
event?: string
intent?: string
/** For `text`: the ordinal of the marker comment this binding writes after. Absent means the only text child. */
anchor?: number
}One binding the client attaches on adoption. The cost model is the number of these.
Raised in this fileE_NESTED_UNRESOLVED
Types
16AcceptMode
type
export type AcceptMode = 'exact' | 'upgrade' | 'forward'How a document was accepted: unchanged, migrated up, or read as-is by a newer reader. See spec/VERSIONING.md.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
AcceptResult
type
export type AcceptResult =
| { ok: true; mode: AcceptMode; from: string; to: string }
| { ok: false; code: 'E_SPEC_MISMATCH' | 'E_MAJOR_UNSUPPORTED' | 'E_VERSION_MALFORMED'; reason: string }Whether this reader can read that document, and if not, which refusal applies.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
BinaryOp
type
export type BinaryOp =
'+' | '-' | '*' | '/' | '%' | '**' | '<' | '>' | '<=' | '>=' | '===' | '!==' | '==' | '!='The binary operators a derived expression may use. Also closed, and for the same reason.
BindingId
type
export type BindingId = stringA value's name inside a template. Holes and wiring entries both address values by it.
Raised in this fileE_NESTED_UNRESOLVED
CacheClass
type
export type CacheClass = 'static' | 'shared' | 'private'What a read set makes a fragment. Derived, never declared — a class you can assert is one you can assert wrongly.
DerivedExpr
type
export type DerivedExpr =
| { k: 'ref'; id: BindingId }
| { k: 'lit'; v: Json }
| { k: 'un'; op: UnaryOp; a: DerivedExpr }
| { k: 'bin'; op: BinaryOp; a: DerivedExpr; b: DerivedExpr }
/** A choice between two values — `a ? b : c`, with `a ?? b` and `a || b` lowered to it. See `spec/ir/template-ir-2.md`. */
| { k: 'cond'; a: DerivedExpr; b: DerivedExpr; c: DerivedExpr }A computed value, encoded rather than compiled to a function. See spec/ir/template-ir-2.md.
EscapeClass
type
export type EscapeClass = 'escape' | 'proven-safe' | 'trusted-raw'The compiler's escape-elision decision. trusted-raw must name its provenance. See spec/ir/template-ir-2.md.
Raised in this fileE_NESTED_UNRESOLVED
HoleKind
type
export type HoleKind =
| 'text'
| 'attr'
| 'attr-bool'
| 'attr-presence'
| 'node'
| 'list'
| 'slot'
| 'component'
| 'children'
/** A shape that renders only when its binding is truthy. See `spec/ir/template-ir-2.md`. */
| 'variant'What a hole is, which decides who produces its bytes. See spec/ir/template-ir-2.md.
Raised in this fileE_NESTED_UNRESOLVED
Json
type
export type Json = string | number | boolean | null | Json[] | { [k: string]: Json }What can be a hole's value. A template is data, so its values have to be data too.
Raised in this fileE_NESTED_UNRESOLVED
Migration
type
export type Migration = (doc: Record<string, unknown>) => Record<string, unknown>One version step. Pure: it takes a document and returns the next one, and never mutates.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
PatchOp
type
export type PatchOp =
/** Write text into a text node: `.data`, so what travels is unescaped. */
| 'text'
/** Replace an element's children with parsed markup: a raw value, or a call site's children. */
| 'markup'
/** Replace the element itself: a component instance, or one row of a list. */
| 'replace'
/** Add rows to the end of a list. */
| 'append'
/** Drop the rows past `value` from a list. */
| 'truncate'
| 'attr'
| 'bool'
| 'presence'The rung between delta and html, and the one the ladder was missing. See spec/kernel/surgical.md.
Raised in this fileE_PATCH_UNADDRESSABLE
Resolver
type
export type Resolver = (version: string) => TemplateIR | undefinedResolves a nested template by version, which is how a list of fragments is projected.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
UnaryOp
type
export type UnaryOp = '!' | '-' | '+' | '~'The unary operators a derived expression may use. A closed set, because the client evaluates it.
Values
type
export type Values = Record<BindingId, Json>One render's values, by binding. Everything a template needs that is not in its segments.
Raised in this fileE_NESTED_UNRESOLVED
WireForm
type
export type WireForm = 'html' | 'bundle' | 'split' | 'patch' | 'delta' | 'remote'How a fragment's update can be encoded. Every form must produce identical bytes. See spec/ir/template-ir-2.md.
Raised in this fileE_NESTED_UNRESOLVED
WiringOp
type
export type WiringOp = 'text' | 'attr' | 'prop' | 'bool' | 'event' | 'list'What a binding writes. prop exists because an attribute and a live value stop agreeing once somebody types.
Raised in this fileE_NESTED_UNRESOLVED
ALL_FORMS
const
export const ALL_FORMS: readonly WireForm[] = ['html', 'bundle', 'split', 'patch', 'delta', 'remote']Every form, in the order the spec lists them. A template declares the subset it can serve.
Raised in this fileE_NESTED_UNRESOLVED
BINARY_OPS
const
export const BINARY_OPS: readonly BinaryOp[] = [
'+',
'-',
'*',
'/',
'%',
'**',
'<',
'>',
'<=',
'>=',
'===',
'!==',
'==',
'!=',
]Every binary operator, for the validator.
EMPTY_EFFECTS
const
export const EMPTY_EFFECTS: EffectSet = { reads: [], writes: [], envelope: [], residency: 'server' }Reads nothing. server rather than either because a fixture is not a claim about residency.
Raised in this fileE_NESTED_UNRESOLVED
PAYLOAD_SPEC
const
export const PAYLOAD_SPEC = 'weft.payload/2'The format name for a delta or patch payload, versioned separately from the template.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
PAYLOAD_VERSION
const
export const PAYLOAD_VERSION = '2.6.0'The payload version this build writes.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
renderHtml
const
export const renderHtml = renderrender under the name the html wire form goes by, so a form table can name all of them.
Raised in this fileE_DELTA_NOT_INVERTIBLE·E_DELTA_PATH·E_NESTED_UNRESOLVED·E_TPL_MISMATCH
TEMPLATE_IR_SPEC
const
export const TEMPLATE_IR_SPEC = 'weft.template-ir/2'The format name, carried in every document. A different name is a different format, not a version.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
TEMPLATE_IR_VERSION
const
export const TEMPLATE_IR_VERSION = '2.6.0'The version this build writes. Minors are forward-compatible; a major is refused.
Raised in this fileE_MAJOR_UNSUPPORTED·E_MIGRATION_CYCLE·E_MIGRATION_DIRECTION·E_MIGRATION_MAJOR·E_MIGRATION_MISSING·E_SPEC_MISMATCH·E_VERSION_MALFORMED
Specified inspec/FINDINGS.md
UNARY_OPS
const
export const UNARY_OPS: readonly UnaryOp[] = ['!', '-', '+', '~']Every unary operator, for the validator.