Reference

Changelog

What changed in each release, newest first. Every version has its own address, such as /changelog#6.0.0.

7.1.1

#7.1.1

Not released yet

A fix to the language server.

  • Arabic in a splice no longer crashes the server. Finding a name's

uses reads every string of the project for the name in its {…} splices, and it read them a byte at a time: a letter outside ASCII — any Arabic, which the docs site is full of — ended the server. It reads them by character now, and a name's edges are any script's letters, so in {أname} the Arabic letter belongs to the name.

  • The VS Code and Zed extensions fetch wf-lsp 7.1.1.

7.1.0

#7.1.0

Latest

18 November 2026

A project's components documented as the reference documents the built-ins, each drawn live; editors that know all of 7.0, and a script's functions followed into the pages that call them; and every prop of every built-in said in full.

`example`, and `wf docs` in the reference's design

2

  • example Component "what it shows" { … } shows one way to use a component. Its body is a page's — elements, state, handlers, stores — checked as a page is (a component nothing declares is E101, a wrong value T01), formatted by wf fmt, and left out of every build. A /// above it is the words beside it; fakes: answers what it calls.

  • wf docs writes a site, in the design of the official reference — its theme, its fonts, Night and Day. A page a component: its /// comment and header, every example drawn live in a frame of the project's own build (its theme, stylesheets and scripts) beside its source, then its props with their types, what each is when left out and each prop's ///, its events, slots and parts, and what places it. The types, stores and pages have pages of their own. A component with no example is drawn from its props.

Editors

3

  • Your own scripts. In a .js file under src/, each function, class or value it declares says where the project uses it: a lens (Used 3 times in WebFluent), find-references that reach the pages calling it, a hover naming them, a faded hint on what nothing uses, and a rename — from the script or from a page — that changes the declaration and every call. VS Code leaves the script to its TypeScript service and draws the lenses over it; Zed attaches the server to JavaScript.

  • The language server knows all of 7.0: middleware, fake and example in the outline, go-to-definition, references, rename, completion and hover; a tests/ file read with its project; an api group's endpoints; browser globals and their members; toast, ask, announce and http; t("key") goes to the key and $token to the theme; its snippets write what 7.0 checks.

  • The grammars (Tree-sitter, Zed, VS Code) parse and colour example, middleware, fake and the service words, read w / 2 + h / 2 as division and {key: value} in prose as text, and know Json. The extensions fetch wf-lsp 7.1.0.

The reference

2

  • Every prop of every built-in says what it does, what it is when left out, and what each of its cases means — one table that the docs, wf registry --json and the editor's hover all read.

  • The design tokens page says what each token is for and which built-ins draw from it; the configuration page names every setting.

Fixes

7

  • A Dropdown's first argument is its label; a Button(to:) navigates without a stray href; .rounded is rounder corners, not a pill; an outlined secondary, success, warning or info button is coloured.

  • A .closable dialog with no title still has its close button; a sheet opens at its first snap point, and one that may not be dismissed cannot be dragged shut.

  • A multiple Select binds every choice; a NumberInput is held to its min: and max:; a Combobox search answered by an endpoint shows its list.

  • direction: .column turns a Row; a Tabs.Page's .disabled and a Stepper.Step's .done and .error flags are read; Sticky(bottom: true) sticks to the bottom; a Carousel's autoplay: may follow state; a hand-written Callout.Title is the only title.

  • Stat with no format: writes its value as format does; Image keeps the loading: it is given; landscape: false is portrait.

  • format(value) shows text that is not a number as it is.

  • A Grid of more than twelve columns, and a value per breakpoint on a prop that is not a layout's, are T01.

7.0.1

#7.0.1

17 November 2026

Fixes found by reading every page of the guide against 7.0 and building its examples, and the three open issues.

Tests act as a reader can

4

  • A step acts only on what a reader can reach. click, type and press pass over a control in a closed Sheet or Modal, a hidden branch or anything under inert, and take the first one a reader meets. Two a reader could mean fail the step and say so, and a name that only something hidden carries says that too.

  • expect reads what is drawn above the page: an open dialog, such as the one ask(…) draws, and the toasts.

  • A page and a component may each have an async action of one name. A component's pending now belongs to each instance, so two cards side by side no longer join each other's calls, and a test page no longer stops on Identifier '_begin_pending' has already been declared.

  • An error a fake answers with carries the message the network's would, and a read over a faked endpoint fails with it rather than [object Object].

The runtime and the checker

5

  • Host(tag: "svg") is an SVG element, live and in the static paint, so what a script draws in it paints.

  • A match on a stream no longer throws: a stream has a closure, and its .messages and on message(m) hold what it declares it receives.

  • after and every take a Duration — after(3.seconds) — as the guide shows.

  • A13 checks the dark theme as well as the site's. The spa starter's dark theme and the tutorials' now name a label colour that clears it.

  • A state read only as a persist's key: is not reported unused, and N08 no longer suggests window.fetch, which the checker refuses.

Docs, the agent reference and the skill

Every page outside the Learn chapters already reviewed — the reference, the recipes, the about and coming-from pages, the Arabic pages and every error page — was read against 7.0 and its examples built and run, and so were AGENTS.md and the writing-webfluent skill that wf init writes into a project. Pages that still taught Any, Map, fetch, the 6.x read arms or gradual typing are rewritten; the grammar reference covers the service, type and test syntax; the skill covers the request contract, fakes, wf api add, wf migrate and the theme's tokens. The installers suggest pinning v7.0.1, and the editor follows a YAML OpenAPI spec.

7.0.0

#7.0.0

17 November 2026

7.0 is strict, and a request is a contract. Every value has a type the program can name — Any and Map are gone, signatures are declared, nothing converts by itself — and there is no setting that turns any of it off. A service is described once, from its OpenAPI spec if it has one; a call answers with a result that says how it failed; a read is one value with three cases; and a test answers the service with a fake. wf migrate carries a 6.x project across.

`Any` and `Map` leave the language

3

  • Any written as a type is T23, Map is T24, each with a fix that writes Json. A record (type Price { … }) or a dictionary ([String: Number]) says more, where you know it; Json is JSON whose shape is open, matched or decoded before it is read. wf migrate writes Json where that leaves the project with fewer errors, and leaves the T24 of a Map read as a record for a person, who names its type.

  • No place a type is unknown. The docs site and every example check with none (wf types --holes reads zero), and a test holds them to it. Getting there typed more of the language: an empty list beside ?? is the type on its other side (result?.items ?? []); two enum cases from an if are the enum wanted (if c { .open } else { .all }); pop, shift, at, unshift and indexOf are typed; groupBy is a dictionary of lists; File.text() is a promise of text; a JSDoc method ({{ stop(): void }}) is a function; a library's global takes and gives Json; and an argument left out (sort()) is not a value of unknown type.

  • A let's type is held to what any written type is: let cells: [Any] is T23.

A write is sent again only when that is safe

2

  • A retry policy now retries only a request that may be sent twice: GET, HEAD, PUT and DELETE. A POST or PATCH that timed out may have reached the server, and three more of them could be three more orders; it now fails as .timeout.

  • With offline.sync, only a PUT or a DELETE made with no network is kept and sent later. A POST or a PATCH fails as .offline, and the page decides what to do.

Requests that never went, or went wrong

7

  • A resource's body: and headers: are read on every load: typing into the field a search body reads asks again. They were read once, as the page drew.

  • Two readers of one address make one request whether or not a cache policy is set. Each keeps its own abort, and the request stops when the last of them leaves.

  • Backend.users.invalidate() refreshes every resource on the page over that endpoint, and Backend.invalidate() every one over the service. It used to drop the cache and leave the screen as it was.

  • A call's own headers: and retry: were sent in the query string (?headers=[object Object]); they are the request's again.

  • A File parameter is sent under its own name: post avatar(image: File) sends image, where it used to need the name file.

  • Two uploads of different files at once are two calls. An async action called again with the same arguments joins the call already running, and every File looked the same.

  • A store's await fetch("/x/{id}") encodes id as a page's does.

What the checker now says

5

  • match e { .status(code, body) { … } } on a resource's error binds the status and the body. It was T13, nothing declares code.

  • An endpoint call is a promise of its result until it is awaited (T17).

  • A parameter with no default that may not be null must be given (C01).

  • resource u: [User] = Backend.user(…) is T01 when the endpoint returns User.

  • A resource has reload(), invalidate(), loadMore() and cancel(); rows.relaod() is T16.

Types a program can write

7

  • Dictionaries, [K: V]: keys of String or an enum, values of V. Reading a key gives a V?; keys(), values(), entries(), has(k), with(k, v) and without(k) are its methods. A dictionary is a plain object at run time.

  • Function types, (A, B) -> R, with () for nothing: a prop that takes a lambda says what it takes, and a lambda handed to it is held to it. Hover and messages now write an action's type this way, (String) -> (), where they wrote action(String).

  • Aliases, type Scores = [String: Number].

  • -> T on an action: what it returns, held at every return and seen by every caller. A lambda's parameter may say its type, (a: User) => ….

  • Json, the language's own enum for JSON as it arrives — .object, .array, .string, .number, .bool, .null — written Json.string("x") and read by match. A JSON value is plain at run time.

  • T.decode(json) on every declared record, enum and alias: the value checked against the type as the page runs, in every build. It is a result, T ! DecodeError — .ok(value), or .err(e) with e.at (where) and e.message (what).

  • Results, T ! E and T!, matched by .ok and .err; an action may declare -> T ! E, -> ! E or -> !.

A call that fails says how

8

  • An endpoint declared -> T ! E or -> T! returns a result, .ok(value) or .err(error), and never throws. E is an error enum: a case for each status the service answers with, unprocessableContent(problem: ValidationProblem) on 422, carrying that status's body, and one http(error: HttpError) case for everything else (N12 holds an enum that names a status to that shape).

  • HttpError and Problem are built in: what goes wrong between the page and the server — .offline, .timeout(limit), .cancelled, .transport(message), .decode(at, message), .status(code, problem), each with .message — and a server's account of a failure as RFC 9457 has it.

  • try gives a result's value, or returns its error from the action as the action's own (N03 where the action cannot hold it). In a handler it reports the failure.

  • An action declaring -> T ! E returns its value, which is .ok of it, or return .err(e); -> ! E and -> ! return nothing and may fail. Its .result is its last outcome.

  • Patterns: _, a literal, and a case inside a case — .err(.http(.status(503, _))) — in a match, which now runs inside an action or a handler too, and in if let .err(e) = outcome.

  • An action that returns a value says what with -> T (T26, an error; wf fix --code T26 writes the type).

  • Under wf serve, the body of each status an error enum names is held to the type its case carries, as a success is held to -> T.

  • An action that shows a change with optimistic(…) and declares -> ! takes the change back when a try in it passes a failure up, and is .ok when nothing did.

Asking with `http`

http is the built-in service for a request no api describes: http.get(url), http.post(url, body: value), http.put, http.patch and http.delete, through the same engine an api uses. Each is a promise of a result, T!, its error an HttpError, and T is named where the answer goes:

type Row { id: String }
type Me { name: String }

store Account {
    state page = 1
    state name = ""
    resource rows: [Row] = http.get("/api/rows?page={page}")
    action load() -> ! {
        let me: Me = try await http.get("/api/me")
        name = me.name
    }
}

as: .text answers with a String; headers:, timeout:, retry:, cache: and credentials: are the request's own.

What 7.0 refuses

4

Every one has a fix, and wf fix applies those that are mechanical.

  • fetch(…) is N08. It threw on a failure the page rarely caught, and its answer was Any. A resource or a call with no method: is rewritten to http.get(…); a write becomes http.post(…) (or put, …) by hand. window.fetch is still the browser's own.

  • An endpoint that does not say how it fails, -> T, is N08: it is now -> T!, which the fix writes. An errors { 422 -> T } block is N08 too: name the status in an error enum, unprocessableContent(problem: T) on 422, and write -> T ! ThatError.

  • Any and Map where a service meets the program — an endpoint's parameter or answer, a resource's annotation — and an http.get whose answer has no type are N11. Declare a type, or name Json for JSON whose shape is open; the fix writes Json.

  • An endpoint read from an OpenAPI file answers with a result, T!, and a failure's body arrives in the HttpError's .status(code, problem).

The browser, events and the built-ins, typed

6

What a program reaches without declaring it now has a type the checker knows, so a slip is found where it is written rather than in a reader's browser.

  • The browser. window, document, localStorage, JSON, Math, navigator, location, the timers and the plain functions are typed by a table the checker, the editor and wf types read: JSON.parse hands back Json, localStorage.getItem a String?, setTimeout takes a function and milliseconds. A global or a member the table does not list is T30, with the nearest name — Math.florr → floor — and anything it leaves out is reached from a project script whose JSDoc says its types.

  • Events. on keydown(e) is a KeyboardEvent, on click(e) a MouseEvent, and so on through the DOM's events; target is an Element. The gestures hand over what they say (on swipe(s)'s s.direction), and a dragged value arrives as Json.

  • Handles. A ref: is an Element (focus(), value, scrollIntoView(), …). A connection is typed by its send and receive, Json where it names neither, so chat.sned(m) is found.

  • catch e is an Error — name, message, stack — whatever was thrown: the runtime wraps a string, a number or a plain object a script throws in one.

  • The language's own values. env is a record of the names the build knows (env.PUBLIC_APII is T05), query is [String: String], a page's params a record of its own route parameters, locale and dir Strings, and a form's errors [String: String].

  • The built-ins' props. The 72 that took anything now each say what they take: Portal(into: Element?), AspectRatio(ratio: Number), Text(String or Number or Bool), Calendar(disabled: [Date] or (Date) -> Bool). A built-in that shows a list types its other props, its parts and its slots by one of its items: a DataTable's key: r => r.id, a column's value: r => r.nmae (T05), a cell(r). wf registry --json and the docs show these types.

A read is one value

5

A resource was a string, state, beside data, error and refreshing, which a page had to keep in step itself — and could read in combinations that never happen. It is now one value with three cases:

match users {
    .loading { Skeleton(height: "20px") }
    .failed(e) { Alert(e.message).danger }                 // e: HttpError, or the endpoint's error enum
    .loaded(list, refreshing, stale) {
        if refreshing { Spinner.sm }
        if stale != null { Alert("Could not refresh").warning }
        for u in list by u.id { Text(u.name) }
    }
}
  • "Loaded, and the last refresh failed" is .loaded(value, false, e); "loading, with data" cannot be written. A match covers every case or says else: one with no .failed arm is T21, now an error, and one missing another case T15. if let .failed(e) = users { … } takes one case, and a match expression reads one too.

  • A failure is what .err holds for the same request — an HttpError, or the endpoint's error enum for one declared -> T ! E — not 6.x's loose error object.

  • To read one fact, a read has members worked out from its value, which cannot disagree with it: value (T?), isLoading, isLoaded, isFailed, isRefreshing, error (E?) and pending.

  • refresh: says when a read asks again besides an argument changing: .onReconnect — what a read now does when it says nothing — .onFocus, .every(30.seconds), .never, or a list.

  • placeholder: .previous keeps the last value shown, refreshing, while another request of it loads — a search whose results stay while the next ones arrive — where a changed request used to go back to loading.

6.x's forms are N08, and wf fix rewrites them: the loading, error(e) and ready(v) arms become .loading, .failed(e) and .loaded(v); .data becomes .value and .refreshing .isRefreshing; on: .focus, .reconnect and .interval(d) become refresh: .onFocus, .onReconnect and .every(d). .state has no one rewrite: compare with isLoading, isLoaded or isFailed, or match the read. A .failed(e) arm that read 6.x's e.status or e.body matches the HttpError instead: .status(code, problem).

What a request passes through

5

  • Middleware replaces a service's headers { } and its on request, on response and on error hooks with one mechanism: middleware [ refreshOn401(Session.refresh), bearer(Session.token), requestId ], steps run in the order written, each around the next. The runtime's are bearer, header, refreshOn401, requestId and log; a project writes its own as middleware name(req, next) { … }, typed by what a middleware is. Three requests that hear 401 at once share one refresh, since a running action is joined. The old forms are N08.

  • The cache follows the server (RFC 9111, a private cache): a GET is kept only when Cache-Control or Expires allows, for its max-age less its Age, stale within stale-while-revalidate, revalidated with ETag, never under no-store, kept apart by Vary and the credentials. With no caching headers nothing is kept — before, an endpoint kept what its cache: said whatever the server answered. cache: .maxAge(d), .swr(d), .none and .forever still override it.

  • Every answer is checked, in every build: what an endpoint or a resource declares it returns is held to what arrives, deployed as under wf serve, and a server that breaks its contract fails as .decode(at, message).

  • idempotent on an endpoint — post order(body: Order) at "orders" -> Order! idempotent — sends one Idempotency-Key with every try of a call, and lets a POST or PATCH be retried and replayed offline; retry: on any other write is N09, and does nothing.

  • A call gives up after 30 seconds unless its service or the call says otherwise.

Contracts and writes

7

  • at is required, and a path names its parameters as OpenAPI does: get user(id: String) at "users/{id}" -> User!. Every {name} is one of the endpoint's parameters (N01). 6.x made a path from the endpoint's name when it gave none, and wrote a parameter :id; both are N08, and wf fix writes at "<name>" and {id}.

  • Headers and cookies. token: String in header "X-Token" and theme: String? in cookie say where a parameter goes; one the path names has no other place. A specification's "in": "header" and "in": "cookie" are read the same way.

  • Groups. api Backend.todos { … } splits a service's endpoints by what they are about, reached as Backend.todos.list(). A group sends what its service sends; its own base:, retry: or middleware is N08.

  • What a write makes stale. invalidates [list, byId(id)] on a write names the reads of its group it changes, each argument one of the write's own parameters (N05). When the write succeeds, every resource over one of them asks again and draws the answer in place.

  • A change shown before the server agrees. A read's .update(change) changes what every resource over it shows, and returns what takes the change back: let undo = Backend.todos.list.update(…), then undo() when the write fails.

  • The first parameter may be passed without its name: Backend.user("7").

  • A resource is over a read: one over a POST, PUT, PATCH or DELETE would send it again each time the page draws, and is N02. A call's result awaited on its own, so that a failure is never heard, is N04.

Declared where others see it, inferred where only the body does

7

What another declaration, another file or a caller sees is now declared, and what only the body sees is still inferred — so the checker never has to work one declaration out to check another.

  • Order no longer matters. A store's derived values were typed in the order they were written, and a store reading one declared further down was refused (T13). Each is now worked out after what it reads, wherever that is, so moving a declaration never changes a type. Two that read each other with neither declared are T35.

  • A state says what it holds when its first value does not: state items = [], state picked = null, persist prefs = {} and open JSON are T25, and the fix writes the type the body assigns — items = items.concat([Todo(…)]) gives state items: [Todo] = [].

  • A parameter says its type: an action's, an event's and a slot's (T32, whose fix writes what every call passes), and a lambda's when nothing it is passed to says it — derived byName = (a: User, b: User) => ….

  • A script's JSDoc is its signature. A function called from .wf with none is T31, and the fix writes a block from the call; a union or a bare Array is T31 too. {*} is Json, {Object<string, T>} is [String: T], {HTMLElement} is Element, a function with no @returns gives nothing back, and a class is a type whose members are its JSDoc'd methods.

  • @typedef is a type. /** @typedef {{ id: string, done?: boolean }} Row */ in a script is a record the program names: state rows: [Row] = [].

  • What a script returns is checked, in every build. A call of a function whose @returns names a type is held to it as it returns or settles, and a mismatch throws a DecodeError naming the function — so a value typed Row is a Row, under wf serve and deployed alike.

  • A parameter or state may name what the browser hands a program — action run(e: KeyboardEvent), node: Element — and now(every: …) is a DateTime, as now is.

A value is what it says

6

Agreement is now exact: nothing is converted on the way, and nothing two things could be at once is accepted as either.

  • A map is a record's field by field. A map kept in a state and later given as a User is checked as a literal written there is: a field the record lacks is T05, a required one left out C01, one of the wrong type T01. { ...todo, done: true } is a Todo again.

  • One value, one type (T27). if ok { 1 } else { "none" }, [1, "a"] and day ?? "none" with day: Date? have no type in common, and are refused where they meet instead of becoming a value the checker cannot name. null on one side still makes the value T?.

  • A condition is a Bool (T29). if count, show name, !count and user || fallback are refused; the fix writes what each asks — count != 0, name != "", count == 0, user ?? fallback. A Bool? is a condition, its null false.

  • No conversions (T34, T18). A Date, a Time or a DateTime is shown through a splice that says how — Text("{due:.date(long)}"), not Text(due); a Duration and a Number are not added (3.seconds + 500.ms), though a duration is scaled by a number; "Total: " + n is "Total: {n}". A Url, an Email, a Color and a Uuid are strings wherever text is wanted.

  • Json is matched or decoded (T28). raw.name, raw[0], raw + 1 and raw.keys() assume what nobody checked; User.decode(raw) checks it. A connection that receives something says so — receive Message — and on message(m) is then one.

  • Input(…).time and .datetime hold a Time and a DateTime.

Data from outside, held to its type where it comes in

4

What the program did not write is checked against the type that receives it, at the boundary, and refused with the place it goes wrong (T33) rather than shown wrong, or as nothing, further in.

  • A data file at build time. data posts: [Post] = "posts.json" holds the file to [Post] when the project is built: ` posts.json is not what data posts says it is: $[3].date is "March 5", not a Date `. Dates, times, addresses and colours are read for what they are.

  • A template's data before it renders. A page that declares parameters beside its route's — page Invoice(path: "/", number: String, customer: Customer, items: [Line]) — takes those: wf render, Template::render_* and the Node binding refuse data that does not fit ($.items[1].price is missing), and a name the page reads that it does not declare is T13. A page that declares no parameters reads its data by name, as before.

  • A test's seeds before it runs. data: { count: "two" } for a state count = 0 is T33, and a store member the store does not have is T05.

  • A persist value as it is read back. What storage holds is held to the value's type; a value an older build left in another shape is dropped for the initial value, with a warning in a development build, and the page loads.

Pages, lines, and writes kept offline

6

How an endpoint answers more than once is written in its contract, once.

  • Pages. pages .number(param: page), pages .cursor(param: after, next: p => p.nextCursor, items: p => p.posts) or pages .link (the answer's Link header, RFC 8288). A read of it holds every page's items, typed, with .items, .hasMore and .loadMore(); the read keeps the page itself and writes no state of the page's. A refresh asks again for every page gathered, in order, and shows them together.

  • Lines. get tail(id: String) at "logs/{id}" -> [LogLine]! streamed: a read over it is .loaded from its first line and grows; awaited whole it is every line; for await line in Logs.tail(id: id) in an action or a handler walks them as they arrive. Each line is held to its type, and the request goes through the service's middleware, timeout and retries.

  • A write kept offline says so. Its call used to resolve with nothing while the checker said User; it now fails .offline(queued: true), so the page knows no answer came. HttpError's .offline carries queued.

  • What happens to it later. Once sent, what its endpoint invalidates asks again — on the page that sends it, or on every open page when the service worker does. One the server refuses is never sent again and is listed in network.refused ({ method, url, status, at }) until network.clearRefused().

  • N14 refuses a pages or streamed that cannot work: on a write, a page parameter the endpoint lacks or the first call must give, a cursor with no next:, a page that is not a list with no items:, a streamed answer that is not a list, and for await over anything but a streamed call.

  • paginate: on a call is N08. Its .items, .hasMore and .loadMore() stay; pages .number(param: page) moves to the endpoint, and the state page the runtime used to write goes.

Fakes: a service answered in a test

6

A test of a page that reads a service no longer needs the service.

  • fake OneUser for Backend.users { list(page) { .ok([…]) } } answers a group's endpoints (or a service's own) in place of the network. Each answer names the endpoint and the parameters it reads, by the names the endpoint gives them, and gives the endpoint's result — .ok(value) or .err(error), picked by an if or a match from what the call sent.

  • Held to the contract (N06). An endpoint the group does not have, a parameter it does not take, an answer of the wrong type, an endpoint answered twice; a test's fakes: naming no fake or two that answer one endpoint; an expect called naming no endpoint.

  • test "…"(fakes: [OneUser]) { … } runs in a browser with those fakes answering. Nothing is sent: a write's invalidates asks its reads again, as after a real success, and a call to an endpoint no fake answers fails the test, naming it. A paged endpoint is answered a page at a time; a streamed one with the whole list, a line at a time.

  • expect called Backend.users.create and expect not called … check whether the page asked an endpoint.

  • wf verify --fakes tests/fakes.wf builds the site aside with that file's fakes answering its endpoints, and loads every page of that build. A build never carries fakes.

  • A read in wf render data. { "users": { "loaded": [ … ] } } paints a resource users' .loaded arm (and { "failed": … } its .failed arm), its members reading the same; a declared type holds the value (T33). A static page still paints .loading.

