Reference
Changelog
What changed in each release, newest first. Every version has its own address, such as /changelog#6.0.0.
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.
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 isE101, a wrong valueT01), formatted bywf fmt, and left out of every build. A///above it is the words beside it;fakes:answers what it calls. -
wf docswrites 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
.jsfile undersrc/, 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,fakeandexamplein the outline, go-to-definition, references, rename, completion and hover; atests/file read with its project; an api group's endpoints; browser globals and their members;toast,ask,announceandhttp;t("key")goes to the key and$tokento the theme; its snippets write what 7.0 checks. -
The grammars (Tree-sitter, Zed, VS Code) parse and colour
example,middleware,fakeand the service words, readw / 2 + h / 2as division and{key: value}in prose as text, and knowJson. 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 --jsonand 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; aButton(to:)navigates without a strayhref;.roundedis rounder corners, not a pill; an outlined secondary, success, warning or info button is coloured. -
A
.closabledialog 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
Selectbinds every choice; aNumberInputis held to itsmin:andmax:; aComboboxsearch answered by an endpoint shows its list. -
direction: .columnturns aRow; aTabs.Page's.disabledand aStepper.Step's.doneand.errorflags are read;Sticky(bottom: true)sticks to the bottom; aCarousel'sautoplay:may follow state; a hand-writtenCallout.Titleis the only title. -
Statwith noformat:writes its value asformatdoes;Imagekeeps theloading:it is given;landscape: falseis portrait. -
format(value)shows text that is not a number as it is. -
A
Gridof more than twelve columns, and a value per breakpoint on a prop that is not a layout's, areT01.
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,typeandpresspass over a control in a closedSheetorModal, a hidden branch or anything underinert, 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. -
expectreads what is drawn above the page: an open dialog, such as the oneask(…)draws, and the toasts. -
A page and a component may each have an async action of one name. A component's
pendingnow belongs to each instance, so two cards side by side no longer join each other's calls, and a test page no longer stops onIdentifier '_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
matchon astreamno longer throws: a stream has aclosure, and its.messagesandon message(m)hold what it declares it receives. -
afterandeverytake aDuration—after(3.seconds)— as the guide shows. -
A13checks the dark theme as well as the site's. Thespastarter's dark theme and the tutorials' now name a label colour that clears it. -
A state read only as a
persist'skey:is not reported unused, andN08no longer suggestswindow.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 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
-
Anywritten as a type isT23,MapisT24, each with a fix that writesJson. A record (type Price { … }) or a dictionary ([String: Number]) says more, where you know it;Jsonis JSON whose shape is open, matched or decoded before it is read.wf migratewritesJsonwhere that leaves the project with fewer errors, and leaves theT24of aMapread 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 --holesreads 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 anifare the enum wanted (if c { .open } else { .all });pop,shift,at,unshiftandindexOfare typed;groupByis 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 givesJson; 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]isT23.
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,PUTandDELETE. APOSTorPATCHthat 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 aPUTor aDELETEmade with no network is kept and sent later. APOSTor aPATCHfails as.offline, and the page decides what to do.
Requests that never went, or went wrong
7
-
A resource's
body:andheaders: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, andBackend.invalidate()every one over the service. It used to drop the cache and leave the screen as it was. -
A call's own
headers:andretry:were sent in the query string (?headers=[object Object]); they are the request's again. -
A
Fileparameter is sent under its own name:post avatar(image: File)sendsimage, where it used to need the namefile. -
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
Filelooked the same. -
A store's
await fetch("/x/{id}")encodesidas 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 wasT13, nothing declarescode. -
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(…)isT01when the endpoint returnsUser. -
A resource has
reload(),invalidate(),loadMore()andcancel();rows.relaod()isT16.
Types a program can write
7
-
Dictionaries,
[K: V]: keys ofStringor an enum, values ofV. Reading a key gives aV?;keys(),values(),entries(),has(k),with(k, v)andwithout(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 wroteaction(String). -
Aliases,
type Scores = [String: Number]. -
-> Ton an action: what it returns, held at everyreturnand 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— writtenJson.string("x")and read bymatch. 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)withe.at(where) ande.message(what). -
Results,
T ! EandT!, matched by.okand.err; an action may declare-> T ! E,-> ! Eor-> !.
A call that fails says how
8
-
An endpoint declared
-> T ! Eor-> T!returns a result,.ok(value)or.err(error), and never throws.Eis an error enum: a case for each status the service answers with,unprocessableContent(problem: ValidationProblem) on 422, carrying that status's body, and onehttp(error: HttpError)case for everything else (N12holds an enum that names a status to that shape). -
HttpErrorandProblemare 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. -
trygives a result's value, or returns its error from the action as the action's own (N03where the action cannot hold it). In a handler it reports the failure. -
An action declaring
-> T ! Ereturns its value, which is.okof it, orreturn .err(e);-> ! Eand-> !return nothing and may fail. Its.resultis its last outcome. -
Patterns:
_, a literal, and a case inside a case —.err(.http(.status(503, _)))— in amatch, which now runs inside an action or a handler too, and inif let .err(e) = outcome. -
An action that returns a value says what with
-> T(T26, an error;wf fix --code T26writes 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 atryin it passes a failure up, and is.okwhen 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(…)isN08. It threw on a failure the page rarely caught, and its answer wasAny. A resource or a call with nomethod:is rewritten tohttp.get(…); a write becomeshttp.post(…)(orput, …) by hand.window.fetchis still the browser's own. -
An endpoint that does not say how it fails,
-> T, isN08: it is now-> T!, which the fix writes. Anerrors { 422 -> T }block isN08too: name the status in an error enum,unprocessableContent(problem: T) on 422, and write-> T ! ThatError. -
AnyandMapwhere a service meets the program — an endpoint's parameter or answer, a resource's annotation — and anhttp.getwhose answer has no type areN11. Declare atype, or nameJsonfor JSON whose shape is open; the fix writesJson. -
An endpoint read from an OpenAPI file answers with a result,
T!, and a failure's body arrives in theHttpError'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 andwf typesread:JSON.parsehands backJson,localStorage.getItemaString?,setTimeouttakes a function and milliseconds. A global or a member the table does not list isT30, 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 aKeyboardEvent,on click(e)aMouseEvent, and so on through the DOM's events;targetis anElement. The gestures hand over what they say (on swipe(s)'ss.direction), and a dragged value arrives asJson. -
Handles. A
ref:is anElement(focus(),value,scrollIntoView(), …). A connection is typed by itssendandreceive,Jsonwhere it names neither, sochat.sned(m)is found. -
catch eis anError—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.
envis a record of the names the build knows (env.PUBLIC_APIIisT05),queryis[String: String], a page'sparamsa record of its own route parameters,localeanddirStrings, and a form'serrors[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: aDataTable'skey: r => r.id, a column'svalue: r => r.nmae(T05), acell(r).wf registry --jsonand 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. Amatchcovers every case or sayselse: one with no.failedarm isT21, now an error, and one missing another caseT15.if let .failed(e) = users { … }takes one case, and amatchexpression reads one too. -
A failure is what
.errholds for the same request — anHttpError, 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?) andpending. -
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: .previouskeeps 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 itson request,on responseandon errorhooks with one mechanism:middleware [ refreshOn401(Session.refresh), bearer(Session.token), requestId ], steps run in the order written, each around the next. The runtime's arebearer,header,refreshOn401,requestIdandlog; a project writes its own asmiddleware name(req, next) { … }, typed by what a middleware is. Three requests that hear401at once share one refresh, since a running action is joined. The old forms areN08. -
The cache follows the server (RFC 9111, a private cache): a
GETis kept only whenCache-ControlorExpiresallows, for itsmax-ageless itsAge, stale withinstale-while-revalidate, revalidated withETag, never underno-store, kept apart byVaryand the credentials. With no caching headers nothing is kept — before, an endpoint kept what itscache:said whatever the server answered.cache: .maxAge(d),.swr(d),.noneand.foreverstill override it. -
Every answer is checked, in every build: what an endpoint or a
resourcedeclares it returns is held to what arrives, deployed as underwf serve, and a server that breaks its contract fails as.decode(at, message). -
idempotenton an endpoint —post order(body: Order) at "orders" -> Order! idempotent— sends oneIdempotency-Keywith every try of a call, and lets aPOSTorPATCHbe retried and replayed offline;retry:on any other write isN09, and does nothing. -
A call gives up after 30 seconds unless its service or the call says otherwise.
Contracts and writes
7
-
atis 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 areN08, andwf fixwritesat "<name>"and{id}. -
Headers and cookies.
token: String in header "X-Token"andtheme: String? in cookiesay 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 asBackend.todos.list(). A group sends what its service sends; its ownbase:,retry:ormiddlewareisN08. -
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(…), thenundo()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,PATCHorDELETEwould send it again each time the page draws, and isN02. A call's result awaited on its own, so that a failure is never heard, isN04.
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
derivedvalues 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 areT35. -
A state says what it holds when its first value does not:
state items = [],state picked = null,persist prefs = {}and open JSON areT25, and the fix writes the type the body assigns —items = items.concat([Todo(…)])givesstate 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
.wfwith none isT31, and the fix writes a block from the call; a union or a bareArrayisT31too.{*}isJson,{Object<string, T>}is[String: T],{HTMLElement}isElement, a function with no@returnsgives nothing back, and a class is a type whose members are its JSDoc'd methods. -
@typedefis 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
@returnsnames a type is held to it as it returns or settles, and a mismatch throws aDecodeErrornaming the function — so a value typedRowis aRow, underwf serveand deployed alike. -
A parameter or state may name what the browser hands a program —
action run(e: KeyboardEvent),node: Element— andnow(every: …)is aDateTime, asnowis.
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
Useris checked as a literal written there is: a field the record lacks isT05, a required one left outC01, one of the wrong typeT01.{ ...todo, done: true }is aTodoagain. -
One value, one type (
T27).if ok { 1 } else { "none" },[1, "a"]andday ?? "none"withday: Date?have no type in common, and are refused where they meet instead of becoming a value the checker cannot name.nullon one side still makes the valueT?. -
A condition is a
Bool(T29).if count,show name,!countanduser || fallbackare refused; the fix writes what each asks —count != 0,name != "",count == 0,user ?? fallback. ABool?is a condition, itsnullfalse. -
No conversions (
T34,T18). ADate, aTimeor aDateTimeis shown through a splice that says how —Text("{due:.date(long)}"), notText(due); aDurationand aNumberare not added (3.seconds + 500.ms), though a duration is scaled by a number;"Total: " + nis"Total: {n}". AUrl, anEmail, aColorand aUuidare strings wherever text is wanted. -
Jsonis matched or decoded (T28).raw.name,raw[0],raw + 1andraw.keys()assume what nobody checked;User.decode(raw)checks it. A connection that receives something says so —receive Message— andon message(m)is then one. -
Input(…).timeand.datetimehold aTimeand aDateTime.
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
datafile at build time.data posts: [Post] = "posts.json"holds the file to[Post]when the project is built: `posts.jsonis not whatdata postssays 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 isT13. A page that declares no parameters reads its data by name, as before. -
A test's seeds before it runs.
data: { count: "two" }for astate count = 0isT33, and a store member the store does not have isT05. -
A
persistvalue 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)orpages .link(the answer'sLinkheader, RFC 8288). A read of it holds every page's items, typed, with.items,.hasMoreand.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.loadedfrom 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.offlinecarriesqueued. -
What happens to it later. Once sent, what its endpoint
invalidatesasks 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 innetwork.refused({ method, url, status, at }) untilnetwork.clearRefused(). -
N14refuses apagesorstreamedthat cannot work: on a write, a page parameter the endpoint lacks or the first call must give, a cursor with nonext:, a page that is not a list with noitems:, a streamed answer that is not a list, andfor awaitover anything but a streamed call. -
paginate:on a call isN08. Its.items,.hasMoreand.loadMore()stay;pages .number(param: page)moves to the endpoint, and thestate pagethe 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 anifor amatchfrom 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'sfakes:naming no fake or two that answer one endpoint; anexpect callednaming no endpoint. -
test "…"(fakes: [OneUser]) { … }runs in a browser with those fakes answering. Nothing is sent: a write'sinvalidatesasks 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; astreamedone with the whole list, a line at a time. -
expect called Backend.users.createandexpect not called …check whether the page asked an endpoint. -
wf verify --fakes tests/fakes.wfbuilds 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 renderdata.{ "users": { "loaded": [ … ] } }paints aresource users'.loadedarm (and{ "failed": … }its.failedarm), 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 Backendrecords the service in the config's newapis, writessrc/api/backend/service.wfonce (yours: the base, the timeout, middleware), marks the generated folder in.gitattributes, and writesgenerated/:types.wfand one file a tag. -
wf api syncrewritesgenerated/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 bywf api sync… DO NOT EDIT.--skip NAMEleaves an operation out, and the config remembers. -
wf api checkexits1whensyncwould change anything, for CI, andwf checkwarnsN07.wf api eject Backendturnsapi Backend from "…"into files;wf api listshows 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,defaultfor an operation with none). Every error status is a case of the operation's error enum (CreatePersonError,notFound(problem: Problem) on 404), a4XXits 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 itsdefault. 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 isJson, neverAny; a field no program can name is quoted ("first-name": String?).x-invalidatesandx-paginationare read. -
The editor and
wf renderread the spec as the build does: a call of an endpoint fromapi … fromis known in hover, completion and the problems list. -
invalidations { }andpagination { }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 examplesanswers 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},atwhere there was none,headers { }→middleware [header(…)]), what eachstateholds, each action returns and fails with (-> ! Efor atryin 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),trywhere a result's value is wanted, an error enum'shttpcase (N12). -
Then what a person decides, listed by place — an
on requesthook to write as middleware, apaginate:to move onto its endpoint — and the changes that need no edit: aPOSTis not retried unlessidempotent, nothing is cached unless the server says so, every answer is checked.--checksays what it would fix and writes nothing; a second run finds nothing. -
New fixes in
wf fixand the editor, from the same work:T34,N12,N03,headers { }, andtryfor a result's value. -
A project whose output is outside it (
"output": "../docs") is migrated too: the step writes no output. -
T20is an error: a list or a record shown as text.lintsand// wf-allowcannot 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,-warningand-infoare 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, andA13checks each pair. A theme with a pale tone may draw newA13warnings. -
Alerts, focus rings, highlights and stars are mixed from the theme's colours, rather than fixed tints, and
color-backdropdims the page behind a modal, a dialog, a sheet and a drawer. -
A
ModalorDialogis as wide as its<dialog>, soclass:orstyle { width: … }on it sizes what it shows. -
The structural look keeps a
Popover's box, and toasts take the theme's font. -
The
spastarter's own dark-mode button isDarkModeSwitch, so it no longer hides the built-inThemeToggle.
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"sendspage-size=20when 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.applyreaches any named control of the form, not only one avalidateblock 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: aFile?, or with.multiplea[File](F02when 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 toT, as aresource's answer always was. -
wf renderholds a read's data to its endpoint's type when the read names none, and draws.loadedfor amatchwritten with.loaded(v)andelse. -
wf api addwrites an endpoint with a text answer (-> String! as: .text) that parses, andwf api checksays whatsyncwould do rather than what it did.
Removed
1
-
WF.fetch, the runtime of WebFluent 2'sfetch x from url { … }, which nothing the compiler writes has called since 3.0.wf migratestill rewrites that grammar.
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) andtarget-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'svalue:;Tabs(value: v)reads it andon change(v)hears the one picked, so a tab can live in the address. A page can bedisabled:, a strip.vertical, and.manualopens 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")andon key("inline-end")are the arrow toward where a line starts or ends, swapped in a right-to-left box. -
wf testhasexpect focus "Beta", and aclickstep puts the focus where a real click would, so the keys a test presses next go there.
Overlays on one path
10
-
Modal,Dialog,SheetandPopovertakedismiss:—.any(Escape or a press outside, the default),.escape, or.nonefor what must be answered — andinitialFocus:, theref: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. -
Sheetis new: a modal from the bottom, or the start or end of the line, dragged shut by its handle or heading, withsnap:points for a bottom sheet. -
AlertDialogis 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, withaction:andonAction: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
Sidebarholds the focus, closes on a press outside, and is one of the layers Escape closes in turn. -
A18warns of aPopoverwith no name;A08coversAlertDialogandSheet.
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
Buttonwhoseon click, or aFormwhoseon 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 verifynames each control drawn under 24×24, as a warning.
Content built-ins
13
-
Callout("Run wf check first.").tipsets a note apart, as GitHub's alerts do:.note,.tip,.important,.warningor.caution, each with its icon and word, or atitle:of its own. -
Kbd("mod+k")is a key as this system writes it:⌘Kon 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.linesis a block of code with its file name, a copy button and line numbers. -
Chip("Rust", icon:, selected:).removableis a compact label that can be pressed (a toggle button) and removed (on remove);Tagstays the one that does neither. -
VisuallyHidden("(opens in a new tab)")is words for a screen reader only. -
CopyButton(value: url)copies, saysCopiedand announces it. -
ThemeToggleswitches light and dark;LocaleSwitchoffers each ofi18n.localesin 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").cardsis 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 acell(r)block, anemptyblock and rows chosen bybind:. -
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;
E103names 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).halfis stars a keyboard can set;.readonlyonly shows. -
Slider(bind: price).rangehas two thumbs. -
DateRangePicker(bind: stay, presets: [.last7])chooses a range in two months, or by a preset. -
Textarea(…).autosizegrows with its text;Input(…).password.revealshows the password on a press;FileUpload(bind: files).dropzonetakes files dropped on it, each shown with a preview and a button to take it out.
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: ameta.scriptsentry marked"load": "consent"loads only once they accept, and Decline is as easy as Accept.
More for showing and laying out
7
-
DescriptionList,Timeline,ItemandAvatarGroupshow pairs, events, rows and people. -
Gallerylays pictures out in a grid of one shape;Masonryplaces anything in columns at its own height. -
CircularProgressis a ring;Meteris 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)says3 minutes agoand keeps saying it. -
AspectRatio,ScrollArea,CenterandStickyhold 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; apersistkeeps the sizes.
The last of the built-ins, and blocks
6
-
ColorPicker,TransferListandEditablechoose a colour, move things between two lists, and edit text in place. -
Fabis a floating main action, a speed dial withFab.Actions;BackToTopappears once the page has scrolled. -
Popconfirmasks 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— orpricing,dashboard,settings— writes a whole page intosrc/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. -
GalleryandMasonrytakecolumns:per breakpoint. -
TourandLightboxtake 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 aforor anif. -
The keyboard checks of tabs and toolbars run again right to left.
-
wf testdrew a built-in where the project had a component of its name in another file. -
x ?? ywherexcould only benull(a field writtennullin a map) was taken to benulltoo, and spliced into text drewT19. -
-(x)wherexis negative compiled to--x, which a browser refuses, and the page did not run. -
format(v, .percent, 1)wrote2%once the page ran where the static paint wrote2.0%; both write the places asked for. -
A part's
mount:was written as an attribute and called with nothing. -
wf checkknows animage's fields:hero.width,.height,.colorand the rest were aT05there, thoughwf buildread them. -
wf test'spress "ctrl+k"holds its modifiers —ctrl,shift,alt,meta, andmod(⌘ on a Mac, Ctrl elsewhere) — so a shortcut can be tested by pressing it. -
A page on
/docs/*answers/docsand every address beneath it in the running site, as the link check always said; a static build paints it atdocs/index.htmlinstead of a directory named*. -
A page's
image:works out what it splices ("{CDN}{post.cover}"), astitle:anddescription:do. -
A
Link's ownaria-current:is kept: the router marks the current link only while the author's value isnull, and the static paint no longer writes the attribute twice. -
I03says what a reader sees: a locale with no file reads the default locale's messages, not the keys; underi18n.literalsthe default locale's table may leave out its own words. -
A
themedeclared twice is a duplicate (E102), and two pages that share a name no longer draw a puzzlingR05. -
The editors' indented-layout grammar reads an
ifvalue's branches and amatchvalue's arms written on the lines under them, aswf fmt --to wfxwrites 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 aBreadcrumb, and its search's kinds aToggleGroup; the tutorials use the built-inThemeToggle,EmptyStateandStat. -
The reference's list of DOM events named
focusinandfocusouttwice. -
A
Switchcan be reached from the keyboard and is heard as a switch. Its input wasdisplay: 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
Sidebarshut 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 aDialog's backdrop closes it, and itsvisible: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 aSplitterfollow 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.bottomStartlines up with its anchor's right edge. -
A
Carouselmoves to the next slide in the right direction, aSwitch'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,menuitemcheckboxwith its state, a submenu's entry and its hidden list — and aMenubar.MenuorContextMenu.Itemsdrawn by aforor anifas the menu it is. -
A live
Radiocarries itsvalue, as its static paint did: a form posted before the script runs no longer sendson. -
A
Menubaritem'sshortcut:runs it from anywhere on the page. -
ConsentSettingsasks the reader again;D06says when a script waits for consent and noConsentBannerasks 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 theidthe live page would give it), aLocaleSwitch's buttons, the rows of aDataTableand aTree, aRating's stars, aCircularProgress's ring, anAvatarGroup's+2, and the value of anEditable, anInputOTPand aTagInput.
Smaller fixes
3
-
An async action's
pendingstays true until every call of it has ended; the first of two calls to end used to clear it while the second ran. -
showwith 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.
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
coreshipped to every project. A build now keeps what runs at load, every function the program calls throughWF, and what those name, until nothing new is named;WFexports only what is called. A project's own scripts, anelementsbuild'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
WFkeeps 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.jsholds only each route's path and page name. -
wf build --statscounts 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
setThemegets a smalltheme.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 itst()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
appis 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
mainlandmark. A program that draws its ownmain(an element withrole: "main") gets a plaindivas 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 itsid,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. -
reduceandreduceRightat build time, so aderivedvalue folded with them shows in the static paint, a template andwf test. -
The browser compiler's preview without a service worker.
previewInline()incrates/wf-wasm/wf.jsserves a build throughrun.htmlwhere 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. -
E111inwf check: a theme the config names and the program does not declare.wf buildstopped on it whilewf checksaid "No problems". -
R05reads the site's language. A page with nolang:is inmeta.lang, so a translation written in that language is now caught. -
log(a, b)sayslogtakes one value and how to log several. -
A component or store member only a
testreaches is no longerU03orU04; at()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 threwholder is not a functionevery time. An action that used it without awaiting anything was written withawaitin 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)andStack(gap: gap)wrote the value as an attribute nothing reads, so the element kept its default look. A class prop (andgap,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 = $primarycompiled tovar(--primary), which no theme sets; a short name only one token group has is that group's ($color-primary). -
wf verifyis 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.
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">(anddir="rtl"for a language written right to left), with its ownog:localeandinLanguageon its JSON-LDWebPage. The router setslanganddiron<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 renderuses it when no--langis given. A site whose pages declared one language each used to ship every page inmeta.lang, so crawlers and link previews read its English pages as Arabic (#6). -
translates:on a page.translates: Homenames the page this one is a translation of. Pages joined this way, directly or through each other, list each other ashreflangalternates, each at its own address, canonical to itself and in its ownlang:, withx-defaultfor the one in the site's language, and name each other's languages asog:locale:alternate. A:parampage's translation is matched by its parameters (/en/posts/:slugfor/posts/:slug). -
R05: atranslates:that names no page or its own, or two translations of one page in one language. -
workeris offered where a statement starts, besidesocket,stream,channelandpeer.
Faster
3
Measured on the documentation site (77 files, 140 pages); cargo xtask
bench reproduces the numbers.
-
wf buildtakes 0.36 s instead of 4.4 s, to the same bytes:-
pages are painted, compressed and read back on every core;
-
a
dataconstant 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;
-
wfallocates with mimalloc.
-
-
wf checktakes 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 severali18n.localeslisted?lang=<code>for each as anhreflangalternate, 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 withtranslates: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 isE120instead 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, ahead { }tag and aFrameare 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. -
Templateanswers aswf builddoes: one evaluator and one renderer serve both, soname.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.
-
.wfxlexing is linear in the size of the file. -
Runtime: a disposed effect lets go of what it read; carousels, drawers, popups,
now,VirtualListand 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.outputoutside the project is refused unless--allow-output-outsidesays so,wf servelistens on this machine unless--hostsays otherwise and serves nothing outside the build, and apublic_envname takes no value from the shell unlessWF_ALLOW_SHELL_ENVnames it. -
wf verifyandwf testrun Chrome with its sandbox, in a private profile that goes whenwfdoes. -
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, aswf buildhas: a project whosebuild.outputis 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
workerandexpect not, outlines parts and persisted state, and has snippets forpersist,validate,on key,apiandtest. -
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,studioand 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
internalsfeature 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,VocabWarningandstudio::StudioDiagnosticare gone (rule_idiscode). -
Typed errors.
WebFluentError::IoError,ConfigError,CodegenError,EditErrorandNotFoundhold their own types, each a message and the error beneath it, whichsource()walks. Build one withWebFluentError::io(…), orio_with(message, cause)to keep the cause;?on anio::Errorkeeps it too. What an error prints is unchanged. -
#[non_exhaustive]onWebFluentError, the AST's enums that gain cases (Declaration,Expr,StatementKind,TypeRef,Step, …),Plan,Tag,OutputType,RuntimeMode,ScriptLoad,init::Template,memory::Contents,EditOpandArgRef. -
Dependencies are up to date: every crate at its newest release the crate's Rust version accepts,
taffy0.15 andminiz_oxide0.9 among them.usvg0.47 andfontdb0.23 stay wherekrilla-svgholds them. -
Every public
Resultsays when it fails; builders are#[must_use]; the lexer, parser and code generator implementDebug; a choice that was twobools 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 withlang:andtranslates:. -
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, …) needsfeatures = ["internals"], and pins an exact version, since those change in any release; -
a
matchon an enum above needs a_arm; -
WebFluentError::IoError(msg)as a value isWebFluentError::io(msg); as a pattern,IoError(e)binds the error, whosemessage()is the old string.
-
-
The editors pin this release: update the extension after it is out.
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.jsis 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 aswf check --format jsonlists them;check,explainandregisterFontbeside 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 underpreview/— 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 builddoes 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:compileandcompile_filesbuild a project from memory — no disk read, none written — with the findings and the output as values. It runs natively as well. -
webfluent::outfsis where a build writes: the disk, or memory insideoutfs::capture.webfluent::platformstands in for threads, clocks and the environment where WebAssembly has none. -
OverlayVfs::set_byteslays 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
Vfsit is given (Options::from_pdf_via,from_slides_via,reader_via), andpaged::fonts::register_fonttakes 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,pdfandbundled-fonts. A native build has all three whatever the features say, sodefault-features = falseleaves 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, asclass:does, on the live page and in the static paint. -
An
if letvalue whose branch awaits compiles.if let p = x { await f(p) } else { … }used as a value made a plain arrow with anawaitin it, and the page's code did not parse; it is now an async arrow, awaited. -
D01 reads
public/through the project'sVfs, as every other check does, so an editor's unsaved picture or a project held in memory counts as there. -
An
@font-facein a PDF is read from its bytes, not written to a temporary file first. -
The agents' skill says which compiler it is for.
just bumpnow sets the skill's version and its copy ofAGENTS.mdwith 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.
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-webfluentskill 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 onewfhas. The README says how to install it. -
wf initgives every new project the skill, in.agents/skills/and.claude/skills/; its language reference points at the project'sAGENTS.mdrather than repeating it. -
The reference has a part for agents.
AGENTS.mdgains "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.mdcovers 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-offandunlock. -
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_placecompares 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_withtakes the project's breakpoints, andagreesholds 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 aPairshape, andgrid-column/grid-rowaPlacement, each printed in the fewest words and edited one side or line at a time;cell,read_placementandedit_placementare what a drop in a grid writes. -
A token set by
theme.tokenscarries 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.
-
ChangeSetisClone, andabsorb_readstakes 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
resourcewithcache:whose request failed reported an uncaught error beside the failure itserrorarm 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, andkeyIsrefused 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.mdcompiles: theRow,GridandStackrows wrotegap: md(T13), key rule 20 wrote a deck in WebFluent 2 syntax, and others boundquery, named a loopt, used tokens no theme declares or bound aDatePickerto 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), listsE119,V12andI05as the warnings they are, adds rows forE005andT22, and documentswf render, six CLI flags,theme.dark,theme.builtin: "structural"andi18n.literals.wf initwrites this reference into a new project, so only awfof this release gives a project the corrected one.
Upgrading
Nothing to change: run wf check.
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": trueini18n, every string a reader sees (an element's text, itslabel:,title:,placeholder:,aria-label:andalt:, a record's text field, a value whose name says it is words, such ascaretTextoremptyLabel) 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'slabels:are words too.wf testtranslates the program as the build does. What no table can translate (a text splicing more than a name) is the new warningI05, 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 theartable and writesformat,agoand every count in Arabic-Indic digits;ar-u-nu-latnis 0–9 whatever the browser would pick. A date pattern's figures follow, andais AM or PM in the locale's words. The document'slangstays the language, so a stylesheet's[lang="ar"]still matches. -
t()in a store, andsetLocale()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 warningE119. -
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 aC04warning. A value that reads state is followed, so the frame redraws as it changes. -
A picture may carry itself: a
data:image/…address on anImage's or anAvatar'ssrc:, 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 anydata: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,lockandtype. An icon drawn in the browser now carriesdata-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, andwf assets --plansays which widths were dropped. -
output_type: "static"pre-renders every page, asssg: truedoes. 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::editreplaces eachold_textwhere 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::editmakes them on a file the set has read, and refuses one that moved since; a missing file isWebFluentError::NotFound.ChangeSet::editedshows what the edits would make of a file, before and after, without changing the set, andChangeSet::dirnames 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:
SetRuleStyleandRemoveRuleStylereach an@mediaor&:staterule, making it when there is none.SetStyleandAppendChildkeep the block as it is written, andSetProponCard.elevatedwrites the prop before the flags, where it wrote a call that did not parse. -
Template::with_studiowrites 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::ratiois public, and a theme's view names as unpaired every colour token the dark theme leaves alone, not onlycolor-*. -
wf commands --jsonreads 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, aconst, 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, andconst Map = 3threw 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) isE118, where the page threw as it drew; such a name now works as a prop, and__proto__as a prop isE118. -
A component call's handlers and attributes follow its root when the body's
iformatchdraws 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 testandwf renderpainted every call toderived 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 (
T06underlinesx, not the store), so the build and the editor agree. -
V01offers the dot for a flag written without it (Button(primary)), and no longer matches a two-letter word to any short name. -
F04no 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
expectreads 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
E102where 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.
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)andemit menu(k, x, y)is handled withon 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 longpressandon swipewritten on a component's call land on its root element, asclass:andon contextmenualready did. A component whose body is not one element has nothing for them to land on, which is the new error C07. -
Modal.Titleand.closable(chapter 9).Modal.Title { … }(andDialog.Title) is drawn in the heading in place oftitle:'s words, so a heading can set a name apart in code;title:stays the dialog's name..closableputs a close button, named Close, in the heading row. It closes the dialog as Escape does, soon closeruns andvisible:follows. Both work in the live page, the pre-render and the template engine. -
Source maps (chapter 39).
build.sourcemapwas 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.wfline 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 andmeta.lang, every visible string of the starter throught(), a language switch built from the locales, andsrc/translations/<locale>.jsonfor each. A tag that is not one, a tag named twice and an empty list are refused, and so are locales forpdfandslides. -
Three icons (chapter 28), 58 in all:
locatefor a panel that follows the caret,folder-offfor a folder that is gone, andfile-plusfor 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, aswf --versionprints it. -
BuildOptions::sourcemapasks for maps whatever the config says, for an editor's preview, andcodegen::sourcemap::SourceMapreads a map back and looks a place up, as a console does with a stack trace. -
init::create_with(dir, name, &Options { template, locales })iswf initwith locales;init::createstays the form without them. -
The language server knows a handler's names: hover gives each its type and completion offers them, where hovering
einon 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, soclick "Paste"finds an item that shows Ctrl+V. A submenu's entry is named by its label, not by its items:WF.submenupoints the entry'saria-labelledbyat its label, for a screen reader and forclick "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 declaredconst T06broke 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
closeevent, 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 testand the template engine, as the live page and the pre-render already did: a panel'semptytext, handed to a frame with anemptyflag of its own, came out as "false". -
A
Menu.Item'sclass:is added beside the item's own, where it wrote overwf-menu__itemand 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(Aabeside "Match case"). -
The components reference has an example of
Modal.Title,.closableandDialog.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.
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 spahasDayandNightthemes with a switch that callssetTheme, a task list that adds a task on Enter through aFormand asks in aModalbefore deleting one, a Settings page with validated fields, andtests/app.wfandtests/tasks.wf.wf init statichas a validated contact form with a required agreementCheckbox, English and Arabic translations, andtests/site.wf.wf testpasses in a new project. -
A test can place a whole page (chapter 24) by its name, as it places a component (
Tasks, thenclick "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, andclick "Name"also finds, by its name, an element whose role is a link, a tab, a menu item (aMenu.Item), an option, a tree item, a switch, a checkbox or a radio (chapter 24). -
on blurandon focuson a page (chapter 9). A page, a component orapphears 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 keydownandon keyupstill listen on the document. -
on auxclick,on focusinandon focusouton any element (chapter 37).on auxclick(e)hears a click with a button other than the main one (e.button == 1is the middle button, to close a tab);on focusinandon focusouthear 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-downandpanel-up. They go wherever an icon name does and are drawn incurrentColor. -
Menu.Item.danger(chapter 9), ordanger: true, draws an item that cannot be undone, such as Delete or Discard, in the danger colour. -
A
Tooltip'sshortcut:reaches its control (chapter 9):Tooltip("Save", shortcut: "mod+s") { Button("Save") }also gives the buttonaria-keyshortcutsin ARIA's spelling (Control+S, orMeta+Son Apple's systems), unless it has one. -
A member's
///is its documentation (chapter 5). A///comment above astate,persist,derivedoractionin a page, a component or a store stays with it, in.wfand.wfxalike; 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, aref:handle or null; named another node the block moves there with its state, and null keeps it aside. Its handlers,emitand lifetimes belong to where it is written.Portalis 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 aBuildCache, 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 newBuildReport::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 aBuildCache::on_diskreopened in a new session defers nothing. -
A member's documentation in the tree.
StateDecl,DerivedDeclandActionDeclcarrydoc: Option<String>, the///lines joined with\n;Statement::doc()andStatement::set_doc()read and set it, for a completion or a hover to show.print::statementwrites a documented member under its///, so a store whose members are documented prints back as itself.reprintandedit::rewrite_declarationreplace, 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 (whatwf explainprints after the summary, before setting it for a terminal), orNone. The code is matched as given:T06, nott06. -
A test's steps outside Chrome.
testing::step_script(what, name, value)returns the JavaScript expression aclick,typeorpressstep evaluates in the page, which answers"ok","none"or"no-option", so an editor's own window can find controls aswf testdoes. -
A rendered test in its locale.
testing::render_testtakes the locale as a fourth argument (Tests::locale()is the project's default, oren), andtemplate::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 theBuildConfig::frames_itselfflag, which the build fills in, so a server an editor runs for its preview can send whatwf servesends. -
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::createwrites them, and.gitignore,AGENTS.mdandpublic/beside them. -
The registry (chapter 38):
wf registry --jsonlists the new icons,auxclick,focusinandfocusoutamong every element's events, anddangeronMenu.Item. -
Paged layout.
paged::style::Length::Mix(points, percent)holds acalc()of both (calc(50% - 12px)isMix(-9.0, 50.0));Stylegainshas_mix()andsettle_mix(w, h, main);codegen::builtin::span_classwrites aColumn's span class. -
check_project_viaruns its phases on scoped threads, and calls aProject'sfile_ofandsource_ofup front, on the calling thread. The findings and their order are unchanged.
Fixes
29
-
A handler reads
keyandvalue(chapter 9).on keydown { if key == "Enter" { … } }passed the check and threwReferenceError: key is not definedon the first key press, which broke Enter in the SPA starter. A handler that readskeynow getsevent?.key, and one that readsvaluegetsevent?.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,Popoveror state-openedMenuwhosevisible:wastruefrom 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 openModalorDialogno longer reaches the page behind it. -
Menus and tooltips (chapter 9).
Menu(label:)is the list's accessible name; the button's words come fromtrigger:(aDropdown's still fromlabel:), so a menu thatvisible: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 aforor a component drew shared one, soaria-controlsandaria-describedbycould name another copy's. A menu keeps itsclass:and itsstyle { }class as it opens and closes. -
Forms ask their rules (chapter 16). A
Formwith nobind:in a page or component withvalidaterules ranon submitanyway; 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 validatedCheckboxorSwitchshows 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)withoutbind:drew no input; it now follows the value, and itson changehears the click. ASwitch'son changewas never attached. A boundCheckboxorRadiowith its ownon changelost 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,DatePickerandFileUpload; aTable'scaption:;Tabs.Pagetitles;Tooltiptext; aModal's orDialog'stitle:; aMenu'strigger:and aDropdown'slabel:; anAvatar'ssrc:,alt:andinitials:; aSkeleton'swidth:,height:andsize:; and anIcon's positional name (Icon(if done { "check" } else { "clock" })). SoCheckbox(label: t("…"))now changes language withsetLocale. 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
derivedthat 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 ituses, 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,RadioorSwitchis its<label>and<input>, ticked and disabled as its state starts, where only the labels' words showed. AMenuorDropdownis 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), andColumn(span: 8)itswf-col--8, where every column was painted the same width.disabled,requiredandcontrolsare written only whentrue, here and in the template engine, soButton("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
MenuorDropdownas its button and hidden list,keyLabel("mod+shift+p")as the build writes it (Ctrl+Shift+P), and at()with a count in the default locale's CLDR form.expectdecodes every numeric entity and the common named ones, soexpect "It isn't"matches. In a test that acts,expecttreats 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: 8andspan: 4in aRowwith 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 aColumnout at itsspan:, where every column came out equal, and the PDF engine'scalc()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
Navbarfollows 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. -
setLocaleis remembered (chapter 21) across page loads, inlocalStorageunderwf: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
Framewhosesrc:is site-relative ("/preview/","/embed/{id}") was refused by the site's own headers. A project that places one is servedX-Frame-Options: SAMEORIGINbywf serve, and its_headerssays the same withframe-ancestors 'self'; every other project keepsDENYand'none'. -
An
Avatar'ssrc:is checked like any othersrc:(chapter 23): a run-time value goes throughWF.safeUrl. -
Long keyed lists no longer stall as they grow (chapter 20). A keyed
forread 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
Splittermoves 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 writesreset:as given, soreset: 0can 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. -
webfluenton Windows (chapter 2). A barewfrunsWF.msc, the Windows Firewall console, which comes first onPATH. The.msi, the release zip andinstall.ps1now also install the binary aswebfluent.exe, sowebfluent buildworks;wf.exedoes too. The.msinow keeps oneUpgradeCode, where each release had its own, so the next one replaces it instead of installing beside it. The Node binding looks forwebfluent.exeandwf.exeby their full names (chapter 35). -
The check does less (chapter 38). The
envlint lexes only a file whose text could nameenv.…, and the output checks work out what a build can evaluate only once they find aChartor aQrCode: 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
Markdowngoes 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
ModalorDialogis the newest layer, so its Escape comes before a popover's beneath it, and a press inside it no longer closes that popover.on closeon a modal is its event, with noV09. -
Every built-in takes what any element takes (chapter 37).
role:,tabindex:,aria-*,data-*andonhandlers reached aPopover,Menu,Tooltip,Modal,VirtualList,Splitter,Tabs,Sidebar,Sliderand 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, asC04says.disabled: truedisables aSlider,DatePickerorFileUpload. Anhtml: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; anIconButton's owntitle:wins over its label on every page. -
A test reads a page as a reader does (chapter 24).
expectreads 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 servespublic/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: trueisdata-x="true"on every page, given to an element or passed through a component's call, and a call'sdata-*,aria-*,id:andclass: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.
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, aMenuat its button, at an anchor or at a point (at:, for a context menu), with submenus, andTooltip, 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).
modis ⌘ on Apple's systems and Ctrl elsewhere; chords ("mod+k mod+s");keyIs(e, …)andkeyLabel(…)for a table of commands that drives menus and a palette; a page, a component orapphearskeydownand the window's events itself;trapFocuskeeps focus inside a panel. -
Gestures (chapter 9).
drag:andon receive(d)with a ghost, edge scroll and Escape;on longpress,on swipe; andSplitterbetween 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, andV12for a long list that is not windowed. -
worker(chapter 18): a Web Worker held like a connection, asked with.request(method, params)and heard withon message, restarted when it crashes; a store may hold connections. -
Frame(chapter 28): another page inside this one, itson messageonly that page's;A17for a frame with no title. -
persistfollows its key (chapter 12):key: Project.idkeeps one value per project;in: .appnames a storage the project gives itself, which may answer later. -
The policy names an app's own schemes and WebAssembly (chapter 33):
meta.connectandmeta.frametakeipc:orwfpreview:,meta.wasmlets a page compile WebAssembly,meta.style_elementslets 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 literalsrc:inpublic/is processed as animagedeclaration 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 asprefers-reduced-motiondoes, anddata-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.PluralRulesreads), and exactly none iskey.zeroin 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,reprintandedit::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 --studiostampsdata-wf-nodeand writesnodes.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(thevalidaterules, 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::agentholds 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 contextis what an agent is given — the files, the problems, the components, the theme, the config with only its publicenv, 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 itsafter:andbefore:were not checked as the reader typed. -
Pre-rendered controls dropped
name:andautocomplete:, and anInputwith its ownid: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-EGwas not right to left. -
A
letin an action, a handler, an effect or a timer was offered by completion everywhere in its page, and listed as a store's member. -
I01andI02missed at()in a page's header;I03said a reader sees the key, where they see the default locale's message. -
Unsafe.Htmlwithout asanitize(…)elsewhere put nothing in; a typo was reported once per check that found it; a page's ownstate envread the project'senv. -
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.
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 forviewport,query,hash,theme,networkandupdate. The warning names it where it is written, and when nothing assigns, binds or changes the state, the quick fix declares itderived, 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", alet, avar,window.ready = …— compiled to a signal read,_VERSION(), wherever a page or a component read it: in text, a splice, aderived, aniforshowcondition, an attribute, a handler. Nothing declares_VERSION, so the page threw as it drew (_VERSION is not defined), andwf checkpassed. 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.
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 toloading, so amatchover 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 staysreadyand keeps its data while it runs, and the answer is drawn in place.loadingis 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
readyand setsname.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 iserror, as it was. -
A
matcharm's binding is live.ready(d)anderror(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 keyedfor … byand 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), andelseis one arm, whichever keys it stands for. -
An
if letbinding is live.if let u = selected { Sheet(u) }showed the value it was drawn with untilselectedwent 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.refreshingandname.pending.refreshingis true while a refresh runs with the data still shown;pendingis true while any request of the resource runs, the first load included. Both areBools, live wherever they are read. Withpaginate:, the next page is a refresh:loadMore()keeps the gathered items on the page, and anotherloadMore()while a page is on its way is ignored.
Fixes
2
-
ready(users)overresource usersreads the data. An arm's binding named like its resource — the guide's own example — compiled to the resource's handle, sousers.lengthwas undefined andfor user in usersdrew nothing. -
on:andcache: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 itscache: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.
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,matchorforat 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 onceactwent back to null and thenpickeddid, and a tab whosematchover a resource drew again on a refetch left its list beside the next tab's. The same held forif … else if … else(the arm drawn last stayed beside the first), for a keyed list item with anifof its own (moved, and taken away, without what theifdrew 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.
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, andText("{rows.state}")stayed "loading".name.state,.data,.errorand a connection's.messagesare now live in text, a splice and an attribute alike. -
A list's key may read the index.
for e, n in list by nthrew before the list drew (_n is not defined), andwf checkpassed: the key was compiled with the item alone. It is given the item and the index, soby nworks and so doesby "{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.
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'sstate envcompiled every read to the build's settings and every write to the state:"{env}"showed[object Object],env == "prod"was never true, andwf checksaid nothing. A loop'sthid the translation function inside the loop the same way. Such a name is now refused as astate,derived,persistorlet, a prop, a route or action parameter, a loop item, a lambda's parameter, a binding ofif let,matchor a slot, and as a top-levelconst,data,image, store orapi. The names areenv,params,localeanddir; 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'sWF. The message suggests a name of your own where there is a usual one —targetforenv,searchforquery,schemefortheme.event,e,value,keyand 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 envis 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.
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, soText("{e.env}")showed[object Object]and drewT20. It is nowenum 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 aStringwherever it is named. -
A value that may be null is
T?, however the document says so. OpenAPI 3.1's"type": ["string", "null"]wasAny?; it isString?, and the same holds for numbers, booleans and lists. AoneOf(oranyOf) of{ "type": "null" }and a$refis that type's?, 3.0's"nullable": truecounts beside atype, anallOfor a$ref, and a record or an enum whose own schema allows null isT?wherever it is named. -
allOfis a record that extends another.[{ "$ref": "…/EnvSummary" }, { "properties": … }]istype 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
formatis the language's type for what the server sends.date-timeis aDateTime,dateaDate,uuidaUuid,emailanEmail,uriaUrl— 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 itsreadOnlyfields) keepsString, so a route parameter or an input's text can still be sent.timestays aString: JSON Schema's carries an offsetTimedoes not read. -
Shared parameters and request bodies are read. A parameter or a body that is a
$refintocomponentswas dropped, so a call passing it wasT10; it is what its$refnames, 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 wasT05.
Fixes
3
-
if letand a case's payload are names in their whole block.if let why = e.reason { Row { Pill(why) } }drewV01("nothing in scope declareswhy"), and so did.failed(why) { … }in amatch; both are now in scope however deep the element that reads them. -
A button named by the
Textin its block draws noA05.Button { Icon("link") Text("Continue") }— and aTextin a branch, or in a component the block places — names the button. ATooltip's words, a custom element's tag and a loneBadgestill do not. -
wf verifyandwf testleave no browser profile behind. Each run that started Chrome left its ~150 MB profile in the temporary directory; where/tmpis 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.
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 isdefault-src 'self', so a frame from anywhere else — a YouTube or Vimeo player, a map — was blocked by the page that held it.meta.framenames the origins a page may embed, asmeta.imgdoes for images, and they joinframe-srcin the meta tag and in_headers:"frame": ["https://www.youtube-nocookie.com"]. An entry with a path or a keyword isE111.
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.
A script nothing waits for no longer counts against how soon a page is ready.
Additions
1
-
"load": "after"on ameta.scriptsentry. An analytics tag listed in the HTML is fetched while the page is, even withasync, 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 itsmeta.integrityhash when it has one. Its origin stays in the policy. A module, or a script whoseglobals.wfcalls, cannot load after the page (E111).
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.
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 renderwith no data renders with none. Without--datait 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 renderand theTemplateAPI 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
.htmladdress. Withbuild.clean_urls: "file", openingcontact.html(orcontact/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,showormatchdraws inside the link, and anaria-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 withjust bench-pdf. -
A test that fails if the previous major version is named as current.
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'simg-src. The policy allowed images only from the site itself anddata: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, orhttps://*.example.comfor its subdomains. One with a path, a keyword or a scheme a picture is not fetched over (wss:) isE111. -
The security chapter's tag-manager example adds Google Analytics' image origins beside its
connectones.
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 ofdefer. Deferred scripts run in order, and everymeta.scriptsentry is linked ahead of the compiled code — so a large library nothing on the page uses, such as Google's 175 KBgtag.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. Anasyncscript runs whenever it arrives, as the vendors' own snippets load it. -
A module, or a script whose
globals.wfcode calls, cannot beasync— the one is imported by the page's loader, the other might arrive after the code that calls it — and isE111. -
The security chapter's tag-manager example loads
gtag.jsthis way. -
For the Rust API:
ScriptSpecgains a publicis_asyncfield, so code that builds one with a struct literal addsis_async: false.
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 aPersoninstead of anOrganization: theWebSite'spublisher, and on a personal site everyWebPage'sabout.job_titleis the person'sjobTitle;same_aslists their profiles elsewhere. -
meta.owner_detailsadds 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:widthandog:image:heightare read from the image when it is inpublic/. -
og:image:altandtwitter:image:altfrom a page'simage_alt:ormeta.image_alt. -
og:localeis written as Open Graph reads it (en→en_US,en-GB→en_GB), with anog:locale:alternatefor each other locale.
Addresses that do not redirect
1
-
build.clean_urls. A static build writes/contactascontact/index.html, and a host such as GitHub Pages answers/contactwith a301."file"also writescontact.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.preloadlists files on the site to fetch with the page: each is a<link rel="preload">in every head, ahead of the stylesheets,asfrom its extension, andcrossoriginfor a font. A font a project.cssfile's@font-facenames no longer waits forstyles.cssto arrive. A path on another origin isE111.
Where a page may send requests
1
-
meta.connectnames the origins a page may send requests to besides its own — an API on another domain, an analytics endpoint — as the policy'sconnect-src:https://api.example.com, orhttps://*.google-analytics.comfor 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, isE111.
The documentation site
1
-
Moves to webfluent.monzeromer.dev. It was still built for the
/WebFluentbase path, so its internal links and search index 404'd.
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
.cssfiles and everystyle { }block, through a cascade with combinators, attribute selectors,:first-child/:nth-child, specificity, inheritance,var(),em,rem,%and::before/::after.@media printapplies. -
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,PageBreakandbreak-before/break-after.
New elements
4
-
Header(on:),Footer(on:)withpageandpagesin 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, …)andQrCode(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
Presentationholdsfor,ifand slide components: a deck writes its openers and footers once and makes a slide per item of its data. -
A page's
stateandderivedvalues have their values on paper — and in any template render — so a slide shows a figure worked out from adatafile. 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_reportandrender_slides_reportreturn aPdfReport: 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
pdforslidesproject, completion offers only what paper draws — noButton, noon click, noresource— aPresentationis offered its slides and the project's slide components, and hover says when an element is not drawn in this output and why.pageandpagesare names inside aHeader,FooterorBackground. 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
Linkwhosetohas 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
Boolprop 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
derivedthat reads a store, aclass: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:expectreads 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.wfruns that file in its project. -
A
validaterule's message may bet("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 fmtleaves 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 falseU02); a store action called in the store's own initial value is named for what it is. -
Host(title:)is thetitleattribute.
Diagnostics
2
-
V11: a component of the project's own named like a built-in (component Chart), which shadows it. -
E109now 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.
The language server says which version it is.
New
1
-
wf-lsp --version(and-V) prints the version;--helpsays what the binary is and how an editor runs it. An editor runs thewf-lspon yourPATHbefore a downloaded release, andcargo installleaves an old one there whenwfis updated — so an editor could report findings the compiler dropped long ago (an unknownHost) whilewf checkfound nothing. Comparingwf-lsp --versionwithwf --versionnow shows it.
Documentation
1
-
Troubleshooting names that symptom and its fix, and the CLI guide says to keep
wf-lspat the version ofwf.
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 inpublic/. -
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, adatafile, 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.offersplus,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,validaterules,persistsettings,formatstyles, responsive steps,Hosttags, key names inon key("…"), translation keys int("…"), publicenv.names, and codes in// wf-allow(. -
Hover says what every name is:
Hostand the props every element takes, a function the language gives, every keyword, a record's field, an endpoint, a case, animage's size. -
New: formatting (
wf fmton the open file), find references, document highlights, signature help inside a call, folding, inlay hints for the type of astateorderivedvalue written without one, and semantic highlighting — a name coloured by what it resolves to.
The compiler
2
-
V10: aHost(tag: …)it does not make used to be adivwithout a word; it is now a warning naming the tags it makes. -
An
imageis typed:hero.widhtis aT05, with the fields an image has.
A new project comes with the language reference its coding agent needs.
New
1
-
wf initwritesAGENTS.md: the WebFluent language reference, in the file an AI coding agent reads before it changes a project, headed by the version of thewfthat 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.mdnameswf init's copy andtests/in the project layout, pins the Rust engine at version 5, says what moving from 4 to 5 asks (wf check, quick fixes,lintsand// wf-allowwhile 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 inittemplate builds clean looked for 4.x's warning format, so it could no longer fail on a warning; it runswf check --deny-warningsand requires the newAGENTS.md.
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 checkruns every check and writes nothing.--format json,sariforgithubonwf buildandwf checkwrites the findings for a tool, code scanning or a pull request;--deny-warningsfails on a warning.wf explain CODEprints a code's entry. -
Quick fixes in the editor, and
fixesin the JSON: the nearest name for a misspelt field, member, method, variable, component or flag;?.for a value that may be null; missing props; missingmatcharms; a bare word written as its flag;alt: ""; an_before a name nothing reads. -
lintsin 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 isU07.
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
matchexpression that covers every case needs noelse. -
persist … { key: id }keeps one stored value per instance.
The dev server, `wf verify` and `wf test`
3
-
wf serveanswers a fetch or file the build did not write with a404and 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 verifyvisits:paramroutes, fails a page whose router drew nothing, and with--returning-visitorloads every route again as a reader whose storage holds the previous build's persisted values. -
press "Escape"inwf testcloses an open dialog.
Behaviour that changed
3
-
A fetch the dev server has no file for is a
404(also underwf verifyandwf test). -
An
apicall with an empty path parameter is not sent (it would have asked for the collection); it ends.aborted, and a resource staysloading. -
One list item that throws no longer blanks its list; an effect that never settles is stopped after 100 runs.
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).numberstored the text the field held, soqty + 1was"31"; it now holds a number, andnullwhen it is emptied. ASelectbinds the option'svalue:as it was written:Select.Option("Two", value: 2)binds2, not"2". -
A button in a form submits it only when it says so. Every
ButtonandIconButtonwithouttype: .submit(or.submit) istype="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 readstodosfollows. In a loop with noby, 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,SliderandDatePickerbound 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 * factorthenscale(3)compiled to a call of nothing; assigning a function to a state stored what the function returned.WF.signal(…).set(fn)now storesfn;.update(fn)is the updater it always was. -
A store action's
letandif let. Aletreassigned later in the action compiled to aconst; anif letinside 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.
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 modinlib.rsand in its own file; the two are one now, and stable and nightly rustdoc both document the crate with none.
Tooling
1
-
scripts/ship.shwaits for a just-pushed commit's CI run to appear, where it took the missing run for a failure and stopped.
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.
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)withurl = "javascript:…"as a live link, and the static paint did the same for anImage,Video,Audio, aSidebar.Itemand anElementattribute. Every URL attribute now goes through the scheme check the browser build applies.
New, in Rust
7
-
Template::from_files,from_dirandfrom_sources: one template from several files — components, themes, types and constants shared — each finding naming its file.pages()lists the pages andpage(name)picks the one to render. -
Data is any
serde::Serializevalue — your own structs — as well as aserde_json::Value. -
render_htmlwrites a<title>from the page's, filled from the data, andwith_langsets<html lang>(anddir="rtl"for an RTL language). -
with_pdf(PdfConfig)andwith_slides(SlidesConfig)set page size, margins and fonts;PdfConfig,PdfMarginsandSlidesConfigare exported at the crate root. -
A
Templateparses and checks once and shares the result:Cloneis cheap and it isSend + Sync, for a server's state. -
The
clifeature (default) holds thewfcommand's own dependencies;default-features = falsebuilds the engine without them — 43 crates instead of 62. -
cargo run --example invoicerenders a directory of templates to HTML, a fragment and a PDF.
New, in Node
4
-
renderHtmlAsync,renderHtmlFragmentAsync,renderPdfAsyncandrenderSlidesAsyncrender without blocking the event loop. -
Template.fromDir(dir),page(name)andwithLang(lang), as in Rust. -
The data goes to
wfover stdin and a PDF comes back on stdout: nothing is written to disk per render. -
wf rendertakes a directory,--pageand--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. -
constanddatafiles are in scope in a template.Text("{LIMIT}")rendered empty.
The editor grammars catch up with 4.2. Nothing in the compiler changed.
Fixed
2
-
Elementis highlighted as a built-in in Zed and VS Code; 4.2.0 left it out of both grammars. -
A state named
showparses in the editor. The grammar readshowat the start of a line as theshow { }statement, soshow = !showin a handler was an error in Zed, though the compiler accepts it. It is a name wherever that statement cannot start, asonandeventare.
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.
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
-
externalis removed. A remote module is ameta.scriptsentry, a local one a script undersrc/, and a custom elementElement("tag", …).wf migratedoes all three; a call into a remote moduleexternaltyped isAnyafterwards. -
Every
.jsundersrc/ships, on every page.wf migratelists the ones a project already has.
New
7
-
Your own scripts. Top-level
function,class,const,let,varandwindow.x = …are names.wfcalls directly. A call is held to the parameters (T10) and to the JSDoc types (T01);@returnstypes the result; a class is constructed. Collisions with another script, a declaration or a name the language owns are errors. An ES module undersrc/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;globalsputs a library's names in scope asAny. -
mount:,update:,cleanup:on every element and component call, andwf:renderondocumentonce 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 anifwith noelseisnullwhen it fails.V04flags a borrowedwf-class. -
Editor: completion, hover and go-to-definition for script names and for the classes
.cssfiles define, insideclass:; the server watches.jsand.cssfiles. -
wf auditlists the scripts and their names;wf typestheir signatures; actingwf testpages link them.
Fixed
2
-
What an
ifbranch,matcharm, list item or slot fill made is disposed of with its page. A route change used to leave its effects, timers andHostcleanups running. -
An
IconButtonwhoseclass: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;--fixformats first,--testruns the tests.just lintandjust fmt-checknow match CI too. -
Editors: the VS Code extension (0.4.0) and the Zed extension (3.2.0) drop
externaland re-read the project when a.jsor.cssfile changes.
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
derivedmay call anactiondeclared 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
sortcomparator is handed two elements. It was typed likemap's(element, index), so the second parameter read as aNumberand a comparator over records failed withT01. -
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/:hashcompiledhashtolocation.hash. -
A11resolves anifon aBoolprop from the call. A card that titles itselfh2under a page title andh3inside a section was judged on both branches, so the heading-outline lint reported theh3one against a page whose call saysh2. -
A select's value takes once its options arrive. The runtime applied it after the children passed to
el(), but codegen appendsSelect.Optionchildren 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 atopacity: 0for good.
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.
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), thenlist.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=aropens a page in that locale — the address the build'shreflangalternates always pointed at. -
Every standard DOM event in
on …:dblclick,pointerdown,scroll,paste,dropand 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
externalcalls it, so Chart.js and most modern libraries work throughexternal+Host. -
wf initwrites a.gitignore;wf generate pagegives 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 aderivedbefore it existed. -
Text("{rows.state}")showed a signal's source; a resource'sstate,data,errorand a socket'smessagesare now read as their values. -
navigatorandlocationcompiled as signals. -
app { state … }never declared its state. -
now(every: 1.seconds)called anownothing declared. -
An action handed over as a value,
addEventListener("scroll", track), was read as a signal. -
A type an
externaldeclares could not annotate a value. -
Backend.avatar.progresswas 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. -
S04never reported two pages on one route;A12counted anh1in each branch of anifas 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 — findswf-lsp.exeon Windows, and downloads the server from the latest release when it is not onPATH.
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.
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 initwrites"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;
.stacksis how aRow,GridorColumnasks to, andwf migrateadds 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
derivedthat read a store declared later in the file readundefined. -
A page
statenamedkey,value,event,eorparamscompiled 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 hiddenshow, which a strictstyle-srcforbids. -
The documentation site was painting
andin inline code. -
frame-ancestorswas shipped in a<meta>tag, where a browser ignores it. -
An
apiblock'son request/on response/on errorhooks compiled to empty functions: everything written in one was generated into a string and thrown away. -
A handler's parameter in an
apihook and in asocket,streamorchannel(on message(m)) compiled to_m()— a signal that was never made, so the handler threw on the first message. -
matchover asocket,streamorchannelcalled 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 aneffectread the bound name as a signal, so the branch that had just checked it was not null used a name that did not exist. -
T06only held a store to its members where the body wroteuse, and never inside another store or anapiblock — soStore.mispelt()in any of those built without a word. -
U04did not see the reads in anapiblock'sheaders { }or hooks, and reported the store members only those reach as unread. -
form.pending,form.errors,form.touchedandform.apply(…)wereT05: 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).
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.
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, forsetTimeout(() => go(), 300). -
A record construction carries the fields it left out — each field's default,
nullfor an optional — soTodo(id: "a", title: "b")holdsdone: falsewherever 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 aresourcemakes. The browser's own iswindow.fetch. -
items.push(x)on astate, apersistor 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:andredirect:work: a route whose guard is false sends the reader to its redirect (default/) instead of painting. -
A page's own
metainhead { }replaces the standard tag of the samepropertyorname, so a post page has oneog:title, its own. -
The registry lists the icons the runtime draws (
registry::ICONS, pinned to the runtime's table); anIcon("…")oricon: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 letname: the branch used to read it as unknown and paint an empty heading. -
A store action's
try/catch,forandelse ifused 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,RadioorSwitchdrops nothing now:aria-*,data-*,name,idanddisabledreach the<input>, and radios bound to one state share anameso the arrow keys move between them. -
navigate("/?filter=done")and aLink(to:)with a query string route by the path and keep the query readable throughquery; 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) loadsapp.jsrather than the shell again. -
WF._basePathis a getter again; a static build's links no longer start withundefined. -
A bare
slotfollowed byon key(…)on the next line names no sloton. -
The vocabulary lint knows a page's route parameters, and its
constanddatanames. -
A page framed by a
layout:is judged with the layout's outline: theh1a layout draws is the page's (A12), and a heading level skipped across the boundary is seen (A11). -
Grid(columns:)is adata-colsattribute the stylesheet reads — a build withbuild.cspon used to have its grids blocked as inline styles — and acolumns:that reads state follows it. -
wf serveserves a site built withbuild.base_pathunder 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.Itemwithouttopaints 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
:parampage's static files carry their own route as the canonical link and sharing URL, not the pattern with:slugin it. -
An
IconButtonwith aclass:keeps the engine's classes; itsicon:,label:and title follow state. -
A
Sidebar.ItemorBreadcrumb.Itemwith ato:reached through aforor anifis a link in the browser too; it used to be a bare<li to="…">that went nowhere.
Added
11
The language core
-
forin actions, handlers and effects — with an index, over a range (1..10,1..=10), or a keyed list;try { } catch e { }; destructuringlet { a, b } = mandlet [x, y] = l. -
Optional chaining
a?.b,a?.m(),a?.[i]: null when the base is, the rest of the chain with it, typed asT?. -
if let x = v { a } else { b }as a value. -
Regular expressions
/pattern/flags, withtest,exec, and a string'smatch,replace,replaceAll,split,search; a/after an operand still divides. -
Spread
[...a, b],{ ...m, k: v }. -
const NAME = valueat the top level, andenv.Xfrom 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.namis aT05and a literal given where a record is wanted is checked field by field; a field only some items of a list have isT?. -
Helpers
sortBy,groupBy,unique,take,first,last,flatMap,sumon lists andcapitalize,truncateon 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"— andago(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 fmtformats 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 serverebuilds 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 })picksitems.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: nameon an element: a handle read as the element itself
(name.focus()).
every(ms) { },after(ms) { }andeffect { … cleanup { … } }; what a
page, a branch, a list item, a match arm or a slot creates is disposed of when it leaves.
persist name = valuein a page, a component or a store: kept in the
browser's storage across visits.
viewport,query,hashandtheme: 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.
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 newtypeandenum. There are no keyword tokens:type:andon = !onare what they look like. -
Flags:
.primary.lgafter the parentheses — aBoolprop 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,onhandlers, slot fills, children.on click { }andon click(e) { }; aButton's block holds what it shows,on clickwhat it does. -
Style values are CSS:
padding: 1rem 2rem,background: $surface,width: {pct}%,&:hover { },@media (…) { },--name: value. A$tokenis validated against the theme;$mdonpaddingis$spacing-md. -
Components declare typed props (
_ name: String,active: Bool = false),events fired withemit, andslots filled by name. -
Pages own their routes:
Routertakes no children; routes match by specificity.layout: Shell(args)wraps a page in a component with a default slot. -
resourceandmatchreplace thefetchblock;for … by keykeys a list;if let x = expr { }unwraps;??,T?,[T],null,awaitin actions and handlers,ifandmatchas values,.case,$tokenin expressions. -
Store.load(id)at the top of a page is set-up code;let xis 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 aftertone: .,$tokensin a style value, events afteron, a component's events afteremit, the arms amatchstill 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 followslayout:. -
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
.wfin the repository and in Halyard parses without an error node. -
Structured edits (
EditOp) write the grammar of the file they edit:AddModifierappends a flag,SetStylewrites a raw value. -
The documentation's
wfblocks 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. Runwf migrate. -
A
Button's block of statements is no longer its click handler; writeon click { }. The migrator does. -
A word nothing declares is an error, where it used to be the
V01warning;Alert(elevated)and itsV02are 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→fetchbeside the newresource,createStore→store,createRouter→router,definePage→page,showToast→toast,bindDialog→dialog,bindPopup→popup,tablist→tabs,offCanvas→drawer; newmatch,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/Parserof the old grammar are#[doc(hidden)]behindwf migrate.Expr::Recordis a new expression;sema::check,sema::types::checkandsema::lowerrun 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 keykeeps the nodes of the items that stay. -
The route table depended on source order; it is now ordered by specificity, then path, whether the
Routerhad children or not. -
easing:on an element was accepted and ignored; it sets the timing function, andspring,smooth,bouncy,easeOutand the rest mean the same there as in atransitionblock. -
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
- Install 3.0 and run
wf migratein 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.
- 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.
- Annotate what you want checked. Nothing is required; `state items:
[Todo] = [] and resource r: [Deploy] = fetch(…)` are where the type
checker starts to see.
- If anything of yours named
WF.*runtime functions — a custom
stylesheet does not, a script in index.html might — rename per the
table above.
- Zed users: the extension's 2.0 pins the new grammar; the old one
highlights nothing useful on migrated files.
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.
-
Carouselis 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. -
Tooltipopens on focus as well as hover, closes on Escape, and describes its trigger witharia-describedby. -
Dropdownmenus follow the ARIA menu pattern:role="menu"withmenuitems, arrow keys, Home/End, Escape, and focus returned to the trigger.
Lint rules
A14— arole: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— anaria-labelthat 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.minifyis 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 aspages/<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>.gzbeside 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. -
A14reported a component whose root took its role from a prop as a plain control. -
wf serveread 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.
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 whenshowErrorschanges. 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/Gridgap: xs|sm|md|lg|xl,align:andjustify:(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; aTcell
inside Thead is a <th>.
Link(to: "/docs", active: "prefix"): links get.activeand
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"; onlyicon:drew the glyph. -
IconButtondropped every named argument buticonandlabel, 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)besidestep). -
placeholder,disabled,srcand 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 aSelectcomponent was appended after the value (codegen). -
An
else ifchain with a finalelseskipped every branch. -
A
SliderorInputwith bothbind:andon:inputkept 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.
-
createStorebound derived values before actions, so a derived value that called an action threw. -
The router never set
document.title. -
wf builddid 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 is404.htmlat the root, and it addresses its assets from the site root, so a dynamic route under a static build hydrates. -
wf servedid 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-primaryeven when noprimaryvariant was used. -
In structural mode the sheet stacked every
Rowunder 768px; it no longer paints layout decisions the author did not make.
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. Usethemes::resolve_tokens(program, config). -
render_page_html/render_page_html_studiotake aSiteContextinstead of five separate parameters. -
generate_html(config, program)takes the program, for the page metadata. -
Template::with_theme(name)selects aThemedeclared in the template rather than naming a built-in palette.
Fixed
11
-
forloops 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 threwReferenceErroron first render.wf init -t spashipped 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>underwf build. The static renderers switched the tag; the SPA codegen never did, and emitted awf-heading--h1class 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: nonebelow 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-selectremoved the outline without replacing it visibly. -
theme.builtin: "structural"never reachedwf build— only the studio honoured it. -
The language server had not compiled for several releases. Nothing in the repository built it;
cargo buildat 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
altand 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
- If your config names
dark,minimalorbrutalist: 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.
- Remove
theme.modeandtheme.extendsif present; they are ignored. - If you styled
.wf-modalor.wf-dialogdirectly, re-check it against a
native <dialog>.
- Add
meta.site_urlto get canonical URLs, sharing cards and a sitemap.
Nothing breaks without it; those tags are simply not emitted.
- Expect new warnings.
S02fires on every page with no description. None
of them fails a build.