weft
ir 2.6.0 · warp 1.8.0
generatedwalked out of the package's public entry

@weftjs/ir

The sealed template format and the one rendering function. Versioned, because a wire format cannot be versioned retroactively.

110exports
110with a doc comment on the declaration

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

packages/ir/src/version.ts

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

packages/ir/src/render.ts

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

packages/ir/src/render.ts

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

packages/ir/src/validate.ts

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.

packages/ir/src/hash.ts

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

packages/ir/src/render.ts

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

packages/ir/src/effects.ts

canonicalJson function

export function canonicalJson(value: Json | undefined): string { … }

Deterministic JSON: object keys sorted, so a hash is stable across emitters.

packages/ir/src/hash.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/version.ts

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.

packages/ir/src/derived.ts

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

packages/ir/src/serialize.ts

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

packages/ir/src/version.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/render.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/template-ir.ts

draftTemplate function

export function draftTemplate(t: DraftTemplate): TemplateIR { … }

An unsealed template: everything but the content-addressed version.

Raised in this fileE_NESTED_UNRESOLVED

packages/ir/src/template-ir.ts

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

packages/ir/src/render.ts

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

packages/ir/src/render.ts

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

packages/ir/src/derived.ts

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

packages/ir/src/effects.ts

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.

packages/ir/src/hash.ts

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

packages/ir/src/effects.ts

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

packages/ir/src/serialize.ts

isStatic function

export function isStatic(effects: EffectSet): boolean { … }

Reads nothing, so its key is its content address and it could be a file.

packages/ir/src/effects.ts

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

packages/ir/src/render.ts

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

packages/ir/src/effects.ts

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

packages/ir/src/version.ts

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

packages/ir/src/serialize.ts

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

packages/ir/src/version.ts

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

packages/ir/src/patch.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/derived.ts

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

packages/ir/src/version.ts

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

packages/ir/src/render.ts

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

packages/ir/src/render.ts

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

packages/ir/src/render.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/render.ts

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

packages/ir/src/render.ts

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

packages/ir/src/effects.ts

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

packages/ir/src/version.ts

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.

packages/ir/src/derived.ts

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

packages/ir/src/incremental.ts

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.

packages/ir/src/hash.ts

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

packages/ir/src/incremental.ts

short function

export function short(hash: string, n = 6): string { … }

A hash shortened for a log or a report. Never for a key.

packages/ir/src/hash.ts

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

packages/ir/src/serialize.ts

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.

packages/ir/src/hash.ts

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.

packages/ir/src/hash.ts

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

packages/ir/src/serialize.ts

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.

packages/ir/src/effects.ts

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

packages/ir/src/validate.ts

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

packages/ir/src/render.ts

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

packages/ir/src/effects.ts

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

packages/ir/src/validate.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/serialize.ts

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

packages/ir/src/template-ir.ts

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.

packages/ir/src/derived.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/validate.ts

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

packages/ir/src/serialize.ts

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

packages/ir/src/patch.ts

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

packages/ir/src/patch.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/incremental.ts

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

packages/ir/src/version.ts

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

packages/ir/src/serialize.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/validate.ts

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

packages/ir/src/template-ir.ts

AcceptMode 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

packages/ir/src/version.ts

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

packages/ir/src/version.ts

BinaryOp type

export type BinaryOp =
  '+' | '-' | '*' | '/' | '%' | '**' | '<' | '>' | '<=' | '>=' | '===' | '!==' | '==' | '!='

The binary operators a derived expression may use. Also closed, and for the same reason.

packages/ir/src/derived.ts

BindingId type

export type BindingId = string

A value's name inside a template. Holes and wiring entries both address values by it.

Raised in this fileE_NESTED_UNRESOLVED

packages/ir/src/template-ir.ts

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.

packages/ir/src/effects.ts

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.

packages/ir/src/derived.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/version.ts

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

packages/ir/src/patch.ts

Resolver type

export type Resolver = (version: string) => TemplateIR | undefined

Resolves 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

packages/ir/src/render.ts

UnaryOp type

export type UnaryOp = '!' | '-' | '+' | '~'

The unary operators a derived expression may use. A closed set, because the client evaluates it.

packages/ir/src/derived.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/template-ir.ts

BINARY_OPS const

export const BINARY_OPS: readonly BinaryOp[] = [
  '+',
  '-',
  '*',
  '/',
  '%',
  '**',
  '<',
  '>',
  '<=',
  '>=',
  '===',
  '!==',
  '==',
  '!=',
]

Every binary operator, for the validator.

packages/ir/src/derived.ts

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

packages/ir/src/template-ir.ts

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

packages/ir/src/version.ts

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

packages/ir/src/version.ts

renderHtml const

export const renderHtml = render

render 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

packages/ir/src/render.ts

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

packages/ir/src/version.ts

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

packages/ir/src/version.ts

UNARY_OPS const

export const UNARY_OPS: readonly UnaryOp[] = ['!', '-', '+', '~']

Every unary operator, for the validator.

packages/ir/src/derived.ts