A service's contract, written from its OpenAPI spec

8

wf api writes a service's contract as files from its OpenAPI spec, where it can be read, reviewed and diffed.

  • wf api add openapi.json --name Backend records the service in the config's new apis, writes src/api/backend/service.wf once (yours: the base, the timeout, middleware), marks the generated folder in .gitattributes, and writes generated/: types.wf and one file a tag.

  • wf api sync rewrites generated/ whole from the spec, removing the file of a tag that is gone; it never touches a file there that does not open with // Code generated by wf api sync … DO NOT EDIT. --skip NAME leaves an operation out, and the config remembers.

  • wf api check exits 1 when sync would change anything, for CI, and wf check warns N07. wf api eject Backend turns api Backend from "…" into files; wf api list shows every service, its groups and endpoints.

  • The reader, fixed and extended. JSON or YAML (its own reader, which refuses anchors and tags with the one line that converts the file), in the file's own order. Tags are groups (Backend.people, default for an operation with none). Every error status is a case of the operation's error enum (CreatePersonError, notFound(problem: Problem) on 404), a 4XX its class's (on 4XX). A parameter goes where the spec says, under the server's name (in query "page-size", in cookie "session_id"), with its default. A body and an answer are read by media type; one the language cannot send or read stops the read with the operation named. An object or a list of cases written in place is a record or an enum named by its place; a shape the spec does not say is Json, never Any; a field no program can name is quoted ("first-name": String?). x-invalidates and x-pagination are read.

  • The editor and wf render read the spec as the build does: a call of an endpoint from api … from is known in hover, completion and the problems list.

  • invalidations { } and pagination { } in a service say what a write of a group makes stale and how a read pages, for endpoints written elsewhere: people.deletePerson(id) invalidates [people.listPeople, people.getPerson(id)]. Each is checked as if written on the endpoint (N05, N14).

  • fake Examples for Backend.people from examples answers every endpoint it does not answer itself with the spec's example of a success.

  • A paged read's .update(change) is handed the items it has gathered, as the page shows them.

Carried to 7 by `wf migrate`

5

7.0 has no loose mode, so wf migrate carries a 6.x project across.

  • Every fix, at once. The step applies the fix every 7.0 finding carries, again and again until none is left: the request forms (fetch → http.get, ready(v) → .loaded(v), .data → .value, on: → refresh:, -> T → -> T!, :id → {id}, at where there was none, headers { } → middleware [header(…)]), what each state holds, each action returns and fails with (-> ! E for a try in an action that said nothing), each parameter takes, JSDoc for a script, a condition's comparison, a splice for text joined to a number ("+" + n → "+{n}", T18), a splice or a unit for a conversion (T34), try where a result's value is wanted, an error enum's http case (N12).

  • Then what a person decides, listed by place — an on request hook to write as middleware, a paginate: to move onto its endpoint — and the changes that need no edit: a POST is not retried unless idempotent, nothing is cached unless the server says so, every answer is checked. --check says what it would fix and writes nothing; a second run finds nothing.

  • New fixes in wf fix and the editor, from the same work: T34, N12, N03, headers { }, and try for a result's value.

  • A project whose output is outside it ("output": "../docs") is migrated too: the step writes no output.

  • T20 is an error: a list or a record shown as text. lints and // wf-allow cannot lower or accept it: they lower only the errors that ship no broken page (R01, C02, S04, I01, I02, I04).

Where a type is unknown

wf types --holes lists every place the checker cannot say what a value is — a parameter with no type, a field of a Map, a browser global, catch e, a built-in's prop of no declared type — with its file, line and kind, and the count of each kind (--json for a tool). A value is counted where it becomes unknown, not at every place it goes afterwards. Inside the checker, a value an error has already been reported about is no longer Any but a type of its own, which agrees with everything as Any did, so the count holds only what the program leaves untyped.

Every built-in follows the theme

5

A built-in draws from the theme's tokens alone, so a theme restyles all of them, and a dark theme needs nothing beyond its colours.

  • What is written on a tone is a token: color-on-primary, -secondary, -success, -danger, -warning and -info are the label of a primary button, a badge, a pressed toggle or a chosen day. A theme with a light primary names a dark one, and A13 checks each pair. A theme with a pale tone may draw new A13 warnings.

  • Alerts, focus rings, highlights and stars are mixed from the theme's colours, rather than fixed tints, and color-backdrop dims the page behind a modal, a dialog, a sheet and a drawer.

  • A Modal or Dialog is as wide as its <dialog>, so class: or style { width: … } on it sizes what it shows.

  • The structural look keeps a Popover's box, and toasts take the theme's font.

  • The spa starter's own dark-mode button is DarkModeSwitch, so it no longer hides the built-in ThemeToggle.

Found by hand, before the release

9

A pass over every 7.0 feature in a browser, against a server that misbehaves on request, found and fixed these:

  • A parameter's default is sent. pageSize: Number = 20 in query "page-size" sends page-size=20 when a call leaves it out, rather than nothing (and the server's own default).

  • An endpoint of a group named like a list helper — Backend.people.remove(id) — is the endpoint, never the list method.

  • form.apply reaches any named control of the form, not only one a validate block guards: the message under it, aria-invalid, aria-describedby, the focus, and gone when the reader changes it.

  • FileUpload(bind: photo) holds what was chosen: a File?, or with .multiple a [File] (F02 when the state is the other).

  • An error thrown under a busy button reaches the console, wf serve's overlay and a test, rather than vanishing.

  • A write kept offline is made up again by the service's middleware, so bearer(Session.token) sends the token of the moment it goes.

  • let x: T = try await http.get(…) is held to T, as a resource's answer always was.

  • wf render holds a read's data to its endpoint's type when the read names none, and draws .loaded for a match written with .loaded(v) and else.

  • wf api add writes an endpoint with a text answer (-> String! as: .text) that parses, and wf api check says what sync would do rather than what it did.

Removed

1

  • WF.fetch, the runtime of WebFluent 2's fetch x from url { … }, which nothing the compiler writes has called since 3.0. wf migrate still rewrites that grammar.

6.2.0

#6.2.0

15 November 2026

The built-ins work for keyboards, screen readers, touch screens and right-to-left pages, and a built-in a later WebFluent adds never changes what a project draws. Some sixty join them — a data table, a tree, a command palette, a menu bar, a tour, a lightbox, a consent banner and the rest — and wf generate block writes a whole page to start from.

A project's own component wins

A component a project declares is what a call of its name draws, even where a built-in has that name. It used to be the other way: the built-in was drawn and the project's component never was, so every built-in the language gained could take the place of a component a project already had. V11 is now information rather than a warning: it says the project's component takes the built-in's place, which cannot then be placed there.

Stacking and target sizes are tokens

2

  • A stacking scale — z-sticky, z-drawer, z-dropdown, z-modal, z-toast, z-tooltip, z-skip-link — replaces the numbers the built-ins' rules wrote out (100, 200, 9999, 10000), so a page's own sticky header or drawer can sit where it should against them.

  • target-min (24px, WCAG 2.2's floor for a pointer) and target-min-touch (44px) are the least a control reaches. On a touch screen every button, icon button, tab, menu item, sidebar item, check box, radio, switch and carousel control is at least 44px; with a mouse nothing changes size.

The arrow keys, everywhere a group needs them

6

  • roving: .x (.y, .both) on any element makes it one stop for Tab, with the arrow keys, Home, End and the first letters of a name inside it — a toolbar, a row of choices — the other way round across a right-to-left box. Tabs, menus and a carousel's dots are built on the same code.

  • Tabs(bind: tab) keeps the open tab in a state, holding the open page's value:; Tabs(value: v) reads it and on change(v) hears the one picked, so a tab can live in the address. A page can be disabled:, a strip .vertical, and .manual opens a tab on Enter or Space rather than as the focus reaches it.

  • A tab strip is painted before any script runs: its tabs, the open one selected, and the other panels hidden.

  • Menus jump to an item by the first letters of its name.

  • on key("inline-start") and on key("inline-end") are the arrow toward where a line starts or ends, swapped in a right-to-left box.

  • wf test has expect focus "Beta", and a click step puts the focus where a real click would, so the keys a test presses next go there.

Overlays on one path

10

  • Modal, Dialog, Sheet and Popover take dismiss: — .any (Escape or a press outside, the default), .escape, or .none for what must be answered — and initialFocus:, the ref: that takes the focus when one opens. When one closes, the focus goes back to what had it.

  • A modal, a dialog, a popover and a menu fade out before they go, however they were closed, and come in the same way.

  • A popover's anchor says what it opens and whether it is open (aria-controls, aria-expanded, aria-haspopup), and the focus goes to the popover's first control, where it stayed on the anchor before.

  • Sheet is new: a modal from the bottom, or the start or end of the line, dragged shut by its handle or heading, with snap: points for a bottom sheet.

  • AlertDialog is new: a dialog a screen reader hears as an alert, read with its body, which Escape answers and a press beside it does not.

  • await ask("Delete the project?", danger: true) asks from a handler and is the answer, in an alert dialog with the focus on no.

  • toast(…) shows a toast from a handler, with action: and onAction: for a button on it; every toast now has a close button, waits while the pointer is on it or the focus is in it, and no more than three show at once. toast.promise(p, loading:, done:, failed:) follows a promise.

  • announce(text) speaks to a screen reader with nothing on screen moving; announce(text, .assertive) interrupts.

  • On a narrow screen an open Sidebar holds the focus, closes on a press outside, and is one of the layers Escape closes in turn.

  • A18 warns of a Popover with no name; A08 covers AlertDialog and Sheet.

Presses that hold up

7

  • A double click submits once: a call of an async action with the same arguments as one still running is that call, and both get its answer. A call with other arguments still runs beside it, and action poll() concurrent { … } runs every call.

  • A Button whose on click, or a Form whose on submit, calls an async action is busy until the call ends — aria-busy, a press that does nothing, and past 300 ms a spinner in place of its label at the same width — with nothing written for it. The focus stays on it.

  • Button(loading: Checkout.pay.pending) is busy the same way while a value holds.

  • on input(debounce: 300.ms) { … } runs once the typing stops; on scroll(e, throttle: 100.ms) { … } at most once in that long. The debounced search is one line.

  • on visible { … } runs when an element comes into view: a "load more" row.

  • What is playing its exit is inert: a press or a Tab cannot land on it.

  • wf verify names each control drawn under 24×24, as a warning.

Content built-ins

13

  • Callout("Run wf check first.").tip sets a note apart, as GitHub's alerts do: .note, .tip, .important, .warning or .caution, each with its icon and word, or a title: of its own.

  • Kbd("mod+k") is a key as this system writes it: ⌘K on a Mac.

  • EmptyState(icon:, title:, text:) { … } is what a list shows with nothing in it, and what to do about it.

  • Stat("Revenue", value:, format: .currency, change: 0.124) is a figure, its label and which way it moved, said to a screen reader too.

  • CodeBlock(code, language:, title:).copy.lines is a block of code with its file name, a copy button and line numbers.

  • Chip("Rust", icon:, selected:).removable is a compact label that can be pressed (a toggle button) and removed (on remove); Tag stays the one that does neither.

  • VisuallyHidden("(opens in a new tab)") is words for a screen reader only.

  • CopyButton(value: url) copies, says Copied and announces it.

  • ThemeToggle switches light and dark; LocaleSwitch offers each of i18n.locales in its own language.

  • Accordion.single { Accordion.Item("Shipping") { … } } is sections of native <details>, one open at a time.

  • Field(label:, hint:, error:) { control } names and describes a control of your own; Fieldset(legend:) groups controls under a legend.

  • InputGroup { Icon("search") Input(…) InputGroup.Clear } draws an input and what goes beside it as one box.

  • OnThisPage(levels: 2) lists the page's headings, marking the one being read.

Each is drawn the same on the live page, in the static paint, by the template engine and, where it can be, in a PDF.

Choosing built-ins

7

  • Toggle("Bold", bind: bold) is a button that stays pressed.

  • ToggleGroup(bind: view, label: "View") { ToggleGroup.Item(…) } is one choice of several, or several with .multiple: one stop for Tab, the arrow keys inside it.

  • RadioGroup(bind: plan, label: "Plan").cards is radio buttons under a legend, each option's hint read with it, drawn as cards if asked.

  • Pagination(bind: page, pages: 12) is Previous, the pages around the current one with gaps for the rest, and Next.

  • Stepper(bind: step) { Stepper.Step("Account") { … } } shows one step at a time and each step's state.

  • NumberInput(bind: qty, min: 1, max: 99) is a number between − and +, stepped by the keys too.

  • Calendar(bind: day, mode: .range) is a month a keyboard can work, for one day, a range or several, with days that cannot be chosen.

Collections and an app's frame

7

  • Listbox(bind:, label:) { Listbox.Option(…) } is options always shown, one chosen or, .multiple, several (Space, Shift with an arrow, Ctrl+A).

  • Tree(items:, children:, key:) { row(f) { … } } is nested items a keyboard opens and walks as a file tree does.

  • DataTable(rows:, key:) { DataTable.Column(…).sortable … } is a table of records whose columns sort, with a cell(r) block, an empty block and rows chosen by bind:.

  • Combobox(bind:, options: | search:, text:) is a field that offers what matches, from a list or a server, one or several.

  • CommandPalette(open:) { … CommandPalette.Item(…) { on select { … } } } is a dialog of everything to do, filtered as the reader types.

  • AppShell { AppShell.Header { … } Sidebar { … } Router } frames an app.

  • A built-in may take named blocks its entry lists; E103 names the ones it takes.

More form controls

7

  • CheckboxGroup(bind: picked, label:, all: "Every topping") ticks the values of a list, with a box for all that is mixed while some are ticked.

  • InputOTP(bind: code, length: 6) is a one-time code a digit to a box, filled whole by a paste or by the code the browser offers.

  • TagInput(bind: tags) makes words chips.

  • Rating(bind: stars).half is stars a keyboard can set; .readonly only shows.

  • Slider(bind: price).range has two thumbs.

  • DateRangePicker(bind: stay, presets: [.last7]) chooses a range in two months, or by a preset.

  • Textarea(…).autosize grows with its text; Input(…).password.reveal shows the password on a press; FileUpload(bind: files).dropzone takes files dropped on it, each shown with a preview and a button to take it out.

More navigation

4

  • NavigationMenu { NavigationMenu.Item("Products") { … } } is a site's navigation whose entries open panels, one at a time, with the arrow keys along the row.

  • Menubar { Menubar.Menu("File") { Menu.Item … } } is a desktop app's menu bar: one Tab stop, and with a menu open Left and Right open the one beside it.

  • ContextMenu { … ContextMenu.Items { Menu.Item … } } opens its menu where a right-click or a long press happened, or on the menu key — no state to write.

  • BottomNavigation is a phone's tab bar, clear of the home indicator; PrevNext links the pages either side of this one.

More overlays

5

  • HoverCard { Link(…) HoverCard.Content { … } } previews what a link points at, on hover or focus.

  • LoadingOverlay(visible: saving) { … } covers a region while it is busy, and keeps its content out of reach.

  • Lightbox { Image(…) … } opens its pictures full screen, with the arrow keys, a swipe and zoom.

  • Tour(open: touring) { Tour.Step(target: newBtn, title: "New") { … } } walks through the page, each target lit through a cut-out.

  • ConsentBanner("…") asks before anything tracks the reader: a meta.scripts entry marked "load": "consent" loads only once they accept, and Decline is as easy as Accept.

More for showing and laying out

7

  • DescriptionList, Timeline, Item and AvatarGroup show pairs, events, rows and people.

  • Gallery lays pictures out in a grid of one shape; Masonry places anything in columns at its own height.

  • CircularProgress is a ring; Meter is a level against its range.

  • Sparkline([3, 5, 2, 8]) is a tiny chart in a line of text, drawn when the page is built.

  • RelativeTime(post.date) says 3 minutes ago and keeps saying it.

  • AspectRatio, ScrollArea, Center and Sticky hold a box's shape, scroll it, centre what is in it, and stick it to the top.

  • PanelGroup(bind: sizes) puts handles between panels that resize them, by pointer or keyboard; a persist keeps the sizes.

The last of the built-ins, and blocks

6

  • ColorPicker, TransferList and Editable choose a colour, move things between two lists, and edit text in place.

  • Fab is a floating main action, a speed dial with Fab.Actions; BackToTop appears once the page has scrolled.

  • Popconfirm asks before the button in it acts.

  • Highlight(text, query: q) marks what a search found.

  • ClientOnly { … } is drawn in the browser alone.

  • wf generate block sign-in — or pricing, dashboard, settings — writes a whole page into src/pages/ for the project to own.

What the built-ins lacked

22

  • CodeBlock(code, highlight: [3, 4]) marks lines; CodeBlock(files: […]) is a tab a file.

  • Stat(…, trend: [31, 40, 28]) draws a sparkline under the figure.

  • ClientOnly { placeholder { … } … } paints its placeholder.

  • Gallery and Masonry take columns: per breakpoint.

  • Tour and Lightbox take their words as props (next:, of: …).

  • DataTable(filter: q, pageSize: 20) filters its rows and shows them a page at a time.

  • PanelGroup.Panel(collapsible: true) folds away and comes back.

  • A CheckboxGroup's options may be drawn by a for or an if.

  • The keyboard checks of tabs and toolbars run again right to left.

  • wf test drew a built-in where the project had a component of its name in another file.

  • x ?? y where x could only be null (a field written null in a map) was taken to be null too, and spliced into text drew T19.

  • -(x) where x is negative compiled to --x, which a browser refuses, and the page did not run.

  • format(v, .percent, 1) wrote 2% once the page ran where the static paint wrote 2.0%; both write the places asked for.

  • A part's mount: was written as an attribute and called with nothing.

  • wf check knows an image's fields: hero.width, .height, .color and the rest were a T05 there, though wf build read them.

  • wf test's press "ctrl+k" holds its modifiers — ctrl, shift, alt, meta, and mod (⌘ on a Mac, Ctrl elsewhere) — so a shortcut can be tested by pressing it.

  • A page on /docs/* answers /docs and every address beneath it in the running site, as the link check always said; a static build paints it at docs/index.html instead of a directory named *.

  • A page's image: works out what it splices ("{CDN}{post.cover}"), as title: and description: do.

  • A Link's own aria-current: is kept: the router marks the current link only while the author's value is null, and the static paint no longer writes the attribute twice.

  • I03 says what a reader sees: a locale with no file reads the default locale's messages, not the keys; under i18n.literals the default locale's table may leave out its own words.

  • A theme declared twice is a duplicate (E102), and two pages that share a name no longer draw a puzzling R05.

  • The editors' indented-layout grammar reads an if value's branches and a match value's arms written on the lines under them, as wf fmt --to wfx writes them.

Reached by every reader

9

  • Every control of the documentation site is at least 24×24 (WCAG 2.5.8): the footer, breadcrumb and card links, and "Cookie settings". So is a Slider's input.

  • A Breadcrumb's last crumb says it is the page the reader is on (aria-current="page").

  • The site's props and events tables are DataTables, its breadcrumbs a Breadcrumb, and its search's kinds a ToggleGroup; the tutorials use the built-in ThemeToggle, EmptyState and Stat.

  • The reference's list of DOM events named focusin and focusout twice.

  • A Switch can be reached from the keyboard and is heard as a switch. Its input was display: none, which took the very element that says "switch" and "on" out of the Tab order and the accessibility tree. It is now laid unseen over the control, with a focus ring on the track.

  • A Sidebar shut off a narrow page is out of the Tab order. It was only slid aside, so Tab walked through links no one could see. It is hidden once it has slid out, and opening it from its toggle takes the focus to its first link.

  • A press on a Modal's or a Dialog's backdrop closes it, and its visible: state follows, as a press outside a popover or a menu already did. A press inside, or a selection dragged out of it, does not.

  • A toast shown while a modal is open is seen and heard. It was drawn under the modal, which also made it inert. The stack is now drawn in the top layer and moves into the open modal for as long as it is open.

  • The first message is heard. The live regions that toasts, route changes and form errors speak through were made on their first message, which a screen reader does not announce. They are made when the page loads. A form error is no longer said twice.

Right to left

3

  • Tabs, menus and a Splitter follow the page's direction: in an Arabic page ArrowLeft moves to the next tab, opens a submenu, and widens the region before a splitter. A submenu opens to the left of its item, and a layer placed .bottomStart lines up with its anchor's right edge.

  • A Carousel moves to the next slide in the right direction, a Switch's thumb slides the right way, and toasts come in from the page's end.

  • Arrow keys pressed with Alt, Ctrl or ⌘ are left to the browser, so Alt+ArrowLeft goes back from a tab strip or a menu.

Fixes

6

  • A static build paints a menu's items with their roles — menuitem, menuitemcheckbox with its state, a submenu's entry and its hidden list — and a Menubar.Menu or ContextMenu.Items drawn by a for or an if as the menu it is.

  • A live Radio carries its value, as its static paint did: a form posted before the script runs no longer sends on.

  • A Menubar item's shortcut: runs it from anywhere on the page.

  • ConsentSettings asks the reader again; D06 says when a script waits for consent and no ConsentBanner asks for it.

  • The build's read-back of its own JavaScript (E901) catches a number after ++ or --, which a browser refuses.

  • A static build paints what it can read of the built-ins the page used to draw alone: an OnThisPage's list of the page's headings (each given the id the live page would give it), a LocaleSwitch's buttons, the rows of a DataTable and a Tree, a Rating's stars, a CircularProgress's ring, an AvatarGroup's +2, and the value of an Editable, an InputOTP and a TagInput.

Smaller fixes

3

  • An async action's pending stays true until every call of it has ended; the first of two calls to end used to clear it while the second ran.

  • show with an exit animation no longer hides content that was shown again before the exit ended.

  • A Splitter's handle reaches 24px, WCAG 2.2's least target, around its 4px line.

6.1.0

#6.1.0

14 November 2026

A site sends much less: the runtime ships only the functions a program reaches, with short names, and only the styles and animations it draws on. The compiler draws icons and the reader's theme before any script runs, and refuses a few more programs that built and then failed in the browser. A project that builds with 6.0 builds with 6.1 unless wf check now finds one of those (see "Upgrading").

Smaller

7

Gzipped, built by 6.0.0 and by 6.1.0 from the same sources:

Project app.js styles.css
The counter example 9.2 → 4.2 kB 3.8 → 1.9 kB
wf init -t static 23.7 → 14.8 kB 5.5 → 4.3 kB
wf init -t spa 23.9 → 16.9 kB 6.2 → 5.0 kB
The documentation site (564 pages) 142 → 111 kB 16.7 → 15.8 kB
  • The runtime is cut by function, not by module. One call into a module used to ship all of it, and every function of core shipped to every project. A build now keeps what runs at load, every function the program calls through WF, and what those name, until nothing new is named; WF exports only what is called. A project's own scripts, an elements build's definitions, the dev server's stores panel and the studio count as callers. "build": { "runtime": "full" } still ships everything.

  • The runtime's names are shortened in a minified build: its top-level functions and values, and each function's locals, the most used first. What a program calls on WF keeps its name.

  • Only the styles a project draws on. The grid, columns, spacers, dividers, code highlighting, Markdown, drag and drop, and the document and slide elements are each kept only with the component that uses them, and the rules every page keeps (reflow, focus, reduced motion) lose the selectors of components a project does not use.

  • Only the motion a project uses. The animation module ships to a program that animates: an animation, an element marked to enter or leave, or a router transition. The route-transition player and async validation ship only when used; key combinations and the theme are modules of their own.

  • A one-page site is one file: its code is in app.js, with no chunk.

  • A route table without the pages' details. A split build sends each page's title, language and layout with the page's own chunk, so app.js holds only each route's path and page name.

  • wf build --stats counts what the build keeps of each runtime module, and what that comes to with its names shortened.

A build does more to prune, so it takes a few milliseconds longer on a small project (about 8% on the documentation site).

Additions

9

  • Icons in the static paint. Every built-in icon is drawn into the pre-rendered HTML, from the same table the runtime draws it from. Before, an icon was an empty element until the script ran, so a header's icon buttons were blank squares on the first paint.

  • The reader's theme before the first paint. A site that calls setTheme gets a small theme.js, linked first, which puts the reader's choice on the page before it is drawn: no flash of the other theme.

  • A page's own language in its text. A page with lang: shows its t() text from that language's table, in the pre-render and while it shows; leaving it puts back the reader's language.

  • A call at the top of app is set-up code, run once when the site opens: app { use Session Session.load() Router }. It was read as an element with a flag.

  • One main landmark. A program that draws its own main (an element with role: "main") gets a plain div as the box the router draws pages into, so a page has one main landmark and its header is a top-level banner. The box keeps its id, wf-main.

  • One skip link. The engine's own skip link is left out when a page opens with its own.

  • A Markdown code block takes keyboard focus (<pre tabindex="0">), built and live, so a long line can be scrolled without a mouse.

  • reduce and reduceRight at build time, so a derived value folded with them shows in the static paint, a template and wf test.

  • The browser compiler's preview without a service worker. previewInline() in crates/wf-wasm/wf.js serves a build through run.html where a browser refuses a service worker (a private window, some embedded browsers).

Checks

5

  • T10: an endpoint called with positional arguments. Backend.signUp(email, password) sent the first value as the call's map and the second nowhere; the finding writes the call by name.

  • E111 in wf check: a theme the config names and the program does not declare. wf build stopped on it while wf check said "No problems".

  • R05 reads the site's language. A page with no lang: is in meta.lang, so a translation written in that language is now caught.

  • log(a, b) says log takes one value and how to log several.

  • A component or store member only a test reaches is no longer U03 or U04; a t() key a string elsewhere in the program names is no longer unused.

Fixes

4

  • optimistic() works. It was handed the state's value instead of the state, and threw holder is not a function every time. An action that used it without awaiting anything was written with await in a plain function, which stopped the page; and a store's action never rolled back what it showed.

  • A variant or a size given state follows it. Button("Save", tone: tone) and Stack(gap: gap) wrote the value as an attribute nothing reads, so the element kept its default look. A class prop (and gap, align, justify) that reads state is now a class looked up from its case, followed as the state changes and painted at its first value.

  • A short token as a value. state accent = $primary compiled to var(--primary), which no theme sets; a short name only one token group has is that group's ($color-primary).

  • wf verify is ten times faster: a page is done once it has loaded and been quiet for 100 ms (900 ms at most), and up to three browsers visit a site's routes at once.

Upgrading

Run wf check. It may find T10 (call an endpoint by name), E111 (a theme the config names that no file declares) or R05 (a page and its translation both in the site's language: set meta.lang, or give the page lang:). A stylesheet that selects main#wf-main should select #wf-main when the program draws its own main.

6.0.0

#6.0.0

13 November 2026

A page can be in a language of its own, the compiler holds up to anything it is given, and the Rust library has a smaller surface with typed errors. A project that builds with 5.14 builds with 6.0, unless it relied on something now refused because it shipped a broken page (a status code the grammar cannot hold, nesting past 100 levels). What 6.0 breaks on purpose is the Rust API (see "Upgrading").

Additions

4

  • lang: on a page. page HomeEn(path: "/en", lang: "en", …) is written <html lang="en"> (and dir="rtl" for a language written right to left), with its own og:locale and inLanguage on its JSON-LD WebPage. The router sets lang and dir on <html> when it shows the page, and puts back the site's language, or the locale the reader chose, on a page without one. wf render uses it when no --lang is given. A site whose pages declared one language each used to ship every page in meta.lang, so crawlers and link previews read its English pages as Arabic (#6).

  • translates: on a page. translates: Home names the page this one is a translation of. Pages joined this way, directly or through each other, list each other as hreflang alternates, each at its own address, canonical to itself and in its own lang:, with x-default for the one in the site's language, and name each other's languages as og:locale:alternate. A :param page's translation is matched by its parameters (/en/posts/:slug for /posts/:slug).

  • R05: a translates: that names no page or its own, or two translations of one page in one language.

  • worker is offered where a statement starts, beside socket, stream, channel and peer.

Faster

3

Measured on the documentation site (77 files, 140 pages); cargo xtask bench reproduces the numbers.

  • wf build takes 0.36 s instead of 4.4 s, to the same bytes:

    • pages are painted, compressed and read back on every core;

    • a data constant is shared rather than copied each time a page reads it;

    • the compressor finds its matches faster, and is run once a file rather than twice;

    • wf allocates with mimalloc.

  • wf check takes 62 ms instead of 82.

  • The language server answers in about 0.1 ms instead of 46:

    • it keeps the analysed project between requests, and analyses it again only after a change;

    • an unchanged file keeps its parse and its tokens.

    An edit's findings arrive in 74 ms instead of 145. Before, a hover cost as much as checking the whole project and grew with it.

Fixes

15

  • No more ?lang= alternates. A project with several i18n.locales listed ?lang=<code> for each as an hreflang alternate, but every ?lang= address serves the default locale's HTML with the bare address as its canonical, so a search engine filed each one as a duplicate and ignored the set (#5). A locale the browser switches to on one address is not an alternate; translations with translates: are. ?lang= still opens a page in that locale for a reader who follows such a link.

  • The compiler cannot be made to hang or crash by what it reads. A name starting with a letter such as ℘ no longer loops forever; nesting past 100 levels is E120 instead of a stack overflow; a template render is bounded (E121); the parser and the PDF engine return an error for input they cannot read rather than panicking; a picture is refused past 50 megapixels before it is decoded.

  • Names in any script repaint. A state named in Arabic (state عدد) is reactive in the bundle, and a name may start with any letter Unicode allows in an identifier.

  • Text is written as text. A \ or ${ in a spliced string, a page title, a class or a colour from data, a head { } tag and a Frame are escaped where they are written, and the build reads its own pages back as a browser would before it ships them. A template's data cannot add CSS declarations or attributes.

  • Template answers as wf build does: one evaluator and one renderer serve both, so name.length, comparisons and indexing agree.

  • A page's state no longer leaks into app, and a rendering server that catches a panic no longer carries one render's state into the next.

  • Every parse error is reported, not only the first; findings are in a fixed order and placed by character, not byte.

  • Numbers the grammar cannot hold are refused (a status past 599, a fractional one, a negative carousel interval) instead of being clamped.

  • .wfx lexing is linear in the size of the file.

  • Runtime: a disposed effect lets go of what it read; carousels, drawers, popups, now, VirtualList and submenus go with their page; navigate() and the router stay on the site; the request engine and the connections are bounded, and credentials never enter the offline queue; the service worker keeps sites under one origin apart.

  • Builds stay in their project. build.output outside the project is refused unless --allow-output-outside says so, wf serve listens on this machine unless --host says otherwise and serves nothing outside the build, and a public_env name takes no value from the shell unless WF_ALLOW_SHELL_ENV names it.

  • wf verify and wf test run Chrome with its sandbox, in a private profile that goes when wf does.

  • I/O errors name their file, and a config or translation that is there but cannot be read is an error rather than the defaults.

  • SVG text is laid out with the document's own fonts.

  • wf check --allow-output-outside, as wf build has: a project whose build.output is outside it could not be checked at all.

Editors

7

  • The grammars read names in any script, raw strings of any length and two declarations on one style line as the compiler does.

  • Zed colours worker and expect not, outlines parts and persisted state, and has snippets for persist, validate, on key, api and test.

  • VS Code colours every style property, colour and regex literals, a splice's format, /// and // wf-allow(…), and the indented layout's blocks.

  • The language server reads the compiler's own tables for keywords, events, built-in names and design tokens, and follows a component's props, events and slots for definitions and renames.

  • Both extensions download the release they pin and check it against SHA256SUMS.

  • VS Code colours a name in any script as the compiler reads one, and tells a member (e.message) from a flag (.danger).

  • The grammars read a raw string inside code that does not parse yet.

For tools (the Rust library)

8

  • One documented surface. template, syntax (the AST, fmt, layout), diagnostics, build, config, vfs, outfs, memory, init, studio and the root items are the API semver covers.

  • The rest is the crate's own: the checker, the code generator, the PDF engine, the registry and the tools. The internals feature makes them public again, hidden from the docs and outside semver, for a tool that accepts that they change in any release.

  • One path per item. The root's second paths (webfluent::lexer, ::parser, ::fmt, ::error, ::assets, …) are gone; use the layer's (webfluent::syntax::fmt, webfluent::diagnostics::error).

  • One finding type. The linters and the studio return diagnostics::Diagnostic; A11yWarning, VocabWarning and studio::StudioDiagnostic are gone (rule_id is code).

  • Typed errors. WebFluentError::IoError, ConfigError, CodegenError, EditError and NotFound hold their own types, each a message and the error beneath it, which source() walks. Build one with WebFluentError::io(…), or io_with(message, cause) to keep the cause; ? on an io::Error keeps it too. What an error prints is unchanged.

  • #[non_exhaustive] on WebFluentError, the AST's enums that gain cases (Declaration, Expr, StatementKind, TypeRef, Step, …), Plan, Tag, OutputType, RuntimeMode, ScriptLoad, init::Template, memory::Contents, EditOp and ArgRef.

  • Dependencies are up to date: every crate at its newest release the crate's Rust version accepts, taffy 0.15 and miniz_oxide 0.9 among them. usvg 0.47 and fontdb 0.23 stay where krilla-svg holds them.

  • Every public Result says when it fails; builders are #[must_use]; the lexer, parser and code generator implement Debug; a choice that was two bools is an enum.

Upgrading

3

  • A project: nothing to change. A multilingual site that relied on the ?lang= alternates had them ignored by search engines already; to have each language indexed, give it pages of its own with lang: and translates:.

  • A program using the crate:

    • a path that no longer resolves moved to its layer (webfluent::fmt → webfluent::syntax::fmt);

    • a module that is no longer public (webfluent::sema, codegen, paged, registry, platform, …) needs features = ["internals"], and pins an exact version, since those change in any release;

    • a match on an enum above needs a _ arm;

    • WebFluentError::IoError(msg) as a value is WebFluentError::io(msg); as a pattern, IoError(e) binds the error, whose message() is the old string.

  • The editors pin this release: update the extension after it is out.

5.14.0

#5.14.0

12 November 2026

The compiler runs in a browser. Built for WebAssembly, it does in a page what wf build does on a machine — sites and apps, every check, pictures sized to WebP, PDFs and slide decks — with nothing sent to a server. It is what the documentation's playground runs.

Additions

4

  • The compiler as WebAssembly (crates/wf-wasm). wf.js is the one thing a page imports: compile(files, config) takes a project as a map of path to text or bytes and gives back the files the build wrote, its pictures and PDFs, and every finding exactly as wf check --format json lists them; check, explain and registerFont beside it. A demo page compiles as you type.

  • Loaded by what a project needs. The compiler is about 1.6 MB gzipped, fetched on the first call. A project whose config asks for a PDF or a deck loads a second build with the paged engine (about 2.7 MB) and the fonts it is set in, then and only then; a face for Arabic is fetched the first time a document has Arabic in it, since a browser has no machine fonts to fall back on.

  • A preview served as a host would serve it. preview(out) hands a build to a service worker that answers for it under preview/ — every page, chunk, stylesheet and picture, and the routes between them.

  • Pictures in the browser. libwebp is compiled to WebAssembly against a C library of its own, so a picture is sized and written as WebP as wf build does it; the encodings are kept from one build to the next, so an edit that leaves the picture alone does not encode it again.

For tools

5

  • webfluent::memory: compile and compile_files build a project from memory — no disk read, none written — with the findings and the output as values. It runs natively as well.

  • webfluent::outfs is where a build writes: the disk, or memory inside outfs::capture. webfluent::platform stands in for threads, clocks and the environment where WebAssembly has none.

  • OverlayVfs::set_bytes lays a file that is not text (a picture, a font) over a path.

  • The paged engine reads a project's fonts and pictures through the Vfs it is given (Options::from_pdf_via, from_slides_via, reader_via), and paged::fonts::register_font takes a face — a font file as it is, zlib or gzip — that stands where a built-in one does.

  • Three features for a WebAssembly build: webp, pdf and bundled-fonts. A native build has all three whatever the features say, so default-features = false leaves PDFs and WebP as they were.

Fixes

5

  • A style { } on a component's call styles the component. Its rule was compiled and its class put on nothing, so placing a component in a grid or sizing it from its call did nothing. The class now joins the root's classes, as class: does, on the live page and in the static paint.

  • An if let value whose branch awaits compiles. if let p = x { await f(p) } else { … } used as a value made a plain arrow with an await in it, and the page's code did not parse; it is now an async arrow, awaited.

  • D01 reads public/ through the project's Vfs, as every other check does, so an editor's unsaved picture or a project held in memory counts as there.

  • An @font-face in a PDF is read from its bytes, not written to a temporary file first.

  • The agents' skill says which compiler it is for. just bump now sets the skill's version and its copy of AGENTS.md with the crates, and the release preflight refuses a skill left behind. 5.13.0 shipped saying 5.12.0.

Upgrading

Nothing to change. A project builds to the same bytes as it did with 5.13.0.

5.13.0

#5.13.0

11 November 2026

WebFluent for coding agents: a skill that teaches the wf loop, a reference with a part written for agents, and a core an agent is given whole. An editor's preview follows a style or text edit with no reload. And a run of fixes to what a running page reads while a change is still going on.

Additions

6

  • A writing-webfluent skill for coding agents. Agents that read Agent Skills (Claude Code, Codex, Gemini CLI, Copilot, Zed and others) can install one skill that teaches the loop: ask the compiler what a component, store or token is before writing, then check, explain, fix, format, test and verify. It names the mistakes models make most, each with its code. References an agent reads by task go with it: code quality and a review checklist; recipes (one small app in fifteen pieces); styling (the tokens, themes, right to left); testing; diagnostics (each common code, its cause and fix); PDFs, decks and server rendering; and apps with Tauri for the desktop and the phone (the typed bridge script, capabilities by platform, safe areas, Android's back gesture, signing). A test compiles every example in them with no warning, and checks that every command and code they name is one wf has. The README says how to install it.

  • wf init gives every new project the skill, in .agents/skills/ and .claude/skills/; its language reference points at the project's AGENTS.md rather than repeating it.

  • The reference has a part for agents. AGENTS.md gains "For agents": the grammar in a few lines, ten idioms, the mistakes made most (T06, C02, X05, T13, E002, T17) and one whole page; every example compiles with no warning.

  • AGENTS.md covers Tauri and Electron apps, on the desktop and the phone.

  • Eleven icons for a design tool: pointer, reach, frame, line, pipette, comment, hand, zoom, ruler, eye-off and unlock.

  • PDFs and decks draw the logical insets (inset-inline, inset-block), read left to right as the logical paddings already were.

For tools

7

  • webfluent::patch: in_place compares two programs and answers with what a running page must change to follow a style or text edit (one class swapped and its rules, or an element's new text), or a rebuild and why. in_place_with takes the project's breakpoints, and agrees holds a patch to what a full build generates.

  • webfluent::agent::context::reference_core() gives the sections of the reference an agent needs first, under 8,000 tokens; reference_section(title) gives any other.

  • Style values: the logical pairs (padding-inline, margin-block, inset-inline, …) are a Pair shape, and grid-column/grid-row a Placement, each printed in the fewest words and edited one side or line at a time; cell, read_placement and edit_placement are what a drop in a grid writes.

  • A token set by theme.tokens carries that value, so an editor can say the config overrides the theme's own. A theme's view can be of a theme the project declares other than the one the config selects.

  • An agent's prompt prints the config with its keys sorted at every depth, so one project always reads the same and keeps the prompt cache.

  • ChangeSet is Clone, and absorb_reads takes back what a copy read.

  • An editor's preview is no longer compressed, which took most of a warm build's time.

Fixes

7

  • A cached request that fails no longer leaks an unhandled rejection. A resource with cache: whose request failed reported an uncaught error beside the failure its error arm handled.

  • A derived value read while a change is running is up to date. An action an effect called, which wrote a state and then read a derived value of it, got the value from before its write.

  • A change runs its effects oldest first, so a branch that leaves disposes of what it drew before any of it reads again; before, an attribute could throw on the null and keep the branch from leaving. One effect that throws no longer keeps the others from running.

  • A store's derived values are worked out with the other stores in reach, in a test's render and a page rendered at build time, where a derived value reading another store came out empty.

  • mod+shift+/ matches. With Shift, a punctuation key sends its other character, and keyIs refused it; it is now read by its place.

  • A locale whose file is not JSON says why, with the line and column, instead of reading as a file with no messages.

  • The reference says what the compiler does. Every example in AGENTS.md compiles: the Row, Grid and Stack rows wrote gap: md (T13), key rule 20 wrote a deck in WebFluent 2 syntax, and others bound query, named a loop t, used tokens no theme declares or bound a DatePicker to a string. It counts 83 icons (it said 32 and 72, as did the guide), gives the runtime's current sizes (2 of 41 modules, 6.8 kB gzipped for a static page), lists E119, V12 and I05 as the warnings they are, adds rows for E005 and T22, and documents wf render, six CLI flags, theme.dark, theme.builtin: "structural" and i18n.literals. wf init writes this reference into a new project, so only a wf of this release gives a project the corrected one.

Upgrading

Nothing to change: run wf check.

5.12.0

#5.12.0

3 November 2026

A project written in Arabic, and translated by its own words: names in any script, every string a reader sees looked up by the text as written, plural forms chosen by the number in the text, and a locale that names its digits. Every name a program binds is now its own, whatever the generated code or the browser calls its own things. And the guide is rewritten, chapter by chapter, by what a reader is there to do.

Additions

11

  • Translate a project by its own words (chapter 28). With "literals": true in i18n, every string a reader sees (an element's text, its label:, title:, placeholder:, aria-label: and alt:, a record's text field, a value whose name says it is words, such as caretText or emptyLabel) is looked up in the locale's table by the text as written, and the source stays in the language it was written in. A string that splices a value is one key, with a placeholder named after it; Markdown written in place and a control's labels: are words too. wf test translates the program as the build does. What no table can translate (a text splicing more than a name) is the new warning I05, where it is shown.

  • Plural forms by the number in the text (chapter 28). A message with plural forms and exactly one number among its values takes its form by that number, so Text("{files} files") reads right in Arabic's two, few and many. With two numbers none is guessed.

  • A locale may name its digits (chapter 28). setLocale("ar-u-nu-arab") reads the ar table and writes format, ago and every count in Arabic-Indic digits; ar-u-nu-latn is 0–9 whatever the browser would pick. A date pattern's figures follow, and a is AM or PM in the locale's words. The document's lang stays the language, so a stylesheet's [lang="ar"] still matches.

  • t() in a store, and setLocale() with it, where both compiled to calls the page could not find.

  • Names in any script (chapter 9). A program's own names start and go on as Unicode's UAX #31 says, with the marks of their letters, and are one name however they were typed: state عددٌ = 3, store المهام, action أضف. The editor grammar reads them the same way. A bidirectional embedding, override or isolate control in the source, which draws code one way while it runs another, is the new warning E119.

  • Markdown draws GFM tables (chapter 27), the same at build time and in the browser: a header row, a delimiter row whose colons align each column, and \| for a pipe inside a cell.

  • Frame(srcdoc: html, sandbox: "") (chapter 21) is a declared prop, where it was an attribute passed through with a C04 warning. A value that reads state is followed, so the frame redraws as it changes.

  • A picture may carry itself: a data:image/… address on an Image's or an Avatar's src:, a Markdown picture or a sanitized <img> is kept, in the live page, the pre-render and the template engine alike. A link, a frame, a form, and any data: that is not an image, are still refused.

  • Fourteen icons (chapter 21), 72 in all: code, monitor, git-commit, play, layers, insert, grid, list, square, pill, image, sparkle, lock and type. An icon drawn in the browser now carries data-icon, as a pre-rendered one did, so a style keyed on the name matches both.

  • WebP is lossy at build.media.quality (chapter 42), through libwebp, keeping alpha: a 23 kB PNG that came out as 189 kB of WebP is now 5 kB. A file that would be no smaller than its original is not written, and wf assets --plan says which widths were dropped.

  • output_type: "static" pre-renders every page, as ssg: true does. The config accepted it and built a single-page app.

For tools

7

Each is for a tool built on the compiler (chapter 41); paths are under webfluent::.

  • agent::edit replaces each old_text where it is found exactly once: exactly, then ignoring line endings, then the indent, then with typographic quotes and dashes read as ASCII. Text found twice names its lines, text found nowhere the three nearest, and the edits apply all or none. ChangeSet::edit makes them on a file the set has read, and refuses one that moved since; a missing file is WebFluentError::NotFound. ChangeSet::edited shows what the edits would make of a file, before and after, without changing the set, and ChangeSet::dir names the project's folder.

  • A change set over newer buffers: it can be laid over buffers that moved on, keeping what it wrote and read, and hands back a file's text without its own change, for writing the hunks a reader accepted. It never reaches outside the project through a link.

  • Editing a style block's nested rules: SetRuleStyle and RemoveRuleStyle reach an @media or &:state rule, making it when there is none. SetStyle and AppendChild keep the block as it is written, and SetProp on Card.elevated writes the prop before the flags, where it wrote a call that did not parse.

  • Template::with_studio writes each element's node id on what it draws (data-wf-node, data-wf-call), as the builds do for an editor.

  • A preview's resources held in an arm: data-wf-resource="loading" or "error" on a page's root makes every resource read as in that arm.

  • contrast::ratio is public, and a theme's view names as unpaired every colour token the dark theme leaves alone, not only color-*.

  • wf commands --json reads each value's kind in a release build, where it said every path was text.

Fixes

19

  • A program's names are its own wherever it binds them. A loop's item, a lambda's parameter, a let, a caught error, an action, a const, a store or a service named like the generated code's own things (_p, e, event, document) or a browser global (Map, Set, Node, setTimeout) used to read the wrong value or stop the page from drawing: for e in entries { Link(to: "/e/{e.id}") } went to /e/undefined, and const Map = 3 threw before any page drew. Each is now spelt apart in the generated code, and the build's read-back of its own JavaScript (E901) catches a clash that slips past.

  • A store member named like what every object has (valueOf, toString, constructor) is E118, where the page threw as it drew; such a name now works as a prop, and __proto__ as a prop is E118.

  • A component call's handlers and attributes follow its root when the body's if or match draws a new one: a button wrapped in a tooltip while disabled kept its click once enabled.

  • A state may start from a derived value defined before it, where it threw as the page drew.

  • A derived function works everywhere: the pre-render, wf test and wf render painted every call to derived countOf = (id) => … blank, inside a lambda too.

  • A select keeps its value when its options are redrawn.

  • A modal reopened before its close event arrives stays open.

  • A drag whose first move leaves its element still begins, in WebKit too, and a draggable element selects no text.

  • A shortcut on a punctuation key is found by its place on a layout that types no ASCII there, so mod+, works on an Arabic keyboard.

  • A name narrowed out of null may still be set to null.

  • A member or field that does not exist is reported at its name (T06 underlines x, not the store), so the build and the editor agree.

  • V01 offers the dot for a flag written without it (Button(primary)), and no longer matches a two-letter word to any short name.

  • F04 no longer warns about a checkbox that is always disabled.

  • A binding that runs again with its value writes nothing, the browser asks about reduced motion once, and a windowed list fed an item at a time lays out once a frame, revealing after it is laid out.

  • A test's settle waits as long as it asks, not two seconds each, and an expect reads a page still moving again until it holds, for up to a second and a half. A file of fifteen browser tests went from two minutes to eighteen seconds.

  • A test file's declaration named like one of the project's is E102 where the tests are collected, where every browser test failed with a SyntaxError.

  • A prop that reads a store named like a browser global is followed, not copied once.

  • A fix's word search no longer panics on a character it would end inside.

  • Chart and QrCode are in the Data display group, so a list of the registry by group draws it once.

The guide

Every chapter is rewritten to a house style drawn from a study of developer documentation, and the chapters are ordered by what a reader is there to do: start, learn the language, build the parts of an app, ship, and look things up. The site has a front page that answers a visitor's questions in order, and its pages, sidebar and search come from the guide.

Upgrading

See chapter 51: store members named like an object's own (E118), a test declaration named like the project's (E102), where T06 is reported, output_type: "static", and smaller WebP. Run wf check.

5.11.0

#5.11.0

29 October 2026

What an editor written in WebFluent asked of the language: a handler that reads every value an event sends, gestures on a component's call, a modal's own heading and close button, source maps, a translated wf init, and icons; and tests that find a control by the name a reader hears, each test file with its own declarations.

Additions

6

  • A handler names each value its event sends (chapter 9). A component that declares event menu(key: String, x: Number, y: Number) and emit menu(k, x, y) is handled with on menu(key, x, y) { … }, each name typed as the event declares it. A handler may name fewer values than the event sends, never more: a name past the last one is the new error T22, which says what the event sends. The same holds for an api's hooks and a connection's handlers.

  • Gestures on a component's call (chapter 9). drag:, dragGroup:, dropValue:, dropAxis:, dropInside:, on receive(d), on dragmove(d), on longpress and on swipe written on a component's call land on its root element, as class: and on contextmenu already did. A component whose body is not one element has nothing for them to land on, which is the new error C07.

  • Modal.Title and .closable (chapter 9). Modal.Title { … } (and Dialog.Title) is drawn in the heading in place of title:'s words, so a heading can set a name apart in code; title: stays the dialog's name. .closable puts a close button, named Close, in the heading row. It closes the dialog as Escape does, so on close runs and visible: follows. Both work in the live page, the pre-render and the template engine.

  • Source maps (chapter 39). build.sourcemap was in the config and nothing read it. It now writes a version 3 map beside the bundle and each page's chunk (app.js.map, pages/Home.js.map), with the sources' text, so a stack trace reads back to the .wf line each statement came from. The scripts are otherwise byte for byte what they are without one.

  • wf init --locales (chapter 38). wf init my-app --locales en,ar (spa or static, the default first) starts a project translated: the i18n config and meta.lang, every visible string of the starter through t(), a language switch built from the locales, and src/translations/<locale>.json for each. A tag that is not one, a tag named twice and an empty list are refused, and so are locales for pdf and slides.

  • Three icons (chapter 28), 58 in all: locate for a panel that follows the caret, folder-off for a folder that is gone, and file-plus for New file.

For tools

4

Each is for a tool built on the compiler (chapter 38); paths are under webfluent::.

  • VERSION: the compiler's version, as wf --version prints it.

  • BuildOptions::sourcemap asks for maps whatever the config says, for an editor's preview, and codegen::sourcemap::SourceMap reads a map back and looks a place up, as a console does with a stack trace.

  • init::create_with(dir, name, &Options { template, locales }) is wf init with locales; init::create stays the form without them.

  • The language server knows a handler's names: hover gives each its type and completion offers them, where hovering e in on click(e) { … } used to show nothing. The tree-sitter grammar reads several names.

Fixes

8

  • A test finds a control by the name a reader hears (chapter 24). What is aria-hidden (a menu item's shortcut, a glyph) is left out of a name, so click "Paste" finds an item that shows Ctrl+V. A submenu's entry is named by its label, not by its items: WF.submenu points the entry's aria-labelledby at its label, for a screen reader and for click "File".

  • A test file's declarations are its own. Every test page was built with every test file's declarations, so two files under tests/ that each declared const T06 broke every test that runs in a browser ("Identifier 'T06' has already been declared"). A test now renders and runs with the project's declarations and its own file's only.

  • A closable modal's close button writes its state at once. The state followed a task later, with the close event, so opening the modal again straight after closing it did nothing.

  • A store's action named like a helper is the store's own. OpenFiles.preview(path), called from another store's action, compiled to the runtime's file preview and lost its argument. A value with a method of its own named like a list or string helper (last, first, take …) now answers for itself, with every argument.

  • A block handed to a component reads the names where it was written in wf test and the template engine, as the live page and the pre-render already did: a panel's empty text, handed to a frame with an empty flag of its own, came out as "false".

  • A Menu.Item's class: is added beside the item's own, where it wrote over wf-menu__item and the item lost its padding and its shortcut column.

  • A15 holds a control's label to its words, not to a glyph beside them that the author marks aria-hidden (Aa beside "Match case").

  • The components reference has an example of Modal.Title, .closable and Dialog.Title, so every part the registry lists has one a tool can show.

Upgrading

See chapter 46: gestures on a component that is not one element (C07), a handler's names (T22), a test file's own declarations, a control's name as a reader hears it, a block's names, a menu item's class, and a value's own method over a helper. Run wf check.

5.10.0

#5.10.0

24 October 2026

The wf init starters, rewritten to work on first use, and the compiler and runtime bugs that clicking through them turned up; what an editor built on the compiler asks of it — icons, events, a member's ///, a build of one route, a faster check; and a pre-render, a test and a PDF that draw what the live page draws.

Additions

10

  • Starters that work on first use (chapter 38). wf init spa has Day and Night themes with a switch that calls setTheme, a task list that adds a task on Enter through a Form and asks in a Modal before deleting one, a Settings page with validated fields, and tests/app.wf and tests/tasks.wf. wf init static has a validated contact form with a required agreement Checkbox, English and Arabic translations, and tests/site.wf. wf test passes in a new project.

  • A test can place a whole page (chapter 24) by its name, as it places a component (Tasks, then click "Add"), with its state, stores and handlers running. This works for a page with no route parameter whose name no component also has. In a test that acts, press "Enter" in a form's text field submits the form, and click "Name" also finds, by its name, an element whose role is a link, a tab, a menu item (a Menu.Item), an option, a tree item, a switch, a checkbox or a radio (chapter 24).

  • on blur and on focus on a page (chapter 9). A page, a component or app hears the window lose and gain focus for as long as it shows, for example to save when the window is left. Both listen on the window; on keydown and on keyup still listen on the document.

  • on auxclick, on focusin and on focusout on any element (chapter 37). on auxclick(e) hears a click with a button other than the main one (e.button == 1 is the middle button, to close a tab); on focusin and on focusout hear focus move onto or off the element or anything inside it.

  • 23 icons for editors and tools (chapter 28), 55 in all: folder, folder-plus, file, refresh, alert-circle, clock, dot, diff, book, git-branch, git-pull-request, pin, more-horizontal, window-minimize, window-maximize, outline, help-circle, collapse-all, chevron-up, globe, external-link, panel-down and panel-up. They go wherever an icon name does and are drawn in currentColor.

  • Menu.Item.danger (chapter 9), or danger: true, draws an item that cannot be undone, such as Delete or Discard, in the danger colour.

  • A Tooltip's shortcut: reaches its control (chapter 9): Tooltip("Save", shortcut: "mod+s") { Button("Save") } also gives the button aria-keyshortcuts in ARIA's spelling (Control+S, or Meta+S on Apple's systems), unless it has one.

  • A member's /// is its documentation (chapter 5). A /// comment above a state, persist, derived or action in a page, a component or a store stays with it, in .wf and .wfx alike; the parser used to drop it. A /// above anything else in a body is still dropped.

  • Portal (chapter 32). Portal(into: node) { … } draws its block into a node somebody else's code made: an editor's tooltip, a map's popup, a chart's legend. The library keeps the node's place, its keys and its focus; the page keeps what is in it. into: takes an element, a ref: handle or null; named another node the block moves there with its state, and null keeps it aside. Its handlers, emit and lifetimes belong to where it is written. Portal is now a built-in's name, so a project's own component or store of that name is reported.

  • Markdown(text).inert (chapter 37), for text somebody else wrote, such as a language server's documentation: entities are decoded and shown as text, a link is its words and a picture is left out.

For tools

10

Each is for a tool built on the compiler (chapter 38); paths are under webfluent::.

  • A build of one route. BuildOptions::only_route (Some("/posts/hello")) renders the page answering that route, for a preview that cannot wait for a whole build. With a BuildCache, a page the cache holds for its current inputs, in memory or on disk, is reused (pages_reused); any other page this session has painted is written as it was last painted and counted in the new BuildReport::pages_deferred; a page never painted is rendered. The next build without the option renders what was deferred, and its output equals a build from nothing. Without a cache it builds everything, and what was last painted is kept only in memory, so a BuildCache::on_disk reopened in a new session defers nothing.

  • A member's documentation in the tree. StateDecl, DerivedDecl and ActionDecl carry doc: Option<String>, the /// lines joined with \n; Statement::doc() and Statement::set_doc() read and set it, for a completion or a hover to show. print::statement writes a documented member under its ///, so a store whose members are documented prints back as itself. reprint and edit::rewrite_declaration replace, remove and insert a member together with its ///: a member taken out left its doc to document the next one, and one put in at the front went between the first member and its doc. print::written_start(source, &statement) is public: where a statement is written from, its /// when it has one.

  • A code's guide entry. diagnostics::codes::guide_section(code) returns a diagnostic code's section of the Diagnostics chapter as Markdown, without its heading (what wf explain prints after the summary, before setting it for a terminal), or None. The code is matched as given: T06, not t06.

  • A test's steps outside Chrome. testing::step_script(what, name, value) returns the JavaScript expression a click, type or press step evaluates in the page, which answers "ok", "none" or "no-option", so an editor's own window can find controls as wf test does.

  • A rendered test in its locale. testing::render_test takes the locale as a fourth argument (Tests::locale() is the project's default, or en), and template::render_program_fragment_in(program, data, messages, locale) renders with that locale's plural rules.

  • The framing decision. codegen::csp::frames_itself(&program), config::project::frame_options(&config) ("DENY" or "SAMEORIGIN") and the BuildConfig::frames_itself flag, which the build fills in, so a server an editor runs for its preview can send what wf serve sends.

  • A starter's files. init::Template::files() lists a starter's own files, as (path, text) pairs with the project's name still {{name}}; init::create writes them, and .gitignore, AGENTS.md and public/ beside them.

  • The registry (chapter 38): wf registry --json lists the new icons, auxclick, focusin and focusout among every element's events, and danger on Menu.Item.

  • Paged layout. paged::style::Length::Mix(points, percent) holds a calc() of both (calc(50% - 12px) is Mix(-9.0, 50.0)); Style gains has_mix() and settle_mix(w, h, main); codegen::builtin::span_class writes a Column's span class.

  • check_project_via runs its phases on scoped threads, and calls a Project's file_of and source_of up front, on the calling thread. The findings and their order are unchanged.

Fixes

29

  • A handler reads key and value (chapter 9). on keydown { if key == "Enter" { … } } passed the check and threw ReferenceError: key is not defined on the first key press, which broke Enter in the SPA starter. A handler that reads key now gets event?.key, and one that reads value gets event?.target?.value, on every kind of handler; a state, a loop item or a parameter of that name is left alone.

  • A layer that starts open no longer stops the page drawing (chapter 9). A Modal, Dialog, Popover or state-opened Menu whose visible: was true from the start asked to open before it was in the document, and threw; each now opens once it is there. A layer anchored to an element stayed clamped to the window's edge once the element scrolled away; it now hides with it (data-anchor-hidden), stays open and shows again when the element comes back. The Escape that closes an open Modal or Dialog no longer reaches the page behind it.

  • Menus and tooltips (chapter 9). Menu(label:) is the list's accessible name; the button's words come from trigger: (a Dropdown's still from label:), so a menu that visible: opens no longer draws a stray button. Each menu and each tooltip drawn gets its own id at run time (WF.uid), where every copy a for or a component drew shared one, so aria-controls and aria-describedby could name another copy's. A menu keeps its class: and its style { } class as it opens and closes.

  • Forms ask their rules (chapter 16). A Form with no bind: in a page or component with validate rules ran on submit anyway; it now stops on a failing rule and shows the messages. Each page and each copy of a component has its own form handles: a page's carried into the next page compiled, and every copy of a component shared one form. A validated Checkbox or Switch shows its message beneath it, announced and tied to the control (aria-describedby, aria-invalid). A field's character count follows a value the program sets, such as a reset.

  • Controls given a value work (chapter 16). Switch(checked: value) without bind: drew no input; it now follows the value, and its on change hears the click. A Switch's on change was never attached. A bound Checkbox or Radio with its own on change lost the binding's write; the binding now writes first and the handler runs after it.

  • Text that reads state follows it (chapter 21). Each of these was worked out once, when the page was drawn: the labels of Checkbox, Radio, Switch, Slider, DatePicker and FileUpload; a Table's caption:; Tabs.Page titles; Tooltip text; a Modal's or Dialog's title:; a Menu's trigger: and a Dropdown's label:; an Avatar's src:, alt: and initials:; a Skeleton's width:, height: and size:; and an Icon's positional name (Icon(if done { "check" } else { "clock" })). So Checkbox(label: t("…")) now changes language with setLocale. Fixed text compiles as before.

  • Stores (chapter 12). A store outlives the page that reads it first: its derived values and effects belonged to that page's scope and stopped when the reader moved on. A derived that reads one written below it in the same store follows it, where it kept its first value. The built script declares each store after the stores it uses, so a read made while the script starts never meets a store not declared yet.

  • The pre-render paints what the live page draws (chapter 26). A Checkbox, Radio or Switch is its <label> and <input>, ticked and disabled as its state starts, where only the labels' words showed. A Menu or Dropdown is its button and a hidden list, where its entries lay in the page, and a menu that state opens is its list alone. A part written with flags carries their classes (Menu.Item.danger), and Column(span: 8) its wf-col--8, where every column was painted the same width. disabled, required and controls are written only when true, here and in the template engine, so Button("Go", disabled: false) is not a dead button. .pop() and .shift() are evaluated on a list the build knows.

  • A test that looks reads the page as a reader does (chapter 24). The template engine draws a Menu or Dropdown as its button and hidden list, keyLabel("mod+shift+p") as the build writes it (Ctrl+Shift+P), and a t() with a count in the default locale's CLDR form. expect decodes every numeric entity and the common named ones, so expect "It isn't" matches. In a test that acts, expect treats any run of white space as one space, as a test that looks already did.

  • Column spans leave room for the gap (chapter 37). span: 8 and span: 4 in a Row with a gap came to 100% plus the gap, and the second always wrapped; each span now gives up its share of the gap, a gap or a span given per breakpoint too. A PDF lays a Column out at its span:, where every column came out equal, and the PDF engine's calc() is a real parser: no spaces needed, nested parentheses, unary minus, functions inside, and a sum of a percentage and points resolved against the box it lands in (chapter 34).

  • The Navbar follows the theme (chapter 37). Its background was a fixed translucent white; it is now the theme's surface, and its text the theme's text colour.

  • setLocale is remembered (chapter 21) across page loads, in localStorage under wf:locale, so a static site keeps the reader's language from page to page. A ?lang= address still wins, without changing the saved choice.

  • A site may frame its own pages (chapter 23). A Frame whose src: is site-relative ("/preview/", "/embed/{id}") was refused by the site's own headers. A project that places one is served X-Frame-Options: SAMEORIGIN by wf serve, and its _headers says the same with frame-ancestors 'self'; every other project keeps DENY and 'none'.

  • An Avatar's src: is checked like any other src: (chapter 23): a run-time value goes through WF.safeUrl.

  • Long keyed lists no longer stall as they grow (chapter 20). A keyed for read the place of every item it kept before each change, so a 960-line log appended line by line froze the page for 3.5 s. Only items whose index changes are measured now; a list that only grows at its end measures nothing.

  • A Splitter moves from where it is drawn (chapter 9). A drag or an arrow key starts from the region's drawn size, not the bound value, and a reset writes reset: as given, so reset: 0 can mean the region's default share.

  • () => … takes no arguments (chapter 14). It was typed as taking one, so it could fail to fit a script parameter whose JSDoc says () => boolean.

  • webfluent on Windows (chapter 2). A bare wf runs WF.msc, the Windows Firewall console, which comes first on PATH. The .msi, the release zip and install.ps1 now also install the binary as webfluent.exe, so webfluent build works; wf.exe does too. The .msi now keeps one UpgradeCode, where each release had its own, so the next one replaces it instead of installing beside it. The Node binding looks for webfluent.exe and wf.exe by their full names (chapter 35).

  • The check does less (chapter 38). The env lint lexes only a file whose text could name env.…, and the output checks work out what a build can evaluate only once they find a Chart or a QrCode: on Halyard the check went from 28 ms to 18 ms. Its phases also run side by side, which helps most on a busy machine.

  • A build into another folder reuses the cache (chapter 38). The cache's key held the output folder, so two builds of one project into different folders, as an editor's previews are, never shared a page.

  • Markdown links are checked, and backslash escapes work (chapter 27). Every link and picture in Markdown goes through the scheme check the rest of a page does, so [x](javascript:…) is drawn as its words. A backslash before punctuation draws that character (\* is *, not emphasis), as CommonMark has it, and the build and the browser draw Markdown alike, line breaks and white space included.

  • Escape goes to the newest layer that can take it (chapter 9). A tooltip under the pointer no longer takes Escape from the page (an editor's completion list behind a toolbar button lost it); it hides and lets the key go on. An open Modal or Dialog is the newest layer, so its Escape comes before a popover's beneath it, and a press inside it no longer closes that popover. on close on a modal is its event, with no V09.

  • Every built-in takes what any element takes (chapter 37). role:, tabindex:, aria-*, data-* and on handlers reached a Popover, Menu, Tooltip, Modal, VirtualList, Splitter, Tabs, Sidebar, Slider and the rest only in part, or not at all; each now writes them on its element, in the live page, the pre-render and the template engine alike, as C04 says. disabled: true disables a Slider, DatePicker or FileUpload. An html: written on an element is an attribute, never markup.

  • A long list drawn before its box is laid out (chapter 37) paints the right rows in its first frame, the row reveal: names among them, where it drew about forty and trimmed them a frame later.

  • A pre-rendered modal has its title as its heading, as the live page draws it, not as a title= tooltip; an IconButton's own title: wins over its label on every page.

  • A test reads a page as a reader does (chapter 24). expect reads a plain render as a browser lays it out: elements that touch read as touching, where the render's line breaks put a space between them. A test run in a browser loads the project's own stylesheets and serves public/ beside the page, as the built page does.

  • A record with all its fields defaulted is Offers() (chapter 12), wherever an expression goes, a prop's default among them; a left-out field of a default record is filled in, in the pre-render too.

  • data-x: true is data-x="true" on every page, given to an element or passed through a component's call, and a call's data-*, aria-*, id: and class: reach the component's root in the template engine.

  • A local is its own (chapter 12). A let, a parameter or a loop's name in a store's action that shares a member's name was compiled to the member, so writing it wrote the store; in a page or a component, one that shared a prop's name read the prop.

Upgrading

See chapter 46: Markdown's backslash escapes and checked links, attributes that built-ins now write, a modal's Escape and painted title, column spans that leave room for the gap, a Menu's label: that no longer names its button, a form without bind: that asks its rules, a bound box whose on change wrote the value itself, and pre-rendered HTML and test snapshots that now match the live page are what a project may notice. On Windows, type webfluent and uninstall an older MSI. Run wf check.

5.9.0

#5.9.0

22 October 2026

An app's frame — layers, shortcuts, gestures, long lists, workers, frames — and the compiler as a library an editor, a visual builder or an agent builds on, each piece also a wf command.

Additions

12

  • Layers (chapter 9). Popover, a Menu at its button, at an anchor or at a point (at:, for a context menu), with submenus, and Tooltip, drawn in the browser's top layer, so nothing clips or covers them. Each flips and slides to stay on screen; Escape closes the top one, a press outside closes what it is outside of, and focus goes back where it was.

  • Shortcuts for an app (chapter 9). mod is ⌘ on Apple's systems and Ctrl elsewhere; chords ("mod+k mod+s"); keyIs(e, …) and keyLabel(…) for a table of commands that drives menus and a palette; a page, a component or app hears keydown and the window's events itself; trapFocus keeps focus inside a panel.

  • Gestures (chapter 9). drag: and on receive(d) with a ghost, edge scroll and Escape; on longpress, on swipe; and Splitter between two regions, with its size kept.

  • VirtualList (chapter 37): a long list drawn a window at a time, rows measured or of a fixed height, reveal: to scroll one into view, and V12 for a long list that is not windowed.

  • worker (chapter 18): a Web Worker held like a connection, asked with .request(method, params) and heard with on message, restarted when it crashes; a store may hold connections.

  • Frame (chapter 28): another page inside this one, its on message only that page's; A17 for a frame with no title.

  • persist follows its key (chapter 12): key: Project.id keeps one value per project; in: .app names a storage the project gives itself, which may answer later.

  • The policy names an app's own schemes and WebAssembly (chapter 33): meta.connect and meta.frame take ipc: or wfpreview:, meta.wasm lets a page compile WebAssembly, meta.style_elements lets a script write <style>.

  • A build cache: only the pages an edit changed are pre-rendered again, in a session (BuildCache::in_memory) or across runs.

  • An Image's literal src: in public/ is processed as an image declaration is: each width and format, its size, a <picture>.

  • Previews of what a reader asked for: data-wf-motion="reduce" on the page's root stills every animation as prefers-reduced-motion does, and data-wf-validation="shown" shows every field's message as a failed submit does.

  • Plurals by CLDR (chapter 21): the build picks each count's form by the default locale's rules (CLDR 48, the same table the browser's Intl.PluralRules reads), and exactly none is key.zero in any language.

For tools

5

Every one reads the project through a Vfs, so an editor's unsaved buffers count (chapter 38).

  • Printing and reprinting: webfluent::print, reprint and edit::rewrite_* change an element, a statement or a declaration in the tree and write the smallest edit, every other byte as it was.

  • The node map both ways: each element's id, place, parent and what it is inside; the node at a caret; the Layers tree; wf build --studio stamps data-wf-node and writes nodes.json.

  • Data an inspector draws from, each a command too: wf components (every component, built-in and the project's), wf theme (every token, its uses and its contrast), wf motion, wf rules (the validate rules, named patterns, every state's rules), wf scope FILE:LINE (what can be read at a place, typed), wf translations (what each locale lacks, what nothing names; --plurals), wf assets, wf config, wf commands; and style values read into their parts and written back.

  • wf fix: one decided fix on every family that has a certain one, and fix-all per family.

  • An agent's change set and context: webfluent::agent holds an agent's edits apart from the working tree, builds them before anyone reads them, and gives them back by file or by hunk; wf context is what an agent is given — the files, the problems, the components, the theme, the config with only its public env, and the guide.

Fixes

8

  • A project's own animation (Card(animate: .Drop)) did nothing on an element that stood still; it plays.

  • A refined type's open end (Number(0..10) took 10) and its after: and before: were not checked as the reader typed.

  • Pre-rendered controls dropped name: and autocomplete:, and an Input with its own id: got a second one, so its label named nothing.

  • A locale missing one plural form showed the default locale's form, two languages on one page; a site whose default locale is right to left was served left to right until a script ran; ar-EG was not right to left.

  • A let in an action, a handler, an effect or a timer was offered by completion everywhere in its page, and listed as a store's member.

  • I01 and I02 missed a t() in a page's header; I03 said a reader sees the key, where they see the default locale's message.

  • Unsafe.Html without a sanitize(…) elsewhere put nothing in; a typo was reported once per check that found it; a page's own state env read the project's env.

  • A comma between two style declarations made the browser drop both; it is an error.

Upgrading

See chapter 46: a comma between style declarations, a field that accepted its range's open end, an animation that now plays, a zero message that now shows, and a right-to-left default locale are what a project may notice. Run wf check.

5.8.0

#5.8.0

19 October 2026

A state that copies a live value says so, a script's values reach a page, and the guide shows a project as a desktop app.

Additions

2

  • X06: a state that copies a live value once. state clock = now(every: 1.seconds) holds the moment the page opened and never ticks again, so every «… ago» built from it freezes; the same holds for viewport, query, hash, theme, network and update. The warning names it where it is written, and when nothing assigns, binds or changes the state, the quick fix declares it derived, which follows the live value. A state the program does change — state tab = query.tab ?? "all" that a click then sets — is a starting value on purpose and draws nothing.

  • Desktop apps, in the guide. Chapter 33 shows a project as a Tauri or an Electron app: the build settings a desktop needs, setting up each shell, the dev loop, calling the native side through typed functions in a script under src/, events, plugins, the security policy and packaging. The chapters after it move up one, to 34–49.

Fixes

1

  • A script's values reach a page. A value a project script declares at its top level — const VERSION = "1", a let, a var, window.ready = … — compiled to a signal read, _VERSION(), wherever a page or a component read it: in text, a splice, a derived, an if or show condition, an attribute, a handler. Nothing declares _VERSION, so the page threw as it drew (_VERSION is not defined), and wf check passed. A call to a script's function was right; a function handed on as a value was not. Every name a script declares is now its own global, read as itself, unless the page or component declares the same name, whose state still wins.

Upgrading

Nothing to change. A function written only to get a script's value onto a page can go back to being the value. A build may now warn X06 on a state whose first value reads a live one; making it derived is the fix.

5.7.0

#5.7.0

18 October 2026

A resource asked again for what it shows keeps it on the page.

Changes

5

  • A refresh keeps the page. Every time a resource was asked again — on: .focus, on: .interval(…), reload(), invalidate() — it went back to loading, so a match over it took the page down to its loading arm and built the ready arm again: a skeleton flash, the scroll lost, the focus and an open sheet gone, every row and every component in it new. Asking again for the same request is now a refresh: the resource stays ready and keeps its data while it runs, and the answer is drawn in place. loading is for a first load — nothing has arrived yet — and for a request that changed: an address or an argument that reads state now names something else (another environment, another page number), where what is on screen would be the wrong data.

  • A refresh that fails keeps the data. The resource stays ready and sets name.error, which the next answer clears, so the ready arm can say the data is stale (if rows.error != null { Alert(…).warning }). A first load that fails is error, as it was.

  • A match arm's binding is live. ready(d) and error(e) were handed their value once, when the arm was drawn. A read of the binding now follows the resource: text, attributes, if, if let, a keyed for … by and a component's props inside the arm change in place when a refresh lands, and the arm is drawn again only when the arm itself changes — loading, ready, error. An enum's arm follows a new payload of the same case the same way (.failed(r) kept showing the first reason it was drawn with), and else is one arm, whichever keys it stands for.

  • An if let binding is live. if let u = selected { Sheet(u) } showed the value it was drawn with until selected went to null and back; another value now reaches the branch in place.

  • A keyed list keeps an item for as long as its key is in it. An item whose value changed under the same key — every row of a refreshed response, which is all new objects — was built again, its focus and its components' state with it. It now keeps its nodes, and its body reads the item and the index live. A row a refresh did not change is not even visited: what an answer has in common with the data shown is kept as the same objects (an item matched by its id, or by its value, or by its place), so an answer that changed nothing redraws nothing.

Additions

1

  • name.refreshing and name.pending. refreshing is true while a refresh runs with the data still shown; pending is true while any request of the resource runs, the first load included. Both are Bools, live wherever they are read. With paginate:, the next page is a refresh: loadMore() keeps the gathered items on the page, and another loadMore() while a page is on its way is ignored.

Fixes

2

  • ready(users) over resource users reads the data. An arm's binding named like its resource — the guide's own example — compiled to the resource's handle, so users.length was undefined and for user in users drew nothing.

  • on: and cache: on a resource over an address are policies. fetch("/api/rows", on: .focus) handed the runtime the word "focus", so such a resource never looked again — on focus, on reconnect or on an interval — and its cache: was not read as a policy either. They are read as an endpoint's are.

Upgrading

Nothing to change. What a page did to live through a refresh can go: a sheet or a form kept outside the match with a snapshot of the data, a derived copy held so the arm would not draw again. A page that wants a spinner on every refresh shows one for name.refreshing. A hand-written WF.match arm is handed its value as before, and an accessor of it as a second argument; WF.each keeps a keyed item's nodes under a new value with live: true, which is what a compiled for … by asks for.

5.6.2

#5.6.2

17 October 2026

What a branch inside a branch drew goes when the outer one does.

Fixes

1

  • A branch takes everything it holds when it goes. An if, if let, match or for at the top of another's body — directly in it, not inside an element — draws into the same parent as the outer one. The outer one remembered the nodes it drew when it drew them and took only those away, so what the inner one drew later stayed on the page: if let m = picked { if act == null { Sheet(m) } } left the sheet showing once act went back to null and then picked did, and a tab whose match over a resource drew again on a refetch left its list beside the next tab's. The same held for if … else if … else (the arm drawn last stayed beside the first), for a keyed list item with an if of its own (moved, and taken away, without what the if drew since), for a list inside a list item, and for a scoped slot's fill. Each now draws between two markers of its own and takes what lies between them, as it is when it changes. Exit animations, and a pre-rendered page taken over in place, work as they did.

Upgrading

Nothing to change. A wrapper written only to keep a nested branch apart — a Stack styled display: contents around a tab's match, or a branch flattened into one if let over a derived value — can go.

5.6.1

#5.6.1

17 October 2026

Two things that compiled and then did not work in the browser.

Fixes

2

  • A resource read in a label follows the resource. Whether text or an attribute is drawn live was decided by the reads a state compiles to, and a resource's or a connection's values are read through its handle, so a label that read only one was worked out once, while it was loading: Button(if plan.data != null { "Request approval" } else { "Deploy" }) stayed "Deploy" after the plan arrived, and Text("{rows.state}") stayed "loading". name.state, .data, .error and a connection's .messages are now live in text, a splice and an attribute alike.

  • A list's key may read the index. for e, n in list by n threw before the list drew (_n is not defined), and wf check passed: the key was compiled with the item alone. It is given the item and the index, so by n works and so does by "{e.id}-{n}" — though a key of the index alone moves with the position, and keeps nothing across an insert.

Upgrading

Nothing to change. A derived value written only to make a resource's label live can go back into the label.

5.6.0

#5.6.0

17 October 2026

A name the language has is not a program's to declare.

Changes

2

  • A name the language already has is E118, where it is declared. A page's state env compiled every read to the build's settings and every write to the state: "{env}" showed [object Object], env == "prod" was never true, and wf check said nothing. A loop's t hid the translation function inside the loop the same way. Such a name is now refused as a state, derived, persist or let, a prop, a route or action parameter, a loop item, a lambda's parameter, a binding of if let, match or a slot, and as a top-level const, data, image, store or api. The names are env, params, locale and dir; the values the browser keeps current (now, viewport, query, hash, theme, network, update); the language's functions (t, format, ago, log, navigate, fetch, uuid, every, after, …); the words a statement is written with (state, action, let, if, show, match, style, on, …); and, at the top level, the runtime's WF. The message suggests a name of your own where there is a usual one — target for env, search for query, scheme for theme. event, e, value, key and the browser's globals stay yours, and so does any name as a field, a map key or an enum case.

  • A top-level const env is refused where it is written. It was refused only when the build read its own bundle back, as "a bug in WebFluent" (E901).

Upgrading

A program that declares one of these names stops at E118, on the line that declares it; rename it and its reads. The usual ones are a loop's or a lambda's t (for t in todos, items.filter(t => …) — todo, item), state query (search), persist theme (scheme), a route parameter or state env (target, stage) and an action named update (edit). The guide, the examples and the site were renamed the same way.

5.5.0

#5.5.0

16 October 2026

A service read from its OpenAPI document is typed as well as one written by hand, and a browser run leaves nothing behind.

Additions

6

  • A string with cases is an enum. {"type": "string", "enum": ["prod", "test"]} — what utoipa writes for a Rust enum — was imported as an empty record, so Text("{e.env}") showed [object Object] and drew T20. It is now enum Env { prod, test }, whose cases are the strings the server sends. When a case cannot be written as a name ("operate.flags", a digit first, true), the schema is a String wherever it is named.

  • A value that may be null is T?, however the document says so. OpenAPI 3.1's "type": ["string", "null"] was Any?; it is String?, and the same holds for numbers, booleans and lists. A oneOf (or anyOf) of { "type": "null" } and a $ref is that type's ?, 3.0's "nullable": true counts beside a type, an allOf or a $ref, and a record or an enum whose own schema allows null is T? wherever it is named.

  • allOf is a record that extends another. [{ "$ref": "…/EnvSummary" }, { "properties": … }] is type ServerDetail = EnvSummary { … }; a second record it names and every part written in place are fields of its own, and what the schema around a part requires, the part's fields answer to.

  • A string's format is the language's type for what the server sends. date-time is a DateTime, date a Date, uuid a Uuid, email an Email, uri a Url — in a response, and in every record only responses reach. What the program sends (a parameter, a request body, and every record one reaches, but for its readOnly fields) keeps String, so a route parameter or an input's text can still be sent. time stays a String: JSON Schema's carries an offset Time does not read.

  • Shared parameters and request bodies are read. A parameter or a body that is a $ref into components was dropped, so a call passing it was T10; it is what its $ref names, and a body is required when the document says so.

  • Anything else a schema names is the type it reads as. A named oneOf, an alias of another schema, or a plain string or number declares nothing, instead of an empty record whose every field read was T05.

Fixes

3

  • if let and a case's payload are names in their whole block. if let why = e.reason { Row { Pill(why) } } drew V01 ("nothing in scope declares why"), and so did .failed(why) { … } in a match; both are now in scope however deep the element that reads them.

  • A button named by the Text in its block draws no A05. Button { Icon("link") Text("Continue") } — and a Text in a branch, or in a component the block places — names the button. A Tooltip's words, a custom element's tag and a lone Badge still do not.

  • wf verify and wf test leave no browser profile behind. Each run that started Chrome left its ~150 MB profile in the temporary directory; where /tmp is memory, a day of test runs filled it and the swap behind it. Chrome is now started with its background downloads off, asked to close before it is stopped, and its profile is removed; each browser has a profile of its own.

Upgrading

A specification's nullable values are now T?, so a read that ignored null — Text(e.reason.toUpperCase()) — is a T04 where it compiled before; ?., ?? or if let says what to do instead. A response field with a format is now a DateTime, Url and so on, and a String assigned to one is T01.

5.4.0

#5.4.0

9 October 2026

A page may embed a frame from another site — a video player, a map — and the policy that ships beside it says so.

Additions

1

  • meta.frame. With "build": { "csp": true } the policy is default-src 'self', so a frame from anywhere else — a YouTube or Vimeo player, a map — was blocked by the page that held it. meta.frame names the origins a page may embed, as meta.img does for images, and they join frame-src in the meta tag and in _headers: "frame": ["https://www.youtube-nocookie.com"]. An entry with a path or a keyword is E111.

The site

3

  • The landing page has a video: Rethinking the web layout.

  • The fonts are served from the site rather than from Google Fonts, and preloaded with the page: a stylesheet on another origin held up every page's first paint by about a second on a phone.

  • The "Read the chapter" links on the landing page's cards, and the language switch, carry an accessible name that says where they go.

5.3.5

#5.3.5

6 October 2026

A script nothing waits for no longer counts against how soon a page is ready.

Additions

1

  • "load": "after" on a meta.scripts entry. An analytics tag listed in the HTML is fetched while the page is, even with async, and a page's speed is measured against everything it asked for before it first painted: Google's 174 KB tag added more than a second to a phone's Largest Contentful Paint on a page that was otherwise ready. A script marked "load": "after" has no tag in the HTML; the runtime asks for it once the page has loaded and drawn its first frame, with its meta.integrity hash when it has one. Its origin stays in the policy. A module, or a script whose globals .wf calls, cannot load after the page (E111).

5.3.4

#5.3.4

6 October 2026

A static page is no longer painted twice.

Fixes

2

  • A pre-rendered page is taken over in place. When a static build's script arrived it drew the whole page again and replaced the one already on screen. The reader saw nothing change, but the browser painted the page a second time — and once a web font had arrived, the second paint of the largest paragraph or image was larger than the first, so it became the page's Largest Contentful Paint. On a phone a page that was readable in under a second scored an LCP of 3.6 s. The script now draws beside the painted page and takes it over: an element nothing holds stays exactly as painted, its attributes brought up to date; one a handler, an effect, a ref, a widget or a list holds is put where the painted one stood. The first paint stays the largest, and the reader keeps their scroll, focus and selection. A page that cannot be matched is drawn again whole, as before.

  • Under wf serve, a takeover is checked. The runtime compares the page it took over with the one it drew, and says so in the console when they differ.

5.3.3

#5.3.3

6 October 2026

Fixes found getting ready for launch, and the project's new terms.

5.x is the stable line. From the first launch video until four weeks after it, releases are patch-only and batched at most weekly — no syntax changes and no breaking changes.

License

1

  • WebFluent is MPL-2.0, no longer GPL-3.0. Changes to WebFluent's own files stay open; using it in a closed product is fine. The sites, PDFs and slide decks you build with it are yours, under any license you choose.

Fixes

5

  • No empty second page. A PDF shorter than one page came out as two: the baseline's body { min-height: 100vh } was measured against the paper while the engine laid out inside the margins. The body is the flow that runs across pages, so a minimum height no longer applies to it.

  • wf render with no data renders with none. Without --data it read standard input regardless, so it waited on the keyboard, and an empty pipe was "Invalid JSON data". Nothing piped in, or an empty pipe, is now {}.

  • A responsive layout in a template. wf render and the Template API wrote a responsive prop's rules (Grid(columns: { base: 1, md: 3 })) but not the class that applies them, so the layout stayed at its narrowest.

  • A page's .html address. With build.clean_urls: "file", opening contact.html (or contact/index.html) by its own address drew the 404 page once the router loaded. It now shows the page, and the address bar reads /contact.

  • A06 ("Link has no text content") counts text a for, if, show or match draws inside the link, and an aria-label.

The project

5

  • One home: every link points at https://webfluent.monzeromer.dev.

  • A gallery of real outputs at /showcase, rebuilt on every release.

  • examples/videos/, the projects the launch videos are recorded from, built in CI.

  • A PDF benchmark against headless Chrome, bench/pdf/RESULTS.md, run with just bench-pdf.

  • A test that fails if the previous major version is named as current.

5.3.2

#5.3.2

6 October 2026

An image from another origin can be allowed by the policy the build ships.

`meta.img`, the origins a page may load images from

3

  • "img": ["https://www.googletagmanager.com"] adds those origins to the policy's img-src. The policy allowed images only from the site itself and data: URIs, and no setting could widen it: a CDN's pictures, or the tracking pixels a tag requests (googletagmanager.com/a, /td), were blocked, and Google's Tag Assistant reported each one.

  • An entry is an origin: https://images.example.com, or https://*.example.com for its subdomains. One with a path, a keyword or a scheme a picture is not fetched over (wss:) is E111.

  • The security chapter's tag-manager example adds Google Analytics' image origins beside its connect ones.

5.3.1

#5.3.1

6 October 2026

A script nothing waits for no longer holds up the page.

`async` for `meta.scripts`

4

  • { "src": "…", "async": true } loads a library with <script async> instead of defer. Deferred scripts run in order, and every meta.scripts entry is linked ahead of the compiled code — so a large library nothing on the page uses, such as Google's 175 KB gtag.js, held the page's code, and the first full paint, until it had arrived. On a slow phone that was over a second of largest-contentful-paint. An async script runs whenever it arrives, as the vendors' own snippets load it.

  • A module, or a script whose globals .wf code calls, cannot be async — the one is imported by the page's loader, the other might arrive after the code that calls it — and is E111.

  • The security chapter's tag-manager example loads gtag.js this way.

  • For the Rust API: ScriptSpec gains a public is_async field, so code that builds one with a struct literal adds is_async: false.

5.3.0

#5.3.0

6 October 2026

What a search engine and a link preview read, said in full by the build — so a site needs no step after wf build to be found, shared and fast.

Who the site belongs to

2

  • meta.owner: "person" publishes the site under a Person instead of an Organization: the WebSite's publisher, and on a personal site every WebPage's about. job_title is the person's jobTitle; same_as lists their profiles elsewhere.

  • meta.owner_details adds any other schema.org property to that node as written — alternateName, email, worksFor, alumniOf, knowsAbout, logo. What the node is (@type, @id, name, url) and what other settings write (jobTitle, sameAs) are refused (E111). Values are escaped for the <script> block they sit in.

The sharing card

3

  • og:image:width and og:image:height are read from the image when it is in public/.

  • og:image:alt and twitter:image:alt from a page's image_alt: or meta.image_alt.

  • og:locale is written as Open Graph reads it (en → en_US, en-GB → en_GB), with an og:locale:alternate for each other locale.

Addresses that do not redirect

1

  • build.clean_urls. A static build writes /contact as contact/index.html, and a host such as GitHub Pages answers /contact with a 301. "file" also writes contact.html; "directory" names every route /contact/ — canonical, og:url, sitemap, breadcrumbs and every link to a page — so the canonical address is never one that redirects.

Files asked for early

1

  • meta.preload lists files on the site to fetch with the page: each is a <link rel="preload"> in every head, ahead of the stylesheets, as from its extension, and crossorigin for a font. A font a project .css file's @font-face names no longer waits for styles.css to arrive. A path on another origin is E111.

Where a page may send requests

1

  • meta.connect names the origins a page may send requests to besides its own — an API on another domain, an analytics endpoint — as the policy's connect-src: https://api.example.com, or https://*.google-analytics.com for a domain's subdomains. Until now the policy left a page only its own origin, with no way to widen it. An entry with a path, or a keyword, is E111.

The documentation site

1

  • Moves to webfluent.monzeromer.dev. It was still built for the /WebFluent base path, so its internal links and search index 404'd.

5.2.0

#5.2.0

4 October 2026

A PDF is the page, printed. The PDF and slide writers are replaced by one paged layout engine: the program is rendered to the HTML and CSS a template renders, and the compiler lays that out on paper itself — the real cascade, block, flex and grid layout, shaped and bidirectional text, pagination, and a PDF with embedded font subsets, an outline and links. No browser, no external tool. A design that works on the web works on paper.

The engine

5

  • CSS, as the page has it. The engine's rules for every built-in, the theme's tokens, the project's .css files and every style { } block, through a cascade with combinators, attribute selectors, :first-child/:nth-child, specificity, inheritance, var(), em, rem, % and ::before/::after. @media print applies.

  • Layout. Block, flex and grid, absolute positioning, gap, min-/max- sizes, aspect-ratio, inline-blocks on a line, tables sized by their content, list markers.

  • Text. Shaped (ligatures, kerning, Arabic joining), bidirectional, broken at Unicode's opportunities, justified. A right-to-left document mirrors its rows, grids, tables and list markers.

  • Paint. Gradients with any number of stops, background pictures, per-side borders with radii, shadows, opacity, clipping, rotation; PNG, JPEG, WebP, GIF and SVG (kept vector).

  • Pagination. Lines kept two to a side, tables broken between rows with their header repeated, side-by-side columns broken each on its own, headings kept with what follows, break-inside: avoid, PageBreak and break-before/break-after.

New elements

4

  • Header(on:), Footer(on:) with page and pages in scope; Background(on:), drawn edge to edge behind each page; Watermark("DRAFT").

  • TableOfContents(levels:, title:) — headings with the page each lands on, dotted leaders, linked.

  • Chart(kind: .bar | .line | .area | .pie | .donut, …) and QrCode(value), vector graphics in a PDF, and SVG on a web page where what they read is known at build time.

  • Document(size:, landscape, margin:, title:, author:, subject:, keywords:, lang:) names the paper and the file's metadata.

Fonts

Liberation Sans, Serif and Mono are built into wf, so Helvetica, Arial, sans-serif, Times and monospace resolve with nothing installed. .ttf/.otf files under fonts/ (or src/fonts/, public/fonts/, pdf.fonts) and local @font-face rules are used by their family name, variable fonts at the asked weight. A character no named face has is drawn from one that has it; the build names any family taken from the machine, and "system_fonts": false forbids it.

Decks

3

  • A Presentation holds for, if and slide components: a deck writes its openers and footers once and makes a slide per item of its data.

  • A page's state and derived values have their values on paper — and in any template render — so a slide shows a figure worked out from a data file. Data handed to a render wins over either.

  • :is() and :where() in the paged cascade. The engine's slide heading sizes use :where, and the slide margin is a default, so a deck's own classes always win.

Templates

1

  • render_pdf_report and render_slides_report return a PdfReport: the bytes, the page count, each page's text in reading order and the notes. A template reads fonts and pictures from beside its files.

The editor

1

  • The language server knows what the project writes. In a pdf or slides project, completion offers only what paper draws — no Button, no on click, no resource — a Presentation is offered its slides and the project's slide components, and hover says when an element is not drawn in this output and why. page and pages are names inside a Header, Footer or Background. On a web project the paper-only elements are offered last.

Fixes

13

  • Right to left, a flex row runs from the right. taffy already mirrors a row under direction: rtl; the engine reversed it again, so rows in an Arabic PDF came out left to right.

  • A keyed list no longer draws a row twice when a handler that runs as a row leaves — an input's blur — writes the list while it is being drawn.

  • A Link whose to has a query (/?show=open) is active only when the address has those values too; a row of filter links no longer marks every one as the current page.

  • Attributes on a component's call reach its root — class:, aria-*, data-*, id, role, title, hidden — on the live page and in the static paint; before, they were dropped without a word. A component that declares a prop of that name still receives it.

  • A Bool prop given a condition — outlined: theme != "light" — follows it, instead of becoming an attribute.

  • The static paint draws what the live page does: a component's derived that reads a store, a class: list with one entry only the browser knows, hidden:.

  • On a page with a layout, the skip link jumps past the layout's chrome to where the page starts.

  • wf test: expect reads the text a reader sees, not the markup; a date or money literal draws; data: seeds stores in a test that clicks; wf test tests/x.wf runs that file in its project.

  • A validate rule's message may be t("key"), and a rule's argument that reads state is read when it checks.

  • xs.filter(x => x != null) is a list of what is there ([T?] to [T]).

  • wf fmt leaves arguments laid out over lines as written.

  • The breadcrumb JSON-LD lists only pages a reader can open; a page's head { } counts as reading its values (no false U02); a store action called in the store's own initial value is named for what it is.

  • Host(title:) is the title attribute.

Diagnostics

2

  • V11: a component of the project's own named like a built-in (component Chart), which shadows it.

  • E109 now refuses only what a page means only in a browser; everything static draws.

Examples

examples/documents/ holds three reference documents: a nine-page Halyard platform report (dark cover, contents, charts, a 64-row table that repeats its header, incidents, a QR code), an invoice (band, watermark, repeated header, totals kept whole), and an Arabic résumé laid out right to left.

examples/decks/ holds three slide decks: WebFluent itself in the docs site's design system, Halyard's quarterly review drawn from the report's data (a slide per incident from a for), and an Arabic workshop.

Tutorials

The cookbook is now Tutorials: three projects built step by step, each complete under examples/tutorials/ and none needing a server — Todos (easy), Field Notes, a statically built notes site (medium), and Pocket, a budget tracker with forms, i18n and offline (hard). A test holds every file the chapter shows to the project it comes from.

Editors

The tree-sitter grammars and the VS Code grammar highlight the new elements.

5.1.1

#5.1.1

4 October 2026

The language server says which version it is.

New

1

  • wf-lsp --version (and -V) prints the version; --help says what the binary is and how an editor runs it. An editor runs the wf-lsp on your PATH before a downloaded release, and cargo install leaves an old one there when wf is updated — so an editor could report findings the compiler dropped long ago (an unknown Host) while wf check found nothing. Comparing wf-lsp --version with wf --version now shows it.

Documentation

1

  • Troubleshooting names that symptom and its fix, and the CLI guide says to keep wf-lsp at the version of wf.

5.1.0

#5.1.0

4 October 2026

The language server catches up with the language. Everything the compiler knows — every declaration, every built-in type's methods, every keyword in every place — the editor now completes, explains, finds and renames, and it gains formatting, references, signature help, folding, inlay types and semantic highlighting. What it offers is read from tables the compiler publishes, each held by a test to the code that reads it, so the editor cannot fall behind the compiler again.

The editor

5

  • Markdown pages are checked as you type, and a finding is checked again when a file it depends on changes: a translation, a .env, a project script, a file in public/.

  • Go to definition, find references, highlight and rename work for every declaration — a type, an enum and its cases, a record's field, a const, a data file, an animation, a service's endpoint, a route parameter, a socket, a form or element handle — and inside a string's {…} splices.

  • Completion knows the fields of a record and the methods of each built-in type (due. offers plus, isBefore, …), a service's endpoints, the keywords each place allows (a store's, an action's, a test's steps), type names after :, duration units after a number, validate rules, persist settings, format styles, responsive steps, Host tags, key names in on key("…"), translation keys in t("…"), public env. names, and codes in // wf-allow(.

  • Hover says what every name is: Host and the props every element takes, a function the language gives, every keyword, a record's field, an endpoint, a case, an image's size.

  • New: formatting (wf fmt on the open file), find references, document highlights, signature help inside a call, folding, inlay hints for the type of a state or derived value written without one, and semantic highlighting — a name coloured by what it resolves to.

The compiler

2

  • V10: a Host(tag: …) it does not make used to be a div without a word; it is now a warning naming the tags it makes.

  • An image is typed: hero.widht is a T05, with the fields an image has.

5.0.1

#5.0.1

3 October 2026

A new project comes with the language reference its coding agent needs.

New

1

  • wf init writes AGENTS.md: the WebFluent language reference, in the file an AI coding agent reads before it changes a project, headed by the version of the wf that made it. An assistant asked to add a page writes this WebFluent — its flags, its slots, its checks — instead of guessing at a language it may never have seen. An older project can take the current one from the repository.

Changed

1

  • AGENTS.md names wf init's copy and tests/ in the project layout, pins the Rust engine at version 5, says what moving from 4 to 5 asks (wf check, quick fixes, lints and // wf-allow while a project catches up), and that a service call with an empty path parameter is not sent.

Tooling

1

  • CI's check that every wf init template builds clean looked for 4.x's warning format, so it could no longer fail on a warning; it runs wf check --deny-warnings and requires the new AGENTS.md.

5.0.0

#5.0.0

3 October 2026

The compiler now refuses most of what used to compile and then fail in the browser, says so with one kind of finding everywhere — the build, wf check, the editor, a CI annotation — and offers the fix where it knows it. This is a major release because a project that built under 4.x may stop on errors it always had: start with wf check, and read Upgrading.

One finding, everywhere

5

  • Every finding has a code, a place and a span, a hint, the other places it concerns and, where the fix is known, the edits that make it. The build renders them as a compiler does — the line, the part underlined, a link to the code's entry — and sums them up in one line. A build that stops on its findings exits 1; one that could not run, 2.

  • Every file is read, even when another does not parse: the parser picks up at the next declaration, so one build shows every mistake once.

  • wf check runs every check and writes nothing. --format json, sarif or github on wf build and wf check writes the findings for a tool, code scanning or a pull request; --deny-warnings fails on a warning. wf explain CODE prints a code's entry.

  • Quick fixes in the editor, and fixes in the JSON: the nearest name for a misspelt field, member, method, variable, component or flag; ?. for a value that may be null; missing props; missing match arms; a bare word written as its flag; alt: ""; an _ before a name nothing reads.

  • lints in the config lowers or raises a code or a family, and // wf-allow(CODE) accepts one finding on one line; an allow that covers nothing is U07.

New checks

Types (a field, member or method that does not exist; the wrong type; a value that may be null; a match that misses a case; arithmetic on what is not a number; a comparison that is always the same; await where it cannot run), what cannot change (X01), components (C01–C06), routes (R01– R04, two pages on one path), forms (F01–F05), reactivity (X02, X04, X05), secrets through joins and browser globals (T12), data and storage (D01–D05), translations (I01–I04), dates, money and key combinations, styles (V05–V07), dead code (U06–U10), and a page's head script from an origin the policy does not name (E902). Every code is in the Diagnostics chapter with a program that draws it and the output the compiler prints for it.

What the compiler writes for you

4

  • A change inside a state's value (form.name = v, items[i].done = v, items.sort()) compiles to an updated copy, so what reads it repaints.

  • A value spliced into an address is encoded where it stands for a value.

  • A match expression that covers every case needs no else.

  • persist … { key: id } keeps one stored value per instance.

The dev server, `wf verify` and `wf test`

3

  • wf serve answers a fetch or file the build did not write with a 404 and a line in the terminal, not the page shell; its builds hold each response to its declared type ($[1].name is missing), show a route no page answers, and show a list item that threw where it is.

  • wf verify visits :param routes, fails a page whose router drew nothing, and with --returning-visitor loads every route again as a reader whose storage holds the previous build's persisted values.

  • press "Escape" in wf test closes an open dialog.

Behaviour that changed

3

  • A fetch the dev server has no file for is a 404 (also under wf verify and wf test).

  • An api call with an empty path parameter is not sent (it would have asked for the collection); it ends .aborted, and a resource stays loading.

  • One list item that throws no longer blanks its list; an effect that never settles is stopped after 100 runs.

4.3.3

#4.3.3

3 October 2026

Programs the compiler accepted and then compiled wrong now compile right, or are refused where they are written; and the build reads back the JavaScript it wrote, so a script the browser would refuse never ships.

Fixed

9

  • A number field binds a number. Input(bind: qty).number stored the text the field held, so qty + 1 was "31"; it now holds a number, and null when it is emptied. A Select binds the option's value: as it was written: Select.Option("Two", value: 2) binds 2, not "2".

  • A button in a form submits it only when it says so. Every Button and IconButton without type: .submit (or .submit) is type="button", on the live page and in the static paint; "Add a row" in a form used to send the form.

  • bind: on a loop item's field writes back. for t in todos by t.id { Input(bind: t.title) } only showed the value; it now writes the item and tells the list, so whatever reads todos follows. In a loop with no by, the list hears of it when the field is left, so the row is not redrawn under the cursor.

  • Every control binds a store's member. Switch, Checkbox, Radio, Slider and DatePicker bound only a page's state; Switch(bind: Prefs.dark) drew no input at all.

  • A state, derived or prop that holds a function is called. derived scale = (x) => x * factor then scale(3) compiled to a call of nothing; assigning a function to a state stored what the function returned. WF.signal(…).set(fn) now stores fn; .update(fn) is the updater it always was.

  • A store action's let and if let. A let reassigned later in the action compiled to a const; an if let inside an action bound nothing.

  • A name declared twice is an error where it is written. Two stores, two constants, a store and a constant, a state and a derived, a store's state and its action, a prop and a state, a page's parameter and a state: each compiled to a script the browser refused, or let the second quietly replace the first. A component may still share its name with a type.

  • The build reads back what it wrote. Every compiled script is checked before and after minifying — strings, templates, regular expressions and comments closed, brackets matched, no name declared twice in one block — and a fault stops the build as the compiler's bug, with the line it wrote.

  • wf test: type "Two" into "Size" on a select threw; it now picks the option by its text, or its value.

Changed

2

  • A button inside a form that submitted it without saying so no longer does: give it type: .submit.

  • A program with a name declared twice no longer builds. Most such programs already failed in the browser.

4.3.2

#4.3.2

3 October 2026

The crate's documentation builds with no warning on docs.rs. Nothing the compiler or the template engine does changed.

Fixed

1

  • docs.rs documents the crate without warnings. 4.3.1 linked module docs by full path, which a stable rustdoc needed and docs.rs's nightly reported as redundant — seventeen warnings. Each of eight modules was documented twice, on its pub mod in lib.rs and in its own file; the two are one now, and stable and nightly rustdoc both document the crate with none.

Tooling

1

  • scripts/ship.sh waits for a just-pushed commit's CI run to appear, where it took the missing run for a failure and stopped.

4.3.1

#4.3.1

3 October 2026

The crate's documentation builds clean. Nothing the compiler or the template engine does changed.

Fixed

1

  • docs.rs builds the crate's documentation without warnings. 4.3.0's build linked to runtime::RUNTIME_JS, which no longer exists, and from public docs to a private field; a stable rustdoc found seventeen more — module docs that linked to their own items by a name that did not resolve. Every link now lands.

Tooling

1

  • scripts/check.sh (just check) and CI build the documentation with warnings as errors, as docs.rs reads it, so a broken link fails before a release rather than after.

4.3.0

#4.3.0

3 October 2026

WebFluent as a template engine, from Rust first and from Node: templates load once and render on every request, spread over files, with your own data types, and untrusted data cannot put script in the page.

Security

1

  • A URL from the data that a browser would run is dropped. The template engine wrote Link("Pay", to: url) with url = "javascript:…" as a live link, and the static paint did the same for an Image, Video, Audio, a Sidebar.Item and an Element attribute. Every URL attribute now goes through the scheme check the browser build applies.

New, in Rust

7

  • Template::from_files, from_dir and from_sources: one template from several files — components, themes, types and constants shared — each finding naming its file. pages() lists the pages and page(name) picks the one to render.

  • Data is any serde::Serialize value — your own structs — as well as a serde_json::Value.

  • render_html writes a <title> from the page's, filled from the data, and with_lang sets <html lang> (and dir="rtl" for an RTL language).

  • with_pdf(PdfConfig) and with_slides(SlidesConfig) set page size, margins and fonts; PdfConfig, PdfMargins and SlidesConfig are exported at the crate root.

  • A Template parses and checks once and shares the result: Clone is cheap and it is Send + Sync, for a server's state.

  • The cli feature (default) holds the wf command's own dependencies; default-features = false builds the engine without them — 43 crates instead of 62.

  • cargo run --example invoice renders a directory of templates to HTML, a fragment and a PDF.

New, in Node

4

  • renderHtmlAsync, renderHtmlFragmentAsync, renderPdfAsync and renderSlidesAsync render without blocking the event loop.

  • Template.fromDir(dir), page(name) and withLang(lang), as in Rust.

  • The data goes to wf over stdin and a PDF comes back on stdout: nothing is written to disk per render.

  • wf render takes a directory, --page and --lang.

Fixed

2

  • A template's components are drawn in its PDF and slides. The PDF path left every component call out, so an invoice's line items were missing; it also left a function or method call unevaluated — format(price, .currency) drew nothing.

  • const and data files are in scope in a template. Text("{LIMIT}") rendered empty.

4.2.1

#4.2.1

3 October 2026

The editor grammars catch up with 4.2. Nothing in the compiler changed.

Fixed

2

  • Element is highlighted as a built-in in Zed and VS Code; 4.2.0 left it out of both grammars.

  • A state named show parses in the editor. The grammar read show at the start of a line as the show { } statement, so show = !show in a handler was an error in Zed, though the compiler accepts it. It is a name wherever that statement cannot start, as on and event are.

Tooling

1

  • scripts/ship.sh (just ship VERSION) releases a version end to end: CI and the checks on the commit, the Zed pin, the bump, the docs site, the preflight, then the commit, the push and the tag after a prompt.

4.2.0

#4.2.0

3 October 2026

JavaScript is part of a project the way CSS is. A .js file under src/ is a plain browser script, linked on every page as written, and what it declares is in scope by name — checked, documented and offered by the editor. external is gone; wf migrate rewrites it.

Breaking

2

  • external is removed. A remote module is a meta.scripts entry, a local one a script under src/, and a custom element Element("tag", …). wf migrate does all three; a call into a remote module external typed is Any afterwards.

  • Every .js under src/ ships, on every page. wf migrate lists the ones a project already has.

New

7

  • Your own scripts. Top-level function, class, const, let, var and window.x = … are names .wf calls directly. A call is held to the parameters (T10) and to the JSDoc types (T01); @returns types the result; a class is constructed. Collisions with another script, a declaration or a name the language owns are errors. An ES module under src/ stops the build; an unreadable file is linked with a warning.

  • meta.scripts: libraries by URL, linked before the project's scripts, their origins added to the policy; module: true, as: imports an ES module; globals puts a library's names in scope as Any.

  • mount:, update:, cleanup: on every element and component call, and wf:render on document once per drawing.

  • Element("tag-name", …) places any custom element, in the SPA, the static paint and the template engine.

  • class: takes a map and a list, and an if with no else is null when it fails. V04 flags a borrowed wf- class.

  • Editor: completion, hover and go-to-definition for script names and for the classes .css files define, inside class:; the server watches .js and .css files.

  • wf audit lists the scripts and their names; wf types their signatures; acting wf test pages link them.

Fixed

2

  • What an if branch, match arm, list item or slot fill made is disposed of with its page. A route change used to leave its effects, timers and Host cleanups running.

  • An IconButton whose class: reads state kept its own classes; it used to have them replaced.

Tooling

2

  • scripts/check.sh (just check) runs formatting, clippy and the build one by one, as CI does; --fix formats first, --test runs the tests. just lint and just fmt-check now match CI too.

  • Editors: the VS Code extension (0.4.0) and the Zed extension (3.2.0) drop external and re-read the project when a .js or .css file changes.

4.1.2

#4.1.2

26 September 2026

Six fixes, all found by moving a nineteen-screen application (https://github.com/monzeromer-lab/Halyard) from WebFluent 2 to 4. Nothing here is breaking.

Fixed

6

  • A store's derived may call an action declared below it. The checker inferred each derived value as it met it, so an action declared lower in the file read as undeclared (T13) — though a store's members are mutually visible and the runtime binds its actions first. Half a store's derived values failed to compile for no reason.

  • A sort comparator is handed two elements. It was typed like map's (element, index), so the second parameter read as a Number and a comparator over records failed with T01.

  • A layout's arguments read the route's parameters. They were compiled with no page parameters in scope, so layout: Shell(crumb: "Build {hash}") on /app/builds/:hash compiled hash to location.hash.

  • A11 resolves an if on a Bool prop from the call. A card that titles itself h2 under a page title and h3 inside a section was judged on both branches, so the heading-outline lint reported the h3 one against a page whose call says h2.

  • A select's value takes once its options arrive. The runtime applied it after the children passed to el(), but codegen appends Select.Option children as later statements, so a select bound to state still showed its first option.

  • An animation the page never painted settles at its end, not its start. When the clock ran out, settled() committed the animation's current state — and a page that painted no frame is still on its first — so a mount animation in a background tab or a prerender left the element at opacity: 0 for good.

4.1.1

#4.1.1

26 September 2026

Fixed

A responsive layout on the live page

Grid(columns: { base: 1, md: 2, lg: 3 }) was pre-rendered with the class its breakpoints live under, and the page script then drew the grid again without it — with data-cols="[object Object]" in its place — so every responsive grid fell back to one column the moment the page hydrated. The same went for direction:, gap: and the other layout props written per breakpoint. The live page carries the class, and no map is written as an attribute.

A style shared with a page's layout

A page that names layout: Shell did not count Shell as something it draws, so a style { } block written the same way in Shell and in one page's body was put in that page's own stylesheet — and every other page framed by Shell drew the element unstyled. A layout is part of its page now, and such a rule is shared.

4.1

#4.1

26 September 2026

Security

A private env value no longer reaches the bundle

4.0 made a page that reads a non-public env name a compile error — and then wrote the whole env map into app.js as const env = {…} anyway, so a value like STRIPE_SECRET in webfluent.app.json was downloaded by every reader. The bundle now carries only the names a page may read: those beginning PUBLIC_ and those public_env lists. If a site built with 4.0 or 4.0.1 had a secret in env, rotate it.

Added

7

Offline

Name offline in the config and wf build writes a service worker that stores the site for when the network is gone — the shell, the routes precache names with their own chunks, and a fallback page for the rest — and fetches what it did not write by the policies cache names. It is versioned by a hash of everything the build wrote, so a deploy that changes a byte is a new version; the page reads update.available and calls update.apply(), which takes it and reloads once. With sync, a write made with no network is kept in IndexedDB and sent in order when the connection returns — by Background Sync where the browser has it, so a closed tab still sends it — and network.queued says how many wait. Under wf serve the worker takes itself away.

It is held to a real Chrome in CI (tests/browser/offline.mjs, 24 checks across a pre-rendered and a single-page build): the site stored, a stored route served with the server gone and the fallback for one that is not, a write kept, counted and received exactly once, and an update offered and taken with one reload.

Peers

peer link = rtc(signal: …) opens a WebRTC data channel straight to another page, with the handle and the match of a socket — connecting, open, closed(c), error(e), .send, .messages, .last. The language supplies the channel, not a server: the offer, the answer and the routes each side can be reached by go out through signal:, over whatever the app already has, and what the other side sent is handed to link.signal(m). One side is the initiator; ice: names STUN or TURN servers. A page that leaves closes its peer, and the other side reads closed at once. Held to two pages in a real Chrome in CI (tests/browser/peer.mjs).

The documentation, rewritten

The guide is 48 chapters in six parts — Start, the basics, Building, Shipping, Reference and Help — with a tutorial that ends in a deployed site, chapters for forms, real-time, offline, accessibility, testing, deploying, environments, performance and JavaScript interop, and reference chapters for every command, config key, diagnostic, built-in, design token, runtime function and keyword. It is held to the compiler: every example is compiled, every page example is run and clicked through, every diagnostic example draws its code, every link lands, and a test fails when the language has something the guide does not name.

A name nothing declares is a compile error

Button(huge) and on click { cuont = count + 1 } built, and threw a ReferenceError in the browser the first time the page ran. A name that no state, const, prop, action, store, api, external or browser global declares is now T13, reported where it is written, with the spelling to check. A template's names are its data's, so wf render is not held to it.

wf render is held to what a build is

A template that named a component nothing declares rendered <!-- unknown component -->, and a flag a component does not take was dropped, both with exit status 0 — an invoice with a typo went out that way. The render now stops on everything a build stops on except T13. It also takes --token NAME=VALUE for a design token over the theme's, reads an indented .wfx template, and finds a data file beside the template, as the guide always said it did.

The Node binding, as webfluent on npm

npm install webfluent — a thin wrapper around wf render, at the compiler's version, published by the release once the repository has an npm token. withTokens() reached nothing before and does now; withTheme() is only sent when set, instead of naming a default theme; renderSlides() is new; a template that does not compile throws what wf said. Its tests run in CI against the wf the job built.

A title that looks its entry up

title: "{posts.find(p => p.slug == slug)?.title ?? slug} — Blog" was written into every file as those characters: only a bare parameter name was filled in. A title may splice any expression over the route's parameters and the program's constants and data; the build works it out for each file and the router again on each visit.

env from a .env file and the shell

env.NAME reads the config's env map, then a .env file beside it, then the shell — so a pipeline can give staging and production their own values without editing a file. The shell supplies a name the config or .env declares, or a public one.

A config key nothing reads is reported

"defaultLocale" in webfluent.app.json was dropped without a word; the build now warns and names the key it meant (default_locale). wf init -t static itself wrote the misspelling, and so did the documentation site.

And

  • Pagination: resource list = Api.items(page: page, paginate: .page), then list.items, list.loadMore(), list.hasMore. The compiler emitted the option and the checker refused it; the runtime now has it.

  • A route's parameters in its title: title: "{slug} — Blog" gives each pre-rendered file, and the live tab, that route's value.

  • ?lang=ar opens a page in that locale — the address the build's hreflang alternates always pointed at.

  • Every standard DOM event in on …: dblclick, pointerdown, scroll, paste, drop and the rest, without a warning.

  • on open { } on a socket, as a peer and a channel had it.

  • A class a module exports is constructed when an external calls it, so Chart.js and most modern libraries work through external + Host.

  • wf init writes a .gitignore; wf generate page gives the page a description.

Fixed

14

The favicon on a pre-rendered page

meta.favicon was never linked from a pre-rendered page, and the single-page shell linked it as written, so under a base_path it pointed at the host's root. It is linked from every page, resolved like any other asset, and typed so an SVG icon is read as one. meta.touch_icon is new: the 180×180 PNG a phone puts on its home screen, which iOS reads instead of an SVG.

A sidebar's items on a phone, and in Arabic

A Sidebar is a column of fixed height that scrolls, and its items shrank to fit instead: with more than a screenful, every link was squeezed to 18px, too small to tap. They keep their size and the column scrolls. On a phone a closed sidebar waits off its own edge — in a right-to-left page it slid the wrong way and covered half the screen.

An action's parameters

action move(by: Number) { n = n + by } on a page or a component compiled by as a signal, _by(), which does not exist: every such action threw the first time it ran. A store's actions were never affected.

What the guide's examples found

Writing every example out as a real page and running it found programs the checks accepted and the browser rejected:

  • head { meta(content: post?.title) } read a derived before it existed.

  • Text("{rows.state}") showed a signal's source; a resource's state, data, error and a socket's messages are now read as their values.

  • navigator and location compiled as signals.

  • app { state … } never declared its state.

  • now(every: 1.seconds) called a now nothing declared.

  • An action handed over as a value, addEventListener("scroll", track), was read as a signal.

  • A type an external declares could not annotate a value.

  • Backend.avatar.progress was refused by the checker.

  • Two declarations on one line — theme T { color-primary: #0F766E radius-md: 14px } — were read as one, setting the first token to both.

  • S04 never reported two pages on one route; A12 counted an h1 in each branch of an if as two.

  • A test that clicks failed in any project with a dark theme.

  • The CSP check took a code sample's onClick= for an attribute.

  • Warnings printed as Warning: Error: ….

  • The Node binding did not look where the installer puts wf.

A site_url with the subpath in it

meta.site_url written as the site's whole address — https://x.github.io/docs beside a base_path of /docs — gave every canonical link, link preview and sitemap entry the base path twice: /docs/docs/. It is read once now, so either spelling means one address.

A browser value in text

Text("{viewport.width}"), a clock on now, network.online — any text that read one of the browser's values was computed once and never moved. Only conditions were drawn live: the check that decides whether a text follows its values knew signals and translations and none of these.

text.lines() on a live page

Every runtime module shares one closure, and the network module declared a lines of its own — the reader for a streamed response. Wherever that module was built in, the later declaration won: text.lines() handed back an async generator, so the static paint showed the lines and the live page replaced them with undefined. The stream reader has its own name now.

Escapes in a splice

A string written inside a splice keeps its own escapes: "n={("a\"b").length}" refused to build, because the escape was undone before the splice was read. And the older spelling {a ?? \"x\"}, which the compiler has always said it accepts, was shown as text rather than read as a splice.

url.query() and url.with(…) paint at build time

They painted nothing until the script ran. The static paint now computes both as the browser's URL does — values decoded, a key replaced where it stood, the search written back form-encoded.

Held to each other

Behind these, three checks: every method's value at build time is compared with the runtime's, in Node, for 61 samples — anything the build cannot know says why; every runtime function the compiler can call must exist; and no two runtime modules may declare the same name.

The documentation site

Written for a phone first: every rule is the phone's, and md, lg and xl add to it. The search is in the phone's menu, every link and control a reader taps is at least 24px (44px in a drawer), a wide table or code block scrolls inside its own box, and no page scrolls sideways at any width from 320px to 1920px, in English or Arabic — each checked on every route in a real browser. It has a favicon, a home-screen icon and a link-preview card, drawn as SVG in site/art/ and exported by scripts/site-art.sh. The search index is its own file, fetched the first time the search box is used, instead of 20 kB carried by every page.

Editors

3

  • Zed: the grammar reads WebFluent 4 — api, connections, validate, refined types, the language's literals — where it used to mark them as errors, and a call with a bare-name argument (remove(i)) no longer fails to parse. It is held to every example in the guide. A string that begins "/// …" — a sample of code — is text, not a doc comment.

  • Neovim, Helix and Emacs: the guide's CLI chapter has the configuration for each.

  • VS Code 0.3.0: attached to this release as a .vsix. It is bundled — the 0.2.0 package could not start — finds wf-lsp.exe on Windows, and downloads the server from the latest release when it is not on PATH.

4.0.1

#4.0.1

26 September 2026

Fixed

A translation paints wherever it is written

The static paint resolved t(…) only when it was the whole of a text. Text(t("name")) painted; "Hello, {t("name")}", "{n} " + t("items"), an if on a translation, and a translated prop that a component spliced into its own text all painted empty, and stayed empty until the page's script ran — so a reader without JavaScript, and a crawler, saw nothing there. A static or server-rendered page with more than one locale almost certainly had some.

The build-time evaluator now answers t("key") and t("key", { … }) wherever they appear, from the default locale, with the same plural picking, placeholder filling and fallback to the key that Text(t(…)) always had. Nothing to change in your source: rebuild, and the text is in the HTML.

The documentation site

The Security chapter was missing from the navigation and the two chapters after it were numbered one short; the Styling chapter was behind the guide by five rows of the design-token table; an Arabic reader saw each page's breadcrumb and prev/next titles in English; and the header read 3.0. The site is now held to the guide by two tests, so its pages cannot fall behind the chapters they are generated from again.

4.0

#4.0

25 September 2026

Thirteen things the language could not do, or did badly. The runtime is now modular and a static page carries 3.7 kB gzipped of it where it used to carry 18.3 kB.

Breaking

3

Read this section before upgrading. wf migrate does the mechanical part and names the rest with the file and the line — run it first:

wf migrate .

env splits in two

env.NAME is replaced at build time and the value lands in the bundle, so only a public name may be read from a page, a component, a store or an api block: one beginning PUBLIC_, or one the new public_env list names. Any other name is a compile error at the line that reads it; the values still reach wf render, which runs on a server.

wf migrate adds every name your pages already read to public_env, so the build keeps working, and prints the list — read it, because an API key in there was a leak before and is a leak now.

An on* attribute is a compile error

Button("x", onclick: expr) is the one place an attribute value is executed. Write Button("x") { on click { … } }. No automatic rewrite: the old value was a string of JavaScript.

A URL a browser would run is refused

href:, src:, to:, poster: and navigate() take http, https, mailto, tel, sms, ftp or a relative URL. A literal is refused where it is written; a value that only exists at run time is refused at the moment it is used. javascript:, data:, vbscript:, blob: and file: have no replacement.

Stores are built on first read

Nothing is constructed at boot. The order stores are declared in no longer matters — a derived that read a store declared below it used to read undefined — and a store nothing reads costs nothing. If a derived of yours had a side effect that ran at boot, it now runs when something reads it; store X(eager: true) restores the old timing.

A persist value follows the site's other tabs

localStorage is shared between tabs, so a write in one now arrives in the others. sync: false keeps a value to its own tab.

The runtime surface

WF.store(def) is WF.store(name, define, options), and WF.host(…) — which was a Url's host — no longer builds a Host; that is WF.attach. Only a hand-written script is affected.

Smaller

  • wf init writes "csp": true. An existing project opts in.

  • The guide renumbered: the components reference is chapter 20 and the cookbook 21, with the new security chapter at 19.

  • A layout no longer reflows on its own below 768px — that landed in the responsive work; .stacks is how a Row, Grid or Column asks to, and wf migrate adds it.

Added

The runtime is modular

28 feature modules, and a build carries only the ones its program reaches — read from the bundle it just wrote, so the set cannot fall behind the compiler. wf build --stats prints what the output weighs and which modules it holds. build.budget warns over a gzipped size; build.runtime: "full" ships everything for a program the scan cannot see.

Eleven types the language brings with it

Date, Time, DateTime, Duration, Money, Url, Email, Color, Uuid, File, Secret — each a plain JSON value at run time, with @2026-03-14, 3.days and €12.99 as literals, arithmetic that runs at build time as well as in the browser, and refinements (Number(1..=30), String(minLength: 8)) checked at every literal. uuid() is where a Uuid comes from.

A service, described once

api Backend(base:) { … get users(page: Number) -> [User] } — or api B from "openapi.json" — compiles to one object of typed, cached, cancellable endpoints: typed errors, retry with backoff, SWR caching with ETag revalidation, dedupe, upload progress, pagination. socket, stream and channel for a connection the page holds open, closed by the scope that opened it.

Validation beside the state it guards

validate email { required email async "Taken" { … } }. The control bound to that state shows the message without being told to, with the role="alert" / aria-invalid / aria-describedby plumbing. Form(bind:) gives valid, errors, touched, pending, values, reset(), submit() and apply(serverErrors).

A real image pipeline

image hero = "hero.jpg" reads the file at build time and writes it at every width a page asks for. Image(hero, sizes:, placeholder: .blur) is a <picture> with width/height from the real file, so nothing shifts. PDF and slides embed the picture rather than a grey rectangle.

Responsive values, without JavaScript

Grid(columns: { base: 1, md: 2, lg: 3 }) compiles to one class and one media query per step, so the right layout is in the first paint. The breakpoints are design tokens.

Motion on the Web Animations API

An interrupted animation gives way to the one that replaced it; a spring is sampled into a linear() easing. New: on: .enterView, shared: for an element carried across a route change, .expand to the height of the content, count: on a number, and sequence { step(after: "120ms") { … } }. Nothing the DOM must end up as depends on an animation finishing — a page that is not painting still opens the box, arrives at the number and completes the route change.

Stores: lifetime, location, and a way to see them

store Cart(scope: .app | .session | .route), and a persist policy: in:, version:, sync: and migrate 1 -> 2 { … }, so a value an older build wrote is carried forward rather than discarded. wf serve gets a stores panel: the tree, every action with the state on each side of it, and a click to put one back.

Security, as a subject the language takes seriously

Beside the breaking changes above: Unsafe.Html(markup) is the one door for markup, sanitize(html) is an allow-list that runs at build time and in the browser from the same list, rel="noopener noreferrer" comes with any target:, meta.integrity emits SRI, and the build reads its own output back and holds it to the policy it ships. wf audit prints every Unsafe.*, every other origin, everything kept on the reader's machine, every env name, the policy and the dependency list. A new chapter 19 covers the threat model and a deployment checklist.

A test that acts

wf test ran a body through the template engine and read the result, which meant no test in the language could exercise a button: a click runs a handler, which runs an action, which changes a store, which repaints, and a renderer does none of that.

A test with an interaction in it is now compiled into a real page, served, and run in a headless browser — same compiler, same runtime, same output a reader gets.

test "reporting an incident opens one more" {
    use IncidentStore
    state draft = ""
    Text("{IncidentStore.open} open")
    Input(bind: draft, label: "What happened")
    Button("Report") { on click { IncidentStore.report(draft) } }

    expect "2 open"
    type "Queue backing up" into "What happened"
    click "Report"
    expect "3 open"
}

click "Save", type "Ada" into "Name", press "Escape" in "Search" and expect run in the order written — which is the whole meaning, since what a click did is only visible in the expect that follows it. Everything is found the way a reader finds it: a button's text, a control's label, its placeholder, its aria-label — the same names the accessibility checks hold a page to. A handler that throws fails the test even where the expects would have passed.

A test that only looks is still rendered and snapshotted, and needs no browser.

wf verify — every page, in a real browser

wf build && wf verify

It starts a headless Chrome, serves the output and opens every route the project has, failing on an uncaught exception, a console.error, a file that did not arrive, an image that failed or a page that rendered no text. It reports the first contentful paint, the node count and the bytes each route fetched; --budget MS fails a route that paints too slowly and --json is the same report for a pipeline. It also says which built-ins no page drew — the classes the pages carried are the list of what actually ran.

The DevTools Protocol client is written here, like the PDF writer and the gzip encoder: it speaks to a process the build started, on the loopback address, so it needs no TLS, no compression and no fragmentation, and a dependency would be larger than the problem.

Interop, in both directions

external Chart from "…" { fn … type … } is a typed import, checked at every call site, emitted as a real ESM module with its origin in the policy. Host(mount:, update:, cleanup:) is a node with a lifetime — the ref + effect + cleanup written by hand, with the cleanup impossible to forget. external element places somebody else's custom element, and output_type: "elements" publishes yours: PriceTag becomes <price-tag>, usable from React, Vue, Svelte, Rails, WordPress or a plain page.

Strings that do not fight you

Raw strings #"…"#, block strings """…""" with the source's indentation removed, and formatted splices {total:.currency}.

Fixed

13

A store's actions now speak the whole language

A store's action and a page's handler are compiled by two different emitters, and each kept its own table of what a WebFluent method becomes in JavaScript. The tables drifted. Inside a store action, items.remove(i) compiled to store.items.remove(i), word.toUpper() to store.word.toUpper(), items.contains(x) to store.items.contains(x), and every one of the 39 scalar methods — due.plus(days: 5), total.times(2), site.host() — to a method call on the value itself. A Date is a string at run time and Money a map, so each of these threw the first time its action ran. The page painted correctly until then, which is why nothing caught them: the source parses, type-checks and lints clean, and only the generated JavaScript is wrong.

There is one table now, read by both emitters, so a method added to one cannot go missing from the other.

Removing from a list no longer empties it

items = items.remove(i) on a page state compiled to a set inside a set. The inner one removed the item; the outer one then set the list to what set hands back, which is nothing. The item went, and the list went with it. The removal now evaluates to the new list, so both the statement items.remove(i) and the assignment are correct.

The static paint knows WebFluent's own spellings

toUpper, toLower and contains were missing from the build-time evaluator, which knew only toUpperCase, toLowerCase and includes. A page that used them painted an empty element, and it stayed empty for a reader without JavaScript and for a crawler.

  • A derived that read a store declared later in the file read undefined.

  • A page state named key, value, event, e or params compiled to a bare identifier: it rendered as nothing and never updated.

  • Input(bind: Store.member) compiled to a control with no binding at all — a silent no-op.

  • The static paint wrote style="display:none" for a hidden show, which a strict style-src forbids.

  • The documentation site was painting ￾ and ￿ in inline code.

  • frame-ancestors was shipped in a <meta> tag, where a browser ignores it.

  • An api block's on request / on response / on error hooks compiled to empty functions: everything written in one was generated into a string and thrown away.

  • A handler's parameter in an api hook and in a socket, stream or channel (on message(m)) compiled to _m() — a signal that was never made, so the handler threw on the first message.

  • match over a socket, stream or channel called the handle as a function, which threw and took the whole page's first paint with it.

  • if let x = … inside an action, a handler or an effect read the bound name as a signal, so the branch that had just checked it was not null used a name that did not exist.

  • T06 only held a store to its members where the body wrote use, and never inside another store or an api block — so Store.mispelt() in any of those built without a word.

  • U04 did not see the reads in an api block's headers { } or hooks, and reported the store members only those reach as unread.

  • form.pending, form.errors, form.touched and form.apply(…) were T05: the checker's idea of a form handle was missing half of it.

Coverage

Every page of every example — the fixtures, both wf init templates, the documentation site and a real 130-file project — is loaded in a headless Chrome on every change: 124 pages, zero errors, and every one of the 52 built-ins that can render in a browser is drawn by at least one of them. just browser runs the sweep; it reports nothing to do where there is no browser.

It is also how a real bug in the dashboard fixture's own store was found the moment it had a test that clicked: resolve changed a field of an item in place, so the list stayed the same list and nothing repainted.

That sweep is how three of the fixes above were found: a route change that never completed, a box that never opened and a number that never moved, each of them waiting on an animation frame that a page which is not painting never gets.

Diagnostics

New codes: P01/P02 (a persisted value's version chain), P03 (a route-scoped store that persists), V03 (an Unsafe.Html, and whether it is sanitised), T12 (a Secret where it would escape).

3.2.1

#3.2.1

24 September 2026

Fixed

A store's action is no longer mistaken for a list method

Todos.remove(id) called the action the store declares. The JavaScript back end matched the method table on the name alone, without looking at what it was called on, so it compiled to Todos.splice(id, 1) — a store is an object of state and actions, never a list, so the handler threw Todos.splice is not a function on the first click. The page painted perfectly until then, which is why nothing caught it.

A store's own members now come first, so an action may be named after a list method. The shadowing was not limited to remove: every name in the table — push, filter, map, take, contains, first, last — hid an action of the same name. Todos.items.remove(0) still reaches the list, since that names the list rather than the store.

items.remove(i) repaints

remove on a list held by state, persist or a store's member spliced it in place, so the signal kept the array it already had: nothing reading it repainted and a persisted list was never written. It now goes through the signal, as push does, via the new WF.removeAt(list, index).

Navigation items drawn by a for are links in a static build

A Sidebar.Item(to:) reached through a loop pre-rendered as a bare <li> with the destination dropped: the components reference on the site, whose index is for c in shown { if … { Sidebar.Item(to: …) } }, shipped a navigation panel with no links in it. The static back end read to: as a literal only, so a destination that needs the loop's binding — "/docs/{p}" — resolved to nothing. It now reads it through the build-time scope.

The published site was also rebuilt: its bundle still carried the <li to="…"> from before the 3.2.0 fix, so clicking a component in the reference sidebar did nothing at all, silently.

The install scripts download a file that exists

install.sh and install.ps1 asked for Rust target triples — wf-$VERSION-x86_64-unknown-linux-gnu.tar.gz, wf-$VERSION-x86_64-pc-windows-msvc.zip — but the release publishes wf-<version>-<arch>-<os>: x86_64-linux, x86_64-macos, aarch64-macos, x86_64-windows. Every run downloaded a 404 page and handed it to tar. install.sh also rejected macOS outright, despite the release carrying both Mac builds, and appended its PATH line again on every run.

Both now resolve the right asset, cover Apple Silicon and Intel Macs, fail with a readable message instead of a corrupt unpack (curl -f, unpacked through a temporary directory), and add the PATH line once. Linux arm64, which has no prebuilt binary, is told to use Cargo.

cargo install webfluent is documented in the guide and the README, which had been pointing at a 0.2.0-alpha Debian package.

Testing

tests/cookbook.rs extracts the three applications from md-docs/20-cookbook.md — the guide itself, not a copy — builds them and runs them against the fake DOM in tests/js/cookbook.test.mjs, clicking through add, toggle, remove and clear. tests/docs_parse.rs now runs the JavaScript back end over every guide block and rejects a bundle that calls a store member the store does not declare, which parsing and type-checking could not see. A navigation item inside a for or an if is held to being a link in every backend.

3.2

#3.2

22 September 2026

Added

9

The guide: md-docs/

A twenty-chapter developer guide, from wf init to three complete applications: getting started, the language basics, pages and routing, elements, state, events and forms, control flow, components, stores, types, expressions, styling, motion, data, internationalisation, content, outputs, tooling, a components reference generated from the registry (scripts/components-reference.py), and a cookbook. Every code block is parsed, semantically checked, type-checked and held to the linters by tests/docs_parse.rs, and the cookbook's applications build and were walked through in a browser. The site's documentation will be rewritten from it.

Syntax colouring

Code(…, language: "wf") — or json, bash, css — and a Markdown fence in one of those languages are coloured, at build time by codegen::highlight and in the browser by WF.highlight, the same tokens either way: keywords, capitalised names, strings, numbers and colours, name: props, $tokens, comments and a shell prompt, each a wf-tok-* span taking its colour from the theme's syntax-* tokens. The baseline theme now carries those tokens and term-bg/term-ink/term-dim, and a code block is painted on term-bg — a console stays dark in both themes — with white-space: pre and a horizontal scroll. sun and moon join the icons; an icon: that reads state follows it.

The documentation site, from the guide

site/ is written from md-docs/ by scripts/site-from-guide.py: one page per chapter under site/src/pages/guide/ (routes /docs/guide/<chapter>), framed by DocsShell — the header with search over every chapter and section, the chapter nav with its numbers, the article at a reading measure, the headings rail and the links to the chapters either side — with prose as Markdown (inline code, links and lists render), fences as CodeBlock (coloured, with a Copy button), shell blocks as Terminal and pipe tables as Table. The components reference is data: wf registry --json becomes site/src/registry.json (scripts/site-data.py), an index page and one page per built-in at /docs/reference/<name> with its signature, props, flags and cases, events and parts under tabs, a filter over the index, and the entries nearby. The landing page, the chapter page, the reference and the phone layout follow the design canvas "WebFluent — site and documentation" to the pixel, in the MO design system: graphite for structure, blue for intent, cyan for data, Inter and JetBrains Mono, a console that stays dark in both themes, a theme toggle, light and dark, and Arabic chrome with the chapters kept left-to-right.

The language

  • A string splice takes any expression: "{format(total, .currency)}", "{[1, 2].length}", "{a ?? "none"}" and "{if ok { "yes" } else { "no" }}" — a splice may hold a string of its own, as long as the group closes on the line. A brace group that is not an expression ("{key: value}" in prose) stays text; one with a slip in it is an error that names the splice.

  • () => expr: a lambda of no parameters, for setTimeout(() => go(), 300).

  • A record construction carries the fields it left out — each field's default, null for an optional — so Todo(id: "a", title: "b") holds done: false wherever it goes.

  • await fetch(url, options) in an action or a handler is the parsed body, and a failed response throws (WF.request): the same request a resource makes. The browser's own is window.fetch.

  • items.push(x) on a state, a persist or a store's member sets a new list, so what reads it repaints and a persisted one is written.

  • Modal(visible:)/Dialog(visible:) take any expression that reads state — a store's member, a condition — and write a state or a store member back when the browser closes the dialog itself.

  • A page's guard: and redirect: work: a route whose guard is false sends the reader to its redirect (default /) instead of painting.

  • A page's own meta in head { } replaces the standard tag of the same property or name, so a post page has one og:title, its own.

  • The registry lists the icons the runtime draws (registry::ICONS, pinned to the runtime's table); an Icon("…") or icon: that names another is a warning, and the language server completes from the same list.

Fixed

18

  • The static paint and the template engine bind an if let name: the branch used to read it as unknown and paint an empty heading.

  • A store action's try/catch, for and else if used to fall through to the page emitter and read _x() signals a store does not have.

  • Form(bind: form) declared the handle twice — as a form and as a ref — which the browser refused.

  • A Checkbox, Radio or Switch drops nothing now: aria-*, data-*, name, id and disabled reach the <input>, and radios bound to one state share a name so the arrow keys move between them.

  • navigate("/?filter=done") and a Link(to:) with a query string route by the path and keep the query readable through query; a link to the route with a query is the current one.

  • The single-page shell addresses its assets from the site root, so a deep link served by the SPA fallback (/deploys/8f2c) loads app.js rather than the shell again.

  • WF._basePath is a getter again; a static build's links no longer start with undefined.

  • A bare slot followed by on key(…) on the next line names no slot on.

  • The vocabulary lint knows a page's route parameters, and its const and data names.

  • A page framed by a layout: is judged with the layout's outline: the h1 a layout draws is the page's (A12), and a heading level skipped across the boundary is seen (A11).

  • Grid(columns:) is a data-cols attribute the stylesheet reads — a build with build.csp on used to have its grids blocked as inline styles — and a columns: that reads state follows it.

  • wf serve serves a site built with build.base_path under that path, as its host will, and sends / there.

  • A Markdown link or image to a site-relative path takes the base path, at build time and in the browser.

  • A Breadcrumb.Item without to paints as a <span>, not an <li> outside a list.

  • The skip link hides by a transform, not an off-canvas offset that a right-to-left page could scroll to.

  • A :param page's static files carry their own route as the canonical link and sharing URL, not the pattern with :slug in it.

  • An IconButton with a class: keeps the engine's classes; its icon:, label: and title follow state.

  • A Sidebar.Item or Breadcrumb.Item with a to: reached through a for or an if is a link in the browser too; it used to be a bare <li to="…"> that went nowhere.

3.1

#3.1

21 September 2026

Added

11

The language core

  • for in actions, handlers and effects — with an index, over a range (1..10, 1..=10), or a keyed list; try { } catch e { }; destructuring let { a, b } = m and let [x, y] = l.

  • Optional chaining a?.b, a?.m(), a?.[i]: null when the base is, the rest of the chain with it, typed as T?.

  • if let x = v { a } else { b } as a value.

  • Regular expressions /pattern/flags, with test, exec, and a string's match, replace, replaceAll, split, search; a / after an operand still divides.

  • Spread [...a, b], { ...m, k: v }.

  • const NAME = value at the top level, and env.X from the config's "env" map, fixed at build time.

  • Record composition type Admin = User { role: String }; enums whose cases carry a payload, enum Status { idle, failed(reason: String) }, written .failed("x") and matched .failed(r) { … } (a match expression binds one name); ["failed", "x"] at run time, a bare case its name.

  • Structural shapes: a map literal is typed by the fields it was written with, so form.nam is a T05 and a literal given where a record is wanted is checked field by field; a field only some items of a list have is T?.

  • Helpers sortBy, groupBy, unique, take, first, last, flatMap, sum on lists and capitalize, truncate on strings — in the browser and at build time.

  • format(value, .style, option) — .number, .integer, .decimal, .currency, .percent, .compact, .date, .time, .datetime, .relative, or a date pattern such as "yyyy-MM-dd HH:mm" — and ago(date), in the i18n locale when the project has one and the document's language otherwise; the static paint and the template engine format from a table of the common locales and currencies.

  • The type checker places an error at the expression it names when the source is at hand; hover shows a record's inherited fields and an enum's payloads; the tree-sitter grammar and the Zed extension know every new form.

Tooling

  • wf fmt formats a project's sources: indentation by block depth,

spacing around braces, trailing blanks and blank-line runs — held to the file's tokens, comments kept; wf fmt --check for CI. --to wfx|wf still changes the layout.

  • wf serve rebuilds on save, reloads the page, and shows a failed build's

diagnostics over the page until the next build passes.

  • Plural forms: t("items", { count: n }) picks items.one, items.other

and the locale's other categories from the translation file.

  • A route change with Router(transition:) plays through the View

Transitions API where the browser has it, the class-based animation standing in elsewhere.

  • wf docs: a self-contained component gallery of every built-in and of

the project's own declarations.

  • Markdown(text): a small Markdown rendered the same way at build time

and by the runtime, the text escaped first; a .md file under src/ is a page, its front matter the page's attributes.

  • data posts = "posts.json": a JSON file as a constant, read at build

time; paths: on a :param page renders the static page once per value and lists each in the sitemap.

  • wf test: `test "name"(data: { … }) { elements expect "text" expect

not "text" } declarations under tests/, rendered through the template engine with the project's declarations at hand, held to their expectations and to snapshots (--update` accepts a new render).

  • The language server renames — a component, a store, a store member, a

local — across the project, inside interpolations too, and offers Extract component on a selection of elements, with what they read as typed props and the stores they use used again.

  • Unused warnings U01–U05: state, derived values, actions, components

and store members the program declares and never reads, in the build's output and the editor.

Components and reactivity

  • Scoped slots: slot row(item: Todo, index: Number), used as

row(item: it, index: i), filled as row(t, i) { … }; the fill is drawn again when a value it is handed changes.

  • Parts of a component: part Header(_ text: String) { … } inside

component Panel, called as Panel.Header("…").

  • A component's enum props are written to its root element as

data-<prop>="<case>".

  • ref: name on an element: a handle read as the element itself

(name.focus()).

  • every(ms) { }, after(ms) { } and effect { … cleanup { … } }; what a

page, a branch, a list item, a match arm or a slot creates is disposed of when it leaves.

  • persist name = value in a page, a component or a store: kept in the

browser's storage across visits.

  • viewport, query, hash and theme: the browser as values, kept

current; a declared name shadows them.

  • on key("ctrl+k") { } on an element or at the top of a page.
  • animation Name { from { } to { } } keyframes, played with `animate:

.Name` or written into a style; container queries pass through.

  • Dark mode: "theme": { "dark": "Night" } applies a second theme under

prefers-color-scheme: dark and on setTheme("dark"), kept across visits.

  • Form(bind: form): form.valid, form.values, form.reset(); an async

action's name.pending.

  • A page's head { meta(…) link(…) script(…) }, painted at build time and

kept current on the live page.

  • The template engine binds a component's positional props and defaults,

and every component is registered before a page renders; the static paint substitutes props through every expression and into branches, loops and matches.

The indented layout: .wfx

The one grammar, written by indentation. A .wfx file opens a block with a line indented deeper than the one before it and closes it with a dedent; inside parentheses, brackets and any braces you write, the layout is free, so a multi-line argument list, a map literal and a one-line { on click { save() } } read as they always did. Nothing else changes: the parser, the checks, the output, the language server, the template engine and wf generate read and write both layouts, and a project may hold both.

wf fmt --to wfx rewrites a project's .wf files as .wfx, and --to wf the other way — a change of layout and nothing else, held to a byte-identical build across every fixture, the documentation site, every wf init template and Halyard, and refused for a file whose indentation does not already follow its braces. wf migrate --wfx migrates a WebFluent 2 project straight into the indented layout.

The Zed extension gains a second grammar and language for .wfx, generated from the same grammar.js, with its own indent queries; the VS Code extension opens .wfx files. Specified in spec/SYNTAX_V2.md §8a.

For tools: wf registry --json, wf types --json, and edits by name

The registry as JSON — every built-in with its positional prop, props and their cases, flags, events, slots, parts and attribute families, plus the universal props — and a project's own declarations the same way: enums, records, components with their props, events and slots, stores with their members, pages with their routes. The structured edit operations speak the grammar by name: SetProp/RemoveProp, SetFlag/RemoveFlag, SetHandler/RemoveHandler, SetSlot/RemoveSlot, beside the older AddModifier/SetArg that stay as aliases; two insertions at one place land in the order they were asked for; a .wfx file is edited through its braced spelling (apply_edits_to). WebFluent Studio reads both.

wf build reads source files in name order

The order files are read in decides the numbering of a page's elements, and it followed the file system's own order — so the same project could build differently on another disk. It is alphabetical now, App.wf first.

3.0

#3.0

Not released yet

The grammar release. WebFluent's surface syntax grew by accretion until it broke its own rules — a misspelled modifier did nothing, one { } meant five things, a style value was a string in which a bare word was a token or a variable depending on a lookup, routes were declared twice, a project's own components could not declare a variant, an event or a slot. WebFluent 3 is one language with one lexeme per meaning, a registry that describes every built-in once, a type checker, motion on any element, and wf migrate, which rewrites a project mechanically: every fixture, the documentation site, every wf init template and the Halyard demo (129 files) migrate to a byte-identical build.

This release is a hard cut. wf build and the language server read only the new grammar; a file in the old one is refused with a pointer to wf migrate. See Migrating at the end.

The grammar

10

enum Tone { neutral, info, danger }
type Todo { id: String, title: String, done: Bool = false, tone: Tone = .neutral }

/// A todo, as one row.
component TodoRow(_ label: String, todo: Todo, compact: Bool = false) {
    event toggle(id: String)
    slot trailing
    Row(align: .center, gap: .sm) {
        style {
            padding: 6px 0
            background: $surface
            --accent: {todo.color}
            &:hover { background: $surface-hover }
        }
        transition { background: 150ms ease-out }
        on click { emit toggle(todo.id) }
        Text(label).bold
        trailing
    }
}

page Home(path: "/", title: "Todos", layout: AppShell(crumb: "Todos")) {
    use Todos
    resource list = fetch("/api/todos")
    match list {
        loading { Spinner }
        error(e) { Alert(e.message).danger }
        ready(v) {
            for t in v by t.id {
                TodoRow(t.title, todo: t, exit: .fadeOut).fadeIn {
                    on toggle(id) { Todos.toggle(id) }
                    trailing { Badge("new").info }
                }
            }
        }
    }
    Button("Add").primary.lg { on click { Todos.add(draft) } }
}

app { Navbar(brand: "Todos") { Navbar.Links { Link("Home", to: "/") } }  Router(transition: .fade) }
  • Lowercase declarations: page, component, store, theme, app, and the new type and enum. There are no keyword tokens: type: and on = !on are what they look like.

  • Flags: .primary.lg after the parentheses — a Bool prop or a case exactly one enum prop has; a case two props share is named, tone: .info. A word nothing declares is an error that lists what the component takes. Input(…).text, Heading("x").h1, Spacer.sm.

  • One positional argument, the component's declared positional prop, then named ones. An enum prop takes a case: Row(gap: .md).

  • Parts under their owner: Table.Head/Body/Row/Cell, Select.Option("Label", value: "v"), Tabs.Page, Card.Header.

  • One block, in order: style, transition, on handlers, slot fills, children. on click { } and on click(e) { }; a Button's block holds what it shows, on click what it does.

  • Style values are CSS: padding: 1rem 2rem, background: $surface, width: {pct}%, &:hover { }, @media (…) { }, --name: value. A $token is validated against the theme; $md on padding is $spacing-md.

  • Components declare typed props (_ name: String, active: Bool = false), events fired with emit, and slots filled by name.

  • Pages own their routes: Router takes no children; routes match by specificity. layout: Shell(args) wraps a page in a component with a default slot.

  • resource and match replace the fetch block; for … by key keys a list; if let x = expr { } unwraps; ??, T?, [T], null, await in actions and handlers, if and match as values, .case, $token in expressions.

  • Store.load(id) at the top of a page is set-up code; let x is a local in a handler or action.

The full grammar, with why it changed and the migration table, is spec/SYNTAX_V2.md.

Added

4

wf migrate

wf migrate [path] [--check] [--stdout] rewrites every .wf under src/ in place — spelling only: the migrated project builds to what it built before. What needs a decision is reported as a note. --check reports without writing; --stdout prints one file's result.

The registry

src/registry describes every built-in once — its positional prop, props with their types and enum cases, flags, events, slots, parts, attribute families — and the compiler's checks, the linters, the language server's hover and completion, the tree-sitter vocabulary check and the tests all read it. The secondary tone reaches Badge, Text and Icon; Spinner has sizes and no tone.

The type checker

Gradual and structural: everything it cannot resolve is Any, which agrees with everything, so every existing project checks without an annotation, and each annotation — state x: [Todo], a prop's type, a type's fields, resource x: [Deploy] — narrows what it can say. It reports, as errors with hints: a value of the wrong type (T01), a case an enum lacks (T02), a value that may be null read without if let, ?? or a != null check (T04), a field or method a record lacks (T05), a member a store lacks (T06), a list or record as a condition (T07), a for over a non-list (T08), an emit that does not match its event (T09), a call with the wrong arguments (T10), a match with nothing to match (T11), and a bind: on a control of the wrong kind. Specified in spec/TYPES.md.

Motion

The universal props — an animation as a flag (.fadeIn), exit:, .fast/.slow, duration:, delay:, easing:, stagger: — on any element, built-in or the project's own. On a branch's root they are the branch's; anywhere else the element plays its own exit before it is removed, wherever it was. A keyed list slides a moved item from where it was. Router(transition: .fade | .slide, duration:) plays one page out and the next in. transition { } blocks take $token timings. prefers-reduced-motion is honoured by the runtime as well as the stylesheet: no class, no wait.

Compiler diagnostics

Errors now: a parse error, a reference to nothing, a flag, case, part, prop, event, slot or layout nothing declares, an ambiguous flag, a positional argument out of place, a match arm the value cannot take, a loose statement in a render block, a clause out of order, the type checker's findings, and a file in the old grammar. V01 names the flag you meant (` did you mean .center? `); a named argument a built-in does not declare is a warning and is written as an attribute.

Tooling

  • Language server: hover and completion are driven by the registry and the type checker — flags after ., cases after tone: ., $tokens in a style value, events after on, a component's events after emit, the arms a match still lacks, a component's slots, layout: candidates, props not yet written, a record's fields and a list's methods after a typed value; hover shows a flag as the prop it sets and a name's inferred type; go to definition follows layout:.

  • Editors: the tree-sitter grammar is rewritten for the new grammar (a small external scanner reads style values), with the Zed queries and snippets and the VS Code TextMate grammar; every .wf in the repository and in Halyard parses without an error node.

  • Structured edits (EditOp) write the grammar of the file they edit: AddModifier appends a flag, SetStyle writes a raw value.

  • The documentation's wf blocks are parsed by the test suite (tests/docs_parse.rs), so an example cannot go stale.

Breaking changes

6

  • The old grammar is refused. wf build, wf serve, the template engine, the language server and the Node binding read WebFluent 3 only. Run wf migrate.

  • A Button's block of statements is no longer its click handler; write on click { }. The migrator does.

  • A word nothing declares is an error, where it used to be the V01 warning; Alert(elevated) and its V02 are gone with the modifier words.

  • The runtime's public surface is renamed for what each thing does: h→el, condRender→when, listRender→each, showRender→show, wfFetch→fetch beside the new resource, createStore→store, createRouter→router, definePage→page, showToast→toast, bindDialog→dialog, bindPopup→popup, tablist→tabs, offCanvas→drawer; new match, mark, emit. The compiler and the runtime ship together; nothing outside a build's own bundle should have named these.

  • t("key", name: value) never parsed; interpolation takes a map: t("key", { name: value }). The documentation said otherwise.

  • Library: webfluent::parse_source(src, file) is the one way in; Lexer/Parser of the old grammar are #[doc(hidden)] behind wf migrate. Expr::Record is a new expression; sema::check, sema::types::check and sema::lower run between parsing and codegen, and the linters see the lowered program.

Fixed

5

  • A list was rebuilt whole on every change, losing focus, scroll and animation state in items that had not changed; for … by key keeps the nodes of the items that stay.

  • The route table depended on source order; it is now ordered by specificity, then path, whether the Router had children or not.

  • easing: on an element was accepted and ignored; it sets the timing function, and spring, smooth, bouncy, easeOut and the rest mean the same there as in a transition block.

  • A multi-line call that gained motion props from a migrated animate(…) clause had them written on the closing parenthesis's line; they take a line of their own.

  • Lint hints spoke the old grammar (Heading("Page Title", h1)).

Migrating

  1. Install 3.0 and run wf migrate in the project. Read the notes it

prints: each names a file and a line where the migrator could not decide — a modifier word no spelling exists for, an imperative fetch to rewrite as let x = await fetch(…). Commit the result; wf build is byte-identical for a project that needed no notes.

  1. Expect errors that were warnings. A misspelled flag, a prop a

component does not declare, a case an enum lacks: the build stops and says what it takes.

  1. Annotate what you want checked. Nothing is required; `state items:

[Todo] = [] and resource r: [Deploy] = fetch(…)` are where the type checker starts to see.

  1. If anything of yours named WF.* runtime functions — a custom

stylesheet does not, a script in index.html might — rename per the table above.

  1. Zed users: the extension's 2.0 pins the new grammar; the old one

highlights nothing useful on migrated files.

2.2

#2.2

19 September 2026

A release about what a built site is like to use and to load. The Halyard demo (https://github.com/monzeromer-lab/Halyard) was put in front of Lighthouse and a screen reader, and everything either one found that the compiler could have prevented, it now prevents; the same site also asked for stylesheets of its own. Halyard's pages went from 63–71 to 87–99 on mobile performance and to 100 on accessibility, with every finding that remained pointed at by wf build. Nothing in this release is breaking.

Added

4

Your own stylesheets

Any .css file under src/ is part of the build: read in path order, bundled into styles.css after the engine's rules and before the rules style { } blocks compile to, minified with the rest. var(--token) reaches every design token. An element names a rule with class:, which adds to the engine's classes rather than replacing them, and follows state:

Card(class: "feature feature--first") { … }
Heading("Forms", h1, class: if loud { "hero--loud" } else { "" })

V02 accepts a modifier class one of these files defines (.wf-alert--elevated makes Alert(elevated) real), in the build and in the editor.

Form fields

Input and Select with label:, hint: or error: become a field: the label is a <label for> the control, the hint and the error are linked by aria-describedby, the error (a string, empty when there is none) is a role="alert" hidden until it has text and sets aria-invalid. The static paint and the client agree, so hydration adopts it.

Input(text, bind: name, label: "Name", hint: "As on your passport", error: nameError)

Accessibility in the runtime

  • A route change settles the reader on the new page: focus moves to its heading (or the main landmark), the viewport returns to the top, the title is announced in a polite live region.

  • Carousel is a labelled region whose slides are groups; it has named previous/next/dot controls, a pause button, stops for reduced motion and hidden tabs, and hides the slides that are not showing from assistive technology.

  • Tooltip opens on focus as well as hover, closes on Escape, and describes its trigger with aria-describedby.

  • Dropdown menus follow the ARIA menu pattern: role="menu" with menuitems, arrow keys, Home/End, Escape, and focus returned to the trigger.

Lint rules

  • A14 — a role: that requires particular children (tablist, menu,

list, radiogroup, …) holding something else. A user component is judged by its root element, and a role given through a prop by what the call passed or the prop's default.

  • A15 — an aria-label that does not contain the control's visible text:

its label, the literals in its block, and what a component in the block renders from its literal props (Kbd(text: "⌘K") in a search button).

  • Every element rule now points at the element's own line and column.

Build output

  • build.minify is honoured at last: the bundle and the sheets lose their

comments and whitespace, and nothing else. Halyard's app.js: 691 KB → 212 KB.

  • build.split (on by default) writes each page as pages/<Name>.js,

linked beside app.js by a static page and fetched by the router the first time its route shows in a single-page build.

  • The stylesheet carries only the component rules the project uses.
  • Literal style { } declarations compile to shared classes instead of

inline styles — one rule for a hundred identical cards, on the static paint before any JavaScript runs.

  • The rules only one page can reach ship in pages/<Name>.css, linked by

that page and loaded by the router before it draws; what the App body or two pages share stays in styles.css. Halyard: 144 KB → 49 KB shared.

  • build.compress (on by default) writes <file>.gz beside every text

output over a kilobyte, with a DEFLATE encoder of the engine's own — within a percent of zlib's default level, no dependency — for hosts that serve a precompressed file when they have one. wf serve sends it, and compresses on the way out what has none, so a Lighthouse run against the dev server measures what a deployed site sends.

  • The static paint evaluates derived values and pure actions at build time,

so a seeded list is painted with its rows rather than left to hydration.

  • Images decode asynchronously; the first on a page is eager with

fetchpriority="high", the rest lazy, unless loading: says otherwise.

Editor support

The Zed extension and the Tree-sitter grammar were rebuilt from scratch and live in this repository (editors/zed, editors/tree-sitter-webfluent). The language server reads the whole project the way wf build does — a store declared in another file resolves, a component called across files is known — and reports positions in the units each client expects.

Fixed

4

  • class: as an attribute replaced the engine's classes; it adds to them.

  • A14 reported a component whose root took its role from a prop as a plain control.

  • wf serve read a query string as part of a file name.

  • The language server matched a document to its project by URL text rather than by path, and could miss a file with an escaped character in its path.

2.1

#2.1

19 September 2026

A release driven by building a real application. The Halyard demo (https://github.com/monzeromer-lab/Halyard) — a nineteen-screen product design implemented entirely in .wf — found every place where the language did less than its documentation promised, and a handful of things a design system needs that it had no way to say. Each is fixed or added here, with a test. Nothing in this release is breaking.

Added

3

State and media in style { }

A style block may now hold blocks for how an element looks while hovered, focused, active, disabled, or in an ARIA state, beside its @media blocks:

Button("Save") {
    style {
        background: "var(--brand)"
        hover { background: "var(--brand-hover)" }
        focus { outline: "2px solid var(--focus-ring)" }
        pressed { color: "var(--text-accent)" }
        @media (max-width: 768px) { width: "100%" }
    }
}

States: hover focus active disabled placeholder focus-within current pressed selected checked expanded invalid. The ARIA ones key off the element's own aria-* attribute, so state and paint cannot disagree. These compile into styles.css under a content-hashed class — one rule per distinct block, shared by every element that writes it, and nothing injected at run time (CSP-safe). @media blocks, which used to become a run-time <style>, take the same path.

Attributes by name

A hyphenated named argument is an attribute: Trow(aria-selected: isSelected), Badge("Ready", data-tone: "success"). A value that reads state follows it, and an aria-* value of false is kept as the string "false", which is a real ARIA state. A keyword after the hyphen is fine (data-state:).

Custom properties and reactive style values

style { --edge: color } sets a custom property. Any style value that reads state is now kept in step with it, so style { height: "{pct}%" } moves.

Components

  • A component's block reaches it as children, in both the SPA and SSG backends. AppShell(crumb: "Logs") { … } is one component.

  • Props are live: Chip(pressed: showErrors) repaints when showErrors changes. Declared defaults reach the SPA.

  • A handler written on a component call — the click shorthand or an explicit on:… block — attaches to the component's root element.

Vocabulary and layout

  • Row/Stack/Grid gap: xs|sm|md|lg|xl, align: and justify: (six

values each) are real utility classes in both stylesheets.

  • Modifiers fluid circle multiple ordered xs sm md lg xl header:

List(ordered) is an <ol>, Tcell("Build", header) is a <th scope=col> wherever it is written.

  • Table(caption: "…") gives the table a visually hidden caption; a Tcell

inside Thead is a <th>.

  • Link(to: "/docs", active: "prefix"): links get .active and

aria-current="page" from the router, on the static paint too.

  • Option("value", "Label") submits the value and shows the label.
  • Theme token and property names may have digit-leading segments

(viz-1, radius-2xl).

Config

meta.fonts and meta.stylesheets add <link rel="preconnect"> and <link rel="stylesheet"> to both HTML shells; the CSP policy widens for those origins.

Language

Two-parameter lambdas (a, b) => expr; a keyword after a dot (Array.from); Number, String, Boolean, Map as globals; a map literal as an arrow body; store derived values may read other derived values and actions.

Fixed

18

  • Icon("home") rendered the word "home"; only icon: drew the glyph.

  • IconButton dropped every named argument but icon and label, and the static backends painted the label as visible text next to the glyph. It is the accessible name (aria-label, title) only, and the glyph is drawn once.

  • Progress(value: expr) was painted once and never moved.

  • Lambda parameters inside pages compiled as signal reads (_x()).

  • An action parameter named like another action read the store member (move(step) beside step).

  • placeholder, disabled, src and the other recognised attribute names were set once even when bound to state.

  • A <select> bound to state always showed its first option: the value was applied before the options existed (runtime), and a slot inside a Select component was appended after the value (codegen).

  • An else if chain with a final else skipped every branch.

  • A Slider or Input with both bind: and on:input kept only one.

  • A Button's block that mixed content with an action ran the action at render time; the action statements are its click handler now.

  • A sub-component dropped its style block, attributes and handlers in the SPA.

  • createStore bound derived values before actions, so a derived value that called an action threw.

  • The router never set document.title.

  • wf build did not run the V01/V02 vocabulary lint or the semantic check; it does, with per-file locations.

  • The catch-all page was written to a directory literally named *. It is 404.html at the root, and it addresses its assets from the site root, so a dynamic route under a static build hydrates.

  • wf serve did not serve a pre-rendered <route>/index.html.

  • The heading-outline lints (A11, A12) could not see headings inside components; A03 did not accept aria-labelledby; A13 warned about a white label on --color-primary even when no primary variant was used.

  • In structural mode the sheet stacked every Row under 768px; it no longer paints layout decisions the author did not make.

2.0

#2.0

Not released yet

A release about correctness. The language gained themes and SEO; the output gained the accessibility, responsiveness and search metadata it should always have had. Several long-standing bugs are fixed, and the tests that would have caught them now exist.

This release contains breaking changes. See Migrating at the end.

Breaking changes

4

Themes are written in WebFluent

The four built-in palettes (default, dark, minimal, brutalist) are gone from the compiler. A theme is source now:

Theme Brand {
    token color-primary: "#0F766E"
    token radius-md: "14px"
}

Declare one and it is used; declare several and select with "theme": { "name": "Brand" }. Tokens you do not name keep their baseline value.

dark, minimal and brutalist ship as examples/themes/*.wf — copy one into your src/ and the existing "name" in your config keeps working. A config that still names a removed palette fails the build with a message pointing at the replacement, rather than silently rendering as the default.

theme.mode and theme.extends were declared in config and never read by anything. Both are removed.

Modal and Dialog are native <dialog> elements

They were divs with an .open class, which meant no focus trap, no inert background, no Escape-to-close and no aria-modal. They now use showModal(), so the browser supplies all four. If you styled .wf-modal directly, note that it no longer positions or hides itself — the element does that — and the backdrop is ::backdrop.

Library signature changes

  • generate_css(tokens) / generate_css_with(tokens, builtin) take resolved tokens rather than a theme name. Use themes::resolve_tokens(program, config).

  • render_page_html / render_page_html_studio take a SiteContext instead of five separate parameters.

  • generate_html(config, program) takes the program, for the page metadata.

  • Template::with_theme(name) selects a Theme declared in the template rather than naming a built-in palette.

Fixed

11

  • for loops produced bundles that crashed. The loop bound a plain callback parameter but every reference to it was emitted as a signal read, so any non-empty list threw ReferenceError on first render. wf init -t spa shipped this.

  • Zero-width spaces in every static page. The SSG and template renderers emitted U+200B after every closing tag — invisible in an editor, present in textContent, in copied text and in what a crawler indexed.

  • Heading("x", h1) did not produce an <h1> under wf build. The static renderers switched the tag; the SPA codegen never did, and emitted a wf-heading--h1 class no stylesheet defines.

  • style { } blocks were dropped on nineteen components — every one handled by a dedicated emitter, because styling was applied after the dispatch that returned early.

  • The sidebar rendered transparent — no background at all in structural mode, and surface-on-white behind a 1.23:1 border in the full one.

  • Navigation vanished on a phone. The sidebar was display: none below 768px and navbar links below 480px, with no control to bring either back. Both are off-canvas now, with a toggle, a scrim, Escape-to-close and focus return.

  • Structural mode had no focus indicator at all, and .wf-input / .wf-select removed the outline without replacing it visibly.

  • theme.builtin: "structural" never reached wf build — only the studio honoured it.

  • The language server had not compiled for several releases. Nothing in the repository built it; cargo build at the root builds the root package alone. Its completion list had drifted to 43 missing modifiers and eight invented ones.

  • Link("Home", to: "/") drew a spurious accessibility warning, and both the PDF and slides scaffolds warned on their own first build.

  • PDF images ignored their alt and drew [Image] regardless; Progress(max: 0) rendered a full bar instead of an empty one.

Added

Search and sharing

Set meta.site_url and every page gets a self-referencing absolute canonical, Open Graph and Twitter card tags, hreflang alternates with x-default, and JSON-LD (WebSite, Organization, WebPage/Article, BreadcrumbList). Builds write sitemap.xml and robots.txt.

Page accepts description, image, type and a bare noindex.

Without site_url, tags that need an absolute URL are omitted rather than guessed at — a relative canonical causes problems later.

Accessibility

Tabs carry the full tablist/tab/tabpanel wiring with roving tabindex and arrow keys. Dropdowns report aria-expanded and close on Escape. Toasts and alerts are live regions. Every page has a <main> landmark and a skip link. Animations respect prefers-reduced-motion. Pointer targets meet the WCAG 2.2 minimum of 24×24.

Performance

The type and spacing scales are fluid (clamp()), so a page responds without a media query — and without losing to an inline style { font-size: … }. Images default to loading="lazy" and decoding="async". The bundle loads with defer. The default font stack no longer names webfonts nothing loads.

The static renderer now paints lists and conditionals over seeded data instead of leaving <!--wf-for--> for the client.

Security

"build": { "csp": true } emits a strict CSP and a _headers file. The dev server sets nosniff, Referrer-Policy and X-Frame-Options.

Diagnostics

A13 (theme contrast, checked at compile time because themes are now source), S01–S04 (title, description, description length, duplicate route) and V02 (a real modifier whose class no stylesheet defines).

For tooling

CompiledSite carries the resolved tokens, the declared themes with their spans, flattened diagnostics, and the reason a theme failed to resolve.

Migrating

  1. If your config names dark, minimal or brutalist: copy the matching

examples/themes/*.wf into your src/. Your existing "theme": { "name": … } then resolves to it. The build tells you this if you forget.

  1. Remove theme.mode and theme.extends if present; they are ignored.
  2. If you styled .wf-modal or .wf-dialog directly, re-check it against a

native <dialog>.

  1. Add meta.site_url to get canonical URLs, sharing cards and a sitemap.

Nothing breaks without it; those tags are simply not emitted.

  1. Expect new warnings. S02 fires on every page with no description. None

of them fails a build.