Zubra docs

Changelog#

All notable changes. The format follows Keep a Changelog, and versions follow Semantic Versioning: from 1.0.0, the authoring formats, the CLI and the runtime's public API change incompatibly only in a new major version.

Unreleased#

6.0.4 — 2026-11-22#

Security#

Found by security audit 6, on 6.0.3.

  • redirect() keeps a same-site path that begins // on the site. @zubra/router read a location as a browser does and refused another origin, but wrote a location on this site as its path, and a path can begin //: redirect(next) with next set to https://this.site//evil.example/, .//evil.example or ..//evil.example answered Location: //evil.example/, which the browser reads as another site. It's written with one slash now, as a location that starts // already was.
  • A value can't set the page's <base>, and a spread can't go on <base> or <link>. <base href={…}> and <base {...attrs}> took a visitor's https://evil.example/, which passes the URL check, and the base then decided where every relative URL went: the page loaded the runtime and the components' modules from the visitor's site, and its forms posted there. A spread on <link> could be { rel: 'stylesheet', href }. Both are compile errors now; a <base> the template writes still compiles.
  • @zubra/sync's live stream is paced by the page reading it. A page that opened /live?since=0 and read nothing made the server load the whole log into that stream, and keep every change after it: ten such pages held 400 MB for a 200,000-change log, and any page that may read a collection could open them. The log is now read a page at a time as the page takes the last, a stream more than 64 events behind is closed (its page reconnects from its cursor, as with the zubra-sync binary), and Node's handle() writes only as fast as the connection takes it.
  • A visitor's style: value is left off, not a failed render. style:color={tone} with a prop that isn't a single CSS value (red;}) failed the whole server render, so one profile's colour took down every page that showed it. It's left off the element with a warning, as in the browser and as a spread's style already was; a literal one is still a compile error.
  • Signals mode takes globalThis.Signal only when it is the API. On a page, an element with id="Signal" (or <img name="Signal">) is globalThis.Signal, and in signals mode a visitor's id stopped every component on the page. A native Signal is used only when it has State, Computed and subtle.untrack.

6.0.3 — 2026-11-21#

Fixed#

  • A window listener, the light-DOM slot observer, and an in-flight fetch go when the element leaves the page. They lived in effect cleanups, and disconnect only pauses the effect graph so a moved element can resume it. The listener stayed on window or document, the observer stayed on the host, and a resource() request kept running and could write into a detached element. Each is now tied to the element being connected: disconnect removes it, and connecting again starts it once. A zb-await whose promise settles while the element is detached still shows its result when the element comes back. Pause still does not run every effect cleanup, so a move re-runs only the effects whose inputs changed.
  • .self is the click's original target. A listener on a shadow host sees event.target retargeted to the host, so a click inside the shadow looked like a click on the host. .self now uses the first entry of composedPath().
  • formDisabledCallback(false) before connect is kept, and setValidity does not throw when its anchor is not focusable. Safari and Firefox can call the callback before the element connects, including with false, and that false was dropped, so the control stayed disabled. The last value is replayed once the script has registered. Safari throws NotFoundError if the validity anchor is the host and the host is not a focusable descendant; the call is retried without an anchor.
  • A hot update that cannot swap the element reloads the page. Defining the same tag twice throws NotSupportedError in Firefox and WebKit. A build with no swap method now sets hotReloaded to false, which is what the plugin already reloads on, and the first class stays registered.
  • --emit element drops a window listener when its zb-if, zb-each, or slot fallback goes. The listener was pushed onto the element for as long as the element lived, so hiding the branch left it on window. A listener nested inside another condition or row stayed too, and connecting the element again put it back. The branch, row, or fallback removes it, including one nested inside, and connecting again adds it only while that branch is showing.

6.0.2 — 2026-11-21#

Fixed#

  • Framework server rendering drops hostile host attributes. renderToString (what an Astro page's attributes go through) wrote every extra host attribute into the HTML, name and all, so a visitor's "><script> or onmouseover ran when the page was parsed. A name that isn't an attribute name, a string event handler, innerHTML and its kin, an object, and an unsafe URL (javascript:, data:, vbscript:, including one hidden by a character reference) are left off, as a spread already left them off.
  • A dynamic style: value can't inject CSS. style:background-image={user} applied url(...) in the browser, and a custom property took </style>, even though a value the server can see is rejected. The runtime now leaves a value that isn't a single CSS value off the element.
  • A sync log can't apply __proto__, constructor or prototype. A push of those names was already refused. A log that already held them (written before the check, or past the handler) was still applied when documents were rebuilt: __proto__ set that document's prototype, and constructor / prototype showed up as fields. They're skipped, on the server and when a client merges a change. prototype is refused on a push too. The Worker standup example serves fields.js beside connect.js, which imports it.
  • A single-quoted attribute can't grow a second attribute. The HTML output always uses double quotes. A literal " inside the value, including one around {name} written with single quotes, was copied through, so a visitor's prop closed the attribute and the rest (ontoggle, open) was parsed as its own. " and < in that literal are escaped. An & the author already wrote (&amp;) stays as written.
  • A spread can't set <meta http-equiv>'s content. http-equiv itself was already refused. content on a meta that has it (or a spread that tries to set both) was still written, which is a refresh to whatever URL the visitor supplied. It's left off, on the server and in the browser.
  • Hydration doesn't bind a component's listeners to a visitor's lookalike markup. An early <!--]--> or <?zb ]?> in a slot, or a child whose tags match the template but whose text doesn't, is not adopted: the component renders its own template. A child component is left to its own template. A matching element loses a URL, an event handler, srcdoc or ping the template doesn't have and no part binds (formaction or onmouseover on the template's button). An id the page wrote stays. Whitespace left where a marker was stripped still matches; a different word does not.
  • The local playground and gallery servers stay inside their directory. A request whose path decodes to .. (/..%2fsecret.txt, /zubra/..%2fsecret.txt) is a 404. index.html in the directory is still served.
  • An action result cookie with no page is ignored. The cookie is shown only on the path it names. One without page matched every path.

6.0.1 — 2026-11-21#

Fixed#

  • A starter script run before npm install says to install. npm create zubra installs nothing, and its last lines say to run npm install and then npm run dev. Running dev, build, preview or test first (and start in the server app, and check with --typescript) asked the shell for vite or astro, or started the server, which then could not import its packages. Git Bash reported vite: command not found, which reads as if the app never included Vite. Those scripts now run scripts/ensure-installed.js first (predev and the rest), and it stops with Dependencies are not installed. Run npm install, then npm run dev. Once node_modules is there, the check is quiet. New apps only: an app already created can copy scripts/ensure-installed.js and the pre* lines from the template.

6.0.0#

Zubra 6.0 makes its own reactive engine the default, with TC39 Signals as an experimental mode. It also makes production mode and closed Sync reads the defaults, and starts the 6.x long-term-support line. Migrating to 6.0 covers the changes for 5.x users. These notes include the release candidate and the changes made since it.

Added#

  • A compact SQLite Sync log is opt-in. sqliteLog(path, { keep: 'latest' }) and zubra-sync --keep-latest retain only each field's latest value in a shared table. On first use they copy the latest values from an existing full log after its old cursors; the old table remains, and later starts must use the same mode. The default still keeps the full history. See Sync for the trade-offs.

  • zubra.errorPage(error): a development error page for any @zubra/server app. The server starter wrote its own: the error's message in the open page, which went away once the fix was saved; an app without that code got whatever it wrote itself (often plain text, or the stack). errorPage(error) gives { status: 500, type, body } to send from the app's catch. In development: an HTML page with the message, escaped (a component's comes with its file, line, a caret and often a fix), and the stack's frames, carrying the reload script when that's on. In production: "Something went wrong" as plain text, never the message, which can hold a query, a path or a host. errorPage(error, { nonce }) for a Content-Security-Policy nonce. Node and the edge (a Worker is production unless production: false). The server starter and the help desk example use it.

  • The Zubra DevTools pane shows more of the reactive engine. A binding that re-ran says why: the signals it reads that the update wrote, followed through computeds (re-ran because doubled ← count changed). A Signals section lists the component's props, state and computeds with their values, how many times each has changed, what reads it (bindings by their DOM operation, computeds by name) and what a computed reads. Live counts the effects in the component, the components on the page, and the effects made since the pane connected that are still alive, with how that count moved over the last updates (counting starts when the pane connects, so a page that never opens it pays nothing; removed elements' effects leave the count when they're garbage-collected). Updates lists the page's last 50: what each wrote (from and to), what it re-ran, in which component, and how long it took. The header names the engine. Read-only, as before; development builds only (the production runtime is byte for byte the same); the pane's DevTools version stays 1, so an older extension and a newer runtime, or the reverse, still work together. Signals mode shows everything but the change counts. The Signals Inspector is unchanged.

  • A warning for className and htmlFor in a .zb template. They are React's names for class and for. HTML has neither, so <button className="more"> was sent as written, the browser read an attribute nothing uses, and the styling was gone with no message; zubra check said "no errors". The compiler now warns at the attribute, with write \class`as the help, inzubra check, the editors and the server's log. Not for a child component that declares a prop of that name, and not in a JSX component, where those names are the right ones. (onClickneeds none: attribute names aren't case-sensitive, so it isonclick`.)

  • createZubra({ reload: true }): saved components update the open page in place, and the server starter uses it. npm create zubra -- --framework server restarts its server on a saved file (node --watch), but the open page stayed as it was until someone reloaded it, where every bundler starter updates on save. With reload, page.finish() and page.scripts() add a small script (<prefix>/reload.js, a file, so no policy has to allow it inline) that keeps an event stream to the server open; when the stream is lost and then opens again, the server is back. The script then asks what each of the page's components is now (<prefix>/reload/versions/…), imports the ones that changed, and the runtime swaps each into its live elements, keeping their state, as the bundler starters' hot updates do; a change to anything else (the server's own code, a component's props or events, one that doesn't compile) reloads the page. In the starter a saved template edit shows in about 0.6 s with the counter's count kept. Nothing watches files: the restart is the signal, so a server that doesn't restart doesn't update. Off by default; Node only.

    • The starter turns it on in development, its error page in development is a page with the same script (so it goes away when the fix is saved), and the counter's comment and the welcome line ("updates in place, keeping its count") are now true of it too.
  • Compared on one app (docs/compared-on-one-app.md): one slice of an ordering app (live menu, bag, pickup time, checkout, live order page) built twelve ways, in Zubra twice, Lit, Enhance, Stencil, FAST, WebUI, SvelteKit, Next.js and Nuxt, on one backend and one set of browser tests, measured on 5.23.0. Where Zubra is ahead (a tap on a slow phone, pages served, lines of code) and where it is behind (download size, menu load, start-up, memory). Each build's code, the spec, the tests, the measuring script and the raw results are in docs/compared/slice/; the backend they share is not published, so they can be read but not rerun.

  • @zubra/unplugin: autoImport, tags without imports. A page can only use a component's tag once something has imported it, so an app with many pages kept a side-effect import in every file or one file listing them all (open.parlor has seven such files, 154 lines). zubra({ autoImport: ['./src/components', '@acme/ui/components'] }) names folders of components, the app's or a package's, and a .svelte, .vue, .jsx or .tsx file that opens one of their tags gets import '…/tool-bar.zb?element' written for it. A component is known by its host tag, not its file's name; only the tags a file uses are imported, so an unused component stays out of the build; the import goes on a line that is already there, so line numbers don't move. In Vite, Rollup, webpack, esbuild and Rspack. Off by default. Not for Astro pages or Angular.

  • createZubra({ compress: true }): the server's files in Brotli or gzip. zubra.handle() and zubra.fetch() sent every file as it is, so the sizes these notes give held only behind a CDN or proxy that compresses: on a plain Node host the browser was sent the runtime's base as 30.5 KB, not 12. With compress: true they answer in Brotli when the request's accept-encoding takes it, in gzip when it takes that, and as before otherwise, with vary: accept-encoding either way. Off by default, so no existing app's responses change; npm create zubra's server app turns it on.

    • Each file is compressed once and kept: what stays the same until a restart gets the smallest encoding (the base is 11.0 KB in Brotli, 12.0 KB in gzip; Brotli takes about 36 ms for it, once), and what an edit may change in development a quick one. Files under 1 KB go as they are.
    • Measured on the comparison's menu page, on a slowed phone over slow 4G: 570 ms to 481 ms to the load event, and 39.4 KB to 21.2 KB sent (20.0 KB in Brotli). On fast 4G, 240 ms to 225 ms.
    • Leave it off where something in front compresses already, and at the edge, where the platform does. It covers what Zubra serves under its prefix; zubra.send(req, res, html) also compresses the page. The app handles its own CSS.
  • buildApp() from @zubra/server/build: the whole app as one module (experimental). A page loaded the runtime, a module per component and each script of its own: four requests on the comparison's menu page, and on a slowed phone the requests, not the work in them, were most of the time between Zubra and the single-file libraries. buildApp({ components, scripts }) builds what buildRuntime() does and puts every component, the plain modules they import and the page scripts you name into the same module; passed as createZubra({ runtime }), it is a page's only script and only preload. On that menu page, CPU slowed six times, thirty interleaved loads: 301 ms to 242 ms to the load event, level with Lit (244), and 12.7 KB in four files to 12.1 KB in one. @zubra/sync is in the module too, where a component or a script of the app's uses it, and the package's own address (/_zubra/sync/index.js) then answers from the module, so a script outside it shares the one store; connect()'s peer-to-peer module stays a file loaded when asked for. On the comparison's build with Sync, thirty interleaved loads, sent in Brotli: 522 ms with the package beside the module (three files, 14.7 KB) to 452 ms with it inside (one file, 13.5 KB); the same page on 5.23.0 was five files and 567 ms in that run.

    • Every page loads the same module, so it is cached once; it defines every component of the app, whether the page uses it or not.
    • A script you name runs on the components' copy of the runtime: import { effect } from '@zubra/runtime' in it is theirs.
    • A component added since the build is refused when its page is made, with a message that says to build again. A component's own address (/_zubra/components/<name>.js) answers with an import of the module, so nothing defines an element twice.
    • As buildRuntime(): needs esbuild installed by the app, production only, not at the edge.

Changed#

  • Sync replay and live queues use bounded memory. The zubra-sync binary sends backlog pages as it reads them and closes a live connection that falls more than 16 events behind; clients reconnect from their cursors to recover changes. Presence and signaling are transient. memoryLog({ keep: 'latest' }) also indexes the latest values for faster pagination. Deployments should still set connection limits and load-test expected traffic; see the binary's README.

  • Starters check their framework's Node requirement before writing an app. Vite, Svelte, Astro and Angular need different Node versions; the chosen requirement is also written to the app's package.json. The creator identifies missing framework values, quotes paths with spaces, and tells users how to install Chromium for browser tests.

  • Every compiler error and warning has a stable code. docs/stability.md told tools to read --format json codes rather than the prose, but no diagnostic had one. Each now carries a code from one registry (src/codes.rs): ZB1xxx parsing, ZB2xxx the template, ZB3xxx the script, ZB4xxx props and their types, ZB5xxx server rendering, ZB6xxx output targets, ZB7xxx imports, ZB8xxx tools, ZB9xxx internal errors. The terminal shows it rustc-style (error[ZB2001]: unknown reference …), check --format json and the request protocol's diagnostics give it as code, and the language server sets it as each diagnostic's code, linked to its row in the new docs/diagnostics.md. The codes are Stable; the message text stays Supported. A tool that matched the first line's error: prefix sees error[ZB…]: now. Found by the pre-6.0 audit.

  • One CLI contract: both CLIs take the same commands, flags, help and exit codes. The native and npm CLIs had drifted: only the native check took --format json (the npm one ignored it), only the npm one had --framework svelte|solid in its help, convert --component was native only, and neither listed --emit element or --client-only. Both now parse with one table (src/cli.rs; the npm CLI asks the compiler for it), so check, compile, convert, fmt, request and serve take identical flags and values in both: the npm CLI gains check --format json, --stdin and --deny-warnings, every --emit and compile flag, convert --component, and request and serve. build, add, types, mcp and check --types need Node and stay in the npm package; the native CLI names them and says where they are, with exit code 2, instead of printing its usage. Found by the pre-6.0 audit.

  • --help, --version and the exit codes are fixed and documented. zubra --help exited 1, check --help and convert --help said "unexpected argument", compile --help tried to read a file named --help, npx zubra types --help wrote typings and npx zubra mcp --help started the server, and neither CLI had --version. Now -h/--help and -V/--version come before anything else, globally and after any command, and exit 0 (build --version is still the package's version); a command's help lists its flags; an unknown command, flag or value is named, with "did you mean" when one is close. Exit codes, in the reference: 0 success (warnings included), 1 errors in the input, 2 a usage error, which used to be 1. check --deny-warnings fails on a warning. Found by the pre-6.0 audit.

  • No framework is vanilla everywhere. npm create zubra said vanilla, the plugin's option framework: 'element', zubra types --framework none, and --framework plain was refused. vanilla is now the name in the CLIs' --framework, zubra types, npm create zubra, @zubra/unplugin's framework option and the TypeScript plugin's, and element, none and plain are accepted as other names for it, for good. Found by the pre-6.0 audit.

  • Smaller CLI edges. A missing file says no such file: <path> (the npm CLI said "files has no source for …", with no newline). A plain check of a lang="ts" component says its types weren't checked, and how to check them. check --types errors show the line with a caret, as the compiler's own do. The help no longer says convert my-element.js takes any custom element: it reads the class --emit element writes. Found by the pre-6.0 audit.

  • A server that doesn't set NODE_ENV runs in production mode. @zubra/server and @zubra/actions were in development mode unless NODE_ENV was production, so a deployment that forgot it sent visitors error messages, stacks, absolute source paths and the runtime's DevTools build. Development is now opt-in, NODE_ENV=development or production: false, as @zubra/server/edge already was, and the server says so once at start (@zubra/server: development mode (NODE_ENV=development)). The sync server's refused-read warning follows the same rule. The server starter's npm run dev passes --dev, which server.js turns into NODE_ENV=development (no shell syntax, so it runs on Windows' cmd), and npm start is plain node server.js. Decided for the 6.0 long-term-support line; Migrating to 6.0 says what to do.

  • A sync server without authorize lets pages read nothing. Writes were already closed by default; reads were open, so every page could pull every collection in the log. Now a collection is readable only when the app says so: authorize: allowReads(['menu', 'stock']) (new; allowReads() for every collection, 5.x's default), an authorize that decides kind: 'read', or allowAnyone. In development the server names a collection a page was sent nothing of, with the allowReads([...]) that would open it. A Durable Object without an authorize() is the same, and the zubra-sync binary takes --read <collection> (repeatable) and --read-all; --open opens reads and writes. Every example and demo already said who may read. Decided for the 6.0 long-term-support line.

  • zubra.send(req, res, html) sends a page compressed. compress: true covered the modules but not the page, most of a first visit's bytes: the server starter's page went out as 17.1 KB and goes as 4.1 KB in Brotli. It uses the response's status and HTML as its type unless told otherwise, and sends the page as it is without compress. The server starter and the help desk example use it. Found by the pre-6.0 audit.

  • A 'use collection' save re-serialises only the fields that changed. Each save wrote the whole document out as JSON twice and parsed the last one back, so one small edit beside a 10,000-item list cost the list every time. Each field's JSON is now kept (a computed of its state) until the field changes, and the save compares fields by it: a one-field edit beside a 10,000-item list goes from 10.5 ms to 4.5 ms in Node. Found by the pre-6.0 audit.

  • The first page after a production start no longer waits on Brotli. With compress, the runtime's files were compressed at quality 11 synchronously on the first request for each (about 120 ms for a page's fifteen modules, with other requests waiting); they are now compressed at start off the main thread, and a request that comes first waits for that work rather than repeat it. They are also read once, so a request no longer hashes the file to find what was kept. The starter's runtime files on a first load: 155 to 240 ms before, 28 to 62 ms after. Found by the pre-6.0 audit.

  • The server starter keeps what it compiled in development too (cache: true): an edited .zb is still picked up, since the folder is checked first, and a page no longer recompiles every component (530 to 560 ms a page on this machine, now 3 to 6 ms). Found by the pre-6.0 audit.

  • @zubra/actions's scripts are cached and can be compressed. In production /_zb/actions.js and /_zb/enhance-forms.js are cached for an hour, as the runtime is (they had no cache-control), and createActions({ compress: true }) sends them in Brotli or gzip, compressed once at start. Found by the pre-6.0 audit.

  • The development error page is readable on a phone and in dark mode, with a heading that names the file (for a component that doesn't compile) or the error. Production's answer is unchanged: "Something went wrong", as plain text. Found by the pre-6.0 audit.

  • Every starter's page has an inline icon, so the first load no longer logs a 404 for /favicon.ico. Found by the pre-6.0 audit.

  • The registry's star-rating is a radio group with one tab stop. It was five aria-pressed buttons, five tab stops, while the registry promises one tab stop and arrow keys for radio-like groups. Now it is role="radiogroup" named by label, with role="radio" stars and aria-checked, a roving tabindex (the chosen star, or the first while there's none), Right and Up for one more star, Left and Down for one fewer, Home and End for one and all; aria-required and aria-readonly follow required and readonly, and a disabled control (its own disabled, or a disabled <fieldset>) is aria-disabled and leaves the tab order. Props, the valuechange event and the form value are unchanged. Stars are at least 24×24 px, and an unlit star is 3.5:1 on white (it was 1.8:1). A copy you added with zubra add before keeps the old roles until you run zubra add star-rating --force. Found by the pre-6.0 audit.

  • Registry components meet WCAG 2.2 AA under axe. dropdown-menu's focused item had only a background 1.1:1 against the menu; it now has a 2px outline in --accent when focused from the keyboard. flip-card's hint was 3.3:1 (now --muted's default, #667085, 5:1), and the hint was part of the card's accessible name, so a speech user saying the face's text didn't match it: the name is the face's text and the hint is its description (aria-describedby). chat-message's white initials on hsl(h 55% 40%) were 3.4:1 for green names; the avatar is lch(46% 40 h), at least 4.8:1 on every hue. axe (WCAG 2.0 to 2.2 A and AA, and its experimental rules) finds nothing in any registry component. Found by the pre-6.0 audit.

  • The playground works from the keyboard. Tab in an editor inserts two spaces, so a keyboard user could tab in and not out (WCAG 2.1.2): Escape, or Ctrl+M as in CodeMirror, now switches Tab between indenting and moving focus, for both editors, and a hint beside the editor says which it does (and is the editors' description). The output tabs are a WAI-ARIA tab list: each tab controls its panel and each panel is labelled by its tab, the selected tab is the one tab stop, and Left, Right, Home and End choose; a code panel is focusable, so it scrolls from the keyboard. At 375 px the tab row wraps instead of widening the page to 527 px. Found by the pre-6.0 audit.

  • The DevTools pane no longer reads itself out on every update. It was an aria-live region whose whole content was replaced every 500 ms while the page updated, so a screen reader re-read the pane and a focused "open in editor" button lost focus. The pane is no longer live; a visually hidden status line says what changed ("Inspecting " on a new selection, "Update 4: 2 of this component's bindings re-ran" after one, at most every two seconds), and an update patches the pane in place, so the focused button and the sections you opened or closed stay as they were. Page values are still escaped by render() and parsed with DOMParser; the patch copies text and attributes from that, never HTML. Found by the pre-6.0 audit.

  • Keyed rows glide without laying the page out once per row. glide read each row's box and computed style straight after the previous row's style write and animate() call, so the browser laid the page out again for every row: removing half of 400 rows took 290 ms. It now reads every row first, then writes and animates them all (about 195 ms in the audit's measurement). The same in --emit element's own helper. Reduced motion and leaving rows behave as before. Found by the pre-6.0 audit.

  • The documentation site works on a phone and from the keyboard. At 375 px the header's links widened the page to 459 px, cutting off "Demos" and "GitHub": the header now wraps (and stops being sticky below 30rem, where it is two lines). Code blocks and tables that scroll sideways weren't reachable from the keyboard: each code block is focusable and named ("Code, HTML"), each table sits in a focusable, named box that scrolls (the table stays a table, where display: block had made it one), and a small script takes the tab stop off any that fits. Linked inline code was 4.4:1 in the light theme; it is 5.5:1. /docs/guide/ was a 404 and now sends you to the guide's first page. The 6.0 migration guide moved from about 35th in the sidebar to second, outside the guide's Previous and Next, and the landing page and the docs' first page link it ("Moving from 5.x? Migrating to 6.0"). axe finds nothing on the landing page, the docs or the playground, at 1280 and 375 px. Found by the pre-6.0 audit.

  • The finished to-do in every starter is 5.5:1, not 4.3:1. todo-list faded a finished item to 60% opacity; it is now --muted, which is at least 4.5:1 in both themes. The starter's test checks it. Found by the pre-6.0 audit.

  • The Solid market dashboard's tiles say which is selected with aria-current. aria-pressed isn't allowed on an <article> (axe: critical). Found by the pre-6.0 audit.

  • 6.x is a long-term-support line, and the docs say so. docs/stability.md has the promise: everything Stable (the .zb format, the compiled ABI abi: 5, the CLI's commands, flags and exit codes, the typings and manifest, the hydration markers, every Stable npm entry) is frozen until 7.0; 6.0.x is fixes only; a 6.x minor adds or changes something Supported, with a reason here; Experimental pieces may change in any release; a Stable item 7.0 removes warns in at least two 6.x minors first; and 6.x gets security and critical fixes for 18 months after 6.0.0. The pre-adoption stage ends with 6.0.0. The README's status and Stability section, SECURITY.md and AGENTS.md follow it. Found by the pre-6.0 audit.

  • Every published package has a README, a homepage, bugs and keywords on npm. @zubra/compiler, @zubra/server, @zubra/language-server and create-zubra had no README, so their pages said "No README data found"; each now says what it is, how to install it, and a minimal example that runs. runtime/test/tools/versions.test.js checks all nine. Found by the pre-6.0 audit.

  • prettier-plugin-zubra is Experimental and not published. It was listed as Supported and recommended, but it isn't on npm and depends on the compiler's folder; docs/editor-support.md says how to install it from a checkout, and it has a LICENSE. Found by the pre-6.0 audit.

  • The engine option is engine: 'zubra' | 'signals'. @zubra/unplugin, createZubra (Node and edge), buildRuntime() and buildApp() read signals mode as signals === true, so signals: 'true' or a typo (signal: true) was silently Zubra's engine. engine is 'zubra' (the default) or 'signals', and any other value is an error naming the two. signals: true, which 6.0.0-rc.0 shipped, still means engine: 'signals', with a development warning to write that. The plugin and createZubra also warn about an option name they don't know, with the nearest one (signal → engine: 'signals'). The plugin's README lists engine, devtools and compilerModule. Found by the pre-6.0 audit.

  • zb- is reserved for Zubra's own elements. An unknown <zb-…> element compiled silently into an element nothing defines (<zb-iff> for <zb-if>); it is now an error, with the nearest of the directives, <zb-outlet> and <zb-context> as help, or another prefix for a component of your own. A component named zb-… can't be used from another template any more: rename it (Migrating to 6.0). The examples, the reference's examples and the tests name theirs my-…. Found by the pre-6.0 audit.

  • 5.x's TC39 names say what happened to them, in development. On the default engine new Signal.subtle.Watcher() was "not a constructor", Signal.subtle.watched was undefined (so { [Signal.subtle.watched]: fn } never ran) and introspectSources?.() returned undefined. In the development build these names (and introspectSinks, hasSinks, hasSources) now throw an error that names signals mode and the migration guide, and a State or Computed made with a watched or unwatched option key warns once. The production build is byte for byte the same; the development build is about 300 B (gzip) larger. Found by the pre-6.0 audit.

  • The repository is github.com/zubra-js/zubra, and the site zubra-js.github.io/zubra. The old repository address redirects; the old site address doesn't. Update git remotes (git remote set-url origin https://github.com/zubra-js/zubra) and bookmarks. npm package names, the VS Code extension and the crate's name are unchanged.

  • Releases can be prereleases. scripts/bump-version.sh 6.0.0-rc.0 sets a prerelease; release.yml publishes it to npm under next, marks its GitHub release as a prerelease, and leaves the VS Code extension and the browser extension on the last release.

  • The server renders with less than half the allocations, and a large list in about half the time. The lowered tree borrows tag names, attribute names and literal text from the parsed component instead of copying them for every element of every render; a branch's or a list's rows go straight into the list they're part of, not through a list of their own; a text of one part needs no list; {row.name} in a list of a prop is read where it is (one copy, not two); a comparison with a string literal (type === "money") copies neither side; a request's props are moved into the render, not copied; a list's rows share one scope, their names borrowed, and their keys are checked for duplicates without being written out as text; a script binding that is a prop (const sorted = sortKey ? … : rows while there's no sort key) is that prop, not a copy of it; a zb-switch case ((column.type || "text") === "money") compares the side ||, ??, && or ?: picks where it is; a string method on an ASCII string reads it where it is instead of copying it to UTF-16 first, and + and template literals add to the string they're building instead of copying it; each component a page renders borrows its props' and script's names from the parsed component instead of copying them, and makes an attribute's camelCase name, a prop's kebab-case one, and its spread bookkeeping only when they differ or are used; an element's children are reserved from its template's shape instead of growing; a list inside a list's rows reuses the scope and key set the last one emptied, and reads its items without collecting them first; a call's one or two arguments are kept inline; toFixed rounds in the one string it answers with; names are lowercased only when they have an uppercase letter; and toFixed rounds from 20 digits more than asked instead of a number's whole 1,100-digit expansion, which it now writes only for a value that rounds to exactly half. The comparison table with 100 orders, per render (native, callgrind and DHAT): 19.5M → 11.0M instructions, 28,406 → 6,328 allocations, 4.4 MB → 1.9 MB allocated; wall-clock 1,653 → about 680 µs (3 orders 99 → about 54 µs; the field and quantity controls, one component each, 158 → 119 and 202 → 158 allocations and about 15% faster). Every .zb file in the repository renders to the same bytes as before.

  • The README is an introduction, and the reference is a page of its own (docs/reference.md). The README was 840 lines and served as both; it is now under 200: what Zubra is, a link to try it in the browser, the command to start an app, one component, who it is for, the packages and where the documentation is. Every section from "Writing a component" to "Standards" moved to the reference unchanged, with the same headings, so on the documentation site its address and anchors are as before. A link to a section of the old README (github.com/…/zubra#the-cli) now lands on the README's top, which links the reference; the skills' links point at the new page.

  • Hydration reads each marker once. Finding a component's parts in server markup steps over regions (<?zb [?> to <?zb ]?>), and it read each node's marker two or three times on the way, parsing a comment's text each time. Ten 100-row tables hydrating: 494,710 marker reads to 265,350, and about 9% less script time (CPU slowed 2×). 28 B gzip.

  • Effects keep half the memory and are made and disposed twice as fast. Each effect kept three arrays of what it read (each with room for about 20 entries on its first push), each signal two of what read it, a closure around the effect's function, and a Set of its children: for a scope with three effects, 49 objects and 3.8 KB alive. Dependencies and subscribers are now one array each, at their exact size while short; every effect runs through one shared method; an owner's children are a list through the children themselves. The same scope is 27 objects and 1.9 KB, and 1,000 of them are made in 0.65 ms instead of 1.4 and disposed in 0.37 instead of 0.8 (Node, perf microbenchmark). On the js-framework-benchmark's script-time profile, replacing 1,000 rows is about 9% faster (35.8 to 32.2 ms, and 34.6 to 31.6 in a second run); the other operations move by a few percent either way, within the noise. About 0.17 KB gzip on the runtime's base. Signals mode is unchanged.

  • Removing items from a long list is about a quarter faster. items.splice(i, 1) on a reactive array went through the proxy's traps for every element it shifted, a thousand sets with their bookkeeping for one row of a thousand, and the list then ran its whole keyed pass (every key, three maps, the longest run in order). Now push, pop, shift, unshift and splice run on the array itself and re-run only the readers of indexes from the first one they change (and of length when it moves); they no longer make the effect that calls them depend on the list. A keyed zb-each settles the rows that kept their key at either end first, and a removal from one place is done without the general pass. In the js-framework-benchmark's script-time profile, removing 10 rows of 1,000: 39.0 ms to 29.4 ms per cycle; the other operations are unchanged. About 0.3 KB gzip on the runtime's base.

  • @zubra/server minifies the component modules it sends in production, the CSS in them too. A module went as the compiler writes it, comments, indentation and authors' names included: across the registry's 26 components, 39.5 KB compressed (102.9 KB raw) is now 33.1 KB (75.5 KB raw), 16.4% fewer compressed bytes on every page. The compiler does it, with oxc's mangler and code generator (a new request command, minify; not oxc's whole minifier, which would bring JavaScript imports into the compiler's WebAssembly build), after everything the server changes in a module, and once per module; with bundle, the joined module is minified once, after joining. The CSS loses its comments and the whitespace next to {, }, ; and ,, and nothing else (a space before :, around + or before ( can mean something). Development and the DevTools get modules as the compiler writes them, and so does createZubra({ minify: false }); with a compiler from before the command, they go as they are. The compiler is larger for it (the native binary 8.1 MB to 8.6 MB). ZUBRA_MINIFY=1 runs the runtime's and the registry's browser suites on minified modules, and CI does.

  • Zubra's own reactive engine is the default; the TC39 Signals API is signals mode, experimental. The model doesn't change: state, computeds and effects, dependencies tracked as they're read, lazy, cached and glitch-free computeds with the equality cut-off, no virtual DOM, setup run once, each binding its own effect. The engine (runtime/src/signal.js) is one the runtime owns, so how an app updates no longer depends on a Stage 1 API, or on a browser shipping a native Signal that behaves differently. An effect is one node the graph marks directly, where on the API it was a Computed and a Watcher's links to it. In Node, creating and disposing 2,000 effects went from 6.6 ms to 1.5 ms, selecting one row of 1,000 from 0.54 ms to 0.47 ms. What every page of @zubra/server loads, file by file, went from 16.1 KB to 15.1 KB compressed, and the whole script API from 20.5 KB to 19.5 KB.

    • What changes for code (none of it for components, templates or the script API):
      • A native globalThis.Signal is no longer used, and isNative is always false.
      • The runtime's Signal export is State, Computed and subtle.untrack/subtle.currentComputed. new Signal.State(0) and Signal.subtle.untrack(fn) work as before; Signal.subtle.Watcher, the introspection functions and the watched/unwatched options don't exist. The typings say so.
      • What state() and computed() return is not an instance of another library's Signal.State, so it can't be handed to another Signals library as one. Zubra's own bridges (subscribe, toStore, React and Vue useSignal, @zubra/sync) work as before.
      • The Signals Inspector shows Zubra apps in signals mode only. Zubra DevTools work on both engines.
    • Signals mode: engine: 'signals' in @zubra/unplugin, in createZubra() of @zubra/server and @zubra/server/edge, and in buildRuntime() and buildApp(). Each puts signal-tc39.js where the runtime's engine is: the API, native where a browser has it, Zubra's implementation (signal-impl.js) otherwise, as in 5.x. @zubra/server then serves the runtime file by file in production too, since its one-file builds hold Zubra's engine. A built runtime must be built with the same option as the server that sends it, or the server refuses it. At the edge, serve dist/production with signal-tc39.js as signal.js, and not with bundle.
    • Both engines are tested. Every runtime suite (unit, browser, the production build) and Sync's run on both, and CI has a job for signals mode. The unit tests take ZUBRA_ENGINE=signals through a module hook (node --import ./test/engine/register.js), and the browser harness serves the engine it names.

Fixed#

  • The Actions CLI survives npm publishing. The zubra-actions command's path no longer has a leading ./, which npm 11 otherwise removes from the published package's commands.

  • The server starter works with the published 6.0 release candidate. Older @zubra/server packages without send() serve the page uncompressed and warn; current packages compress it as configured.

  • Starter and contributor workflows work on Windows. TypeScript starter configuration handles CRLF templates, and Sync's binary browser tests run from cmd.exe and find zubra-sync.exe.

  • The first-component tutorial uses the locally installed CLI. Its commands use npx zubra, so they work in a newly created app without a global install.

  • Clearer compile errors. @click={…} says to write onclick={…}. An element left open is reported where it opened (<div> is never closed), not at its parent's closing tag, with where the parser noticed in the help. <TodoList /> in a .zb template warns that custom element names are lowercase with a hyphen, and names <todo-list> and its import. Found by the pre-6.0 audit.

  • Compile errors in Vite say it once, with the file and the frame. A script error (let = = 2) was met first by the typings' compile, outside the plugin's error handling, so Vite's overlay had no file link or frame. Each error's message also held the whole compiler output, which Vite prints the frame after, so the source line showed twice; the message is now its first line. A compile error no longer carries the plugin's own stack frames (nor @zubra/server's, on its development 500 page; a crash keeps them), Error: error: and warning: warning: lose their doubled prefix, and several warnings from one component are reported one by one. Found by the pre-6.0 audit.

  • TypeScript project discovery works on Windows. tsconfig.json path aliases resolve consistently on Windows.

  • Server evaluation handles search offsets and string split limits. The Rust crate's test fixtures cover these cases alongside compiler tests.

  • The starters' own tests run inside the repository's. A test that runs node --test for a starter (the server starter's, each framework's, Astro's, the minified form script's) passed the runner's NODE_TEST_CONTEXT on, and a nested node --test that has it exits 0 whatever its tests did, so these never failed. They now run, and the one that had been failing was fixed: the Lit starter's test looked for #seen and async-tip p with document.querySelector, which doesn't reach into <my-app>'s shadow root; it uses Playwright's locators, which do (the app itself worked).

  • @zubra/unplugin with Vite: saving a component that doesn't compile no longer reloads the page. The error went to the overlay as it should, but the browser's fetch of the broken module then failed and Vite reloaded the page, so a typo threw away what it held: in every bundler starter, a counter clicked to 3 came back at 0 after the fix. The plugin now compiles a saved component in Vite's hotUpdate hook; one that doesn't compile is reported there (the overlay, with the source line and the compiler's help, and the terminal) and nothing is updated, so the page keeps the last version that worked; the fix is an ordinary hot update. Vite reloads when the first update after a page load finds its overlay up, so the overlay is closed before an update; a page loaded while a component was broken still reloads, as before. Found by trying the nine bundler starters as a newcomer: in each, the count now survives a broken tag, a misspelt name and an unknown name in a handler. In Astro the mistake keeps the page too, and saving the fix reloads it, as Astro does for a server-rendered page. In Vite's dev server, a component's compiler warnings (className on an element, say) now also go to the browser's console, where they only reached the terminal.

  • NaN.toFixed(2) in a template no longer fails the render. The server's evaluator wrote NaN as digits, and any precision but 0 panicked; a missing price formatted with toFixed failed the page. It renders NaN now, as JavaScript does (and Infinity, -Infinity).

  • Memory that grew for as long as a page or server ran. Found by an audit that made and removed thousands of elements of each kind and counted what stayed:

    • Shadow components: each kept a reference to its shadow root after it was gone, and only adoptStyles() let them go, so a page that never called it kept one per shadow element it ever made (about 48 bytes each). A root's reference now goes when the root is collected.
    • @zubra/sync: each document an element left kept an empty entry for its presence room, in the page and, with WebRTC, in the mesh (which also made one for every goodbye from a room it hadn't seen). Moving through a thousand documents kept a thousand. A room no one on the page is in is forgotten.
    • @zubra/sync/server: a live stream that closed while its backlog was being read (a viewer who left during a long first load) started its keep-alive anyway, and nothing stopped it: an interval every 15 s for the life of the server, holding the request. It doesn't start for a stream that has gone.
    • @zubra/server: each warning was remembered so as to be said once, and a surrogate-pair warning names its place in the data (reviews[57].name), so a server rendering such data kept every place it ever saw. After a thousand different warnings it starts again, so one may be said a second time.
  • @zubra/actions: a component that doesn't compile no longer takes a development server down. createActions() compiles every component when the server starts, to find its 'use server' functions, and threw at the first that didn't compile: an unclosed tag or a half-typed line of script in any file ended the process, node --watch started it into the same error, and the browser was left with "can't connect" while a mistake found later, when a page is rendered, gets an error page. In development that component is now left out with a warning that names the file and gives the compiler's error, the other components' functions are served, and the page shows the error when it is rendered. In production, and in zubra-actions build, it is still an error that stops the start. Found by making a newcomer's mistakes in the server starter.

  • origins lets another site in from a browser. createSyncServer({ origins }) and createActions({ origins }) were asked only when a request had no Sec-Fetch-Site, and every browser sends one, so a page on a listed site was refused like any other ("Cross-site writes are refused"). A listed Origin is now let in whatever Sec-Fetch-Site says; any other site is still refused.

  • A page on one of origins can read Sync. @zubra/sync/server sent no CORS headers, so even a listed site's browser kept every pull and live stream from the page, and refused to send its pushes (a JSON post asks first, and nothing answered yes). It now answers a listed Origin, preflights included, as the zubra-sync binary does for its --origins: access-control-allow-origin, -headers: content-type, -methods: GET, POST, OPTIONS, vary: origin. An unlisted site gets none. The server tests run this against both, and a browser test has a page on another site (127.0.0.1 to localhost) write, read and follow live, and one the server doesn't list get nothing.

  • @zubra/sync: presence goes only to the server whose scope has the room. Every connect() on a page was sent every element's presence, so a page connected to two servers (one for its rooms, one for its chat) posted each room's presence, and goodbyes, to both: the other server refused them (403), or took presence that wasn't its business. A connection with a scope now sends only its own rooms'. Found by open.chat in open.parlor, whose house chat has a Sync server of its own beside the rooms'.

  • @zubra/sync: a connection started after another stopped keeps the page's peer id. The live stream's key belonged to its connection, and went with stop(); the server keeps a stopped stream's peer id a while for its key, so the next connect() to the same server was refused (409) and gave the whole page a new peer id, under every other connection too. stop() now leaves its key for the next connection to the same server, which takes the stream over quietly. Only a stopped connection hands its key on: two open ones never share it. Found by open.chat, which had kept one connection open for the life of the page to stay clear of it.

  • choice-cards (registry): a card is only as tall as what it has. Its detail line and its price row were drawn for every item, so a card with only a title had an empty band beneath it. They're drawn when the item has them.

  • A streamed page always ends. A prop given as a promise that never settled held the response open for ever. After streamTimeout (30 s by default; createZubra({ streamTimeout }), or page({ streamTimeout }) for one page; 0 for none) it is rejected like any other error, and the stream ends.

  • A render that failed doesn't break the page. page.render() of a name that isn't a component threw, as it should, but recorded the name first, so head(), scripts() and finish() threw too, for the whole page. A component is now the page's once it has rendered.

  • Prop values JSON can't carry fail where they came from. NaN and ±Infinity arrived as null ("must be a number, found null"), a BigInt threw "Do not know how to serialize a BigInt", and a string with half a surrogate pair (text cut inside an emoji) failed every page that showed it with "the request isn't JSON: unexpected end of hex escape". The first three are now refused naming the component and where in the value (<book-card>'s prop book.price is a BigInt…); the last renders with U+FFFD in its place and a warning saying where. Functions and undefined are still left out, as JSON leaves them; a Date is still its ISO string. The same for slots and context.

Security#

  • redirect() refuses a location with a control character. Browsers drop tab, LF and CR from a URL, so redirect('/\t/evil.example/login') from @zubra/router sent a Location that arrived as //evil.example/login, another site: redirect(url.searchParams.get('next')) with next=/%09/evil.example/login sent a visitor off the site. Any C0 control character or DEL in the location is now a RouteError (a 500), and the ////\ path form must still resolve to the request's origin. Found by the pre-6.0 audit.

  • The enhanced-form script follows only an http(s) redirect. @zubra/actions' client navigated to any zb-location, javascript: included, so an action redirecting to a visitor's next ran script on the page. The server now passes a returned redirect on as zb-location only when it is http: or https: (any other goes out as the plain redirect, which neither fetch nor a browser follows), and the client ignores any other scheme with a console warning. Found by the pre-6.0 audit.

  • zubra convert writes only inside the input's folder. The converted file is named after the tag, and a custom element module's customElements.define('../../../pwned-x', …) (or /tmp/x/victim) wrote outside it. Both converters now require a custom element name (a lowercase ASCII letter first, a hyphen, only a-z 0-9 . _ -, no ..) and say why when the tag or the React function's name (with --prefix) isn't one. Found by the pre-6.0 audit.

  • A spread's style it can't write is left out, not a failed render. A spread whose style was text, or held a value like red;}, failed the whole server render, though a spread's object is often a visitor's data and the docs promise that what it may never set is left out with a warning. The server now leaves out the style, or just the property, and warns (omitted; createZubra({ warn })); the browser applies the same single-CSS-value rule (no ;, braces, <, backslash, url(, expression( or @import) and rejects nested values instead of handing them to the CSSOM. A style the author writes is still a compile error. Found by the pre-6.0 audit.

  • The playground's previews run sandboxed. A shared link (#…) rendered its code into a frame on the site's own origin. The previews are now sandbox="allow-scripts allow-forms allow-modals" frames, an opaque origin, and talk to the playground by postMessage: errors, the DevTools' "open in editor", and the Sync example's store, scoped to the component and page. The Zubra DevTools pane, which reads the top page, no longer reaches the playground's previews. Found by the pre-6.0 audit.

  • Workflows hold less. In pages.yml only the deploy job has pages: write and id-token: write; the build job, which runs installs and build scripts, has read access and no longer restores the Rust cache. release.yml's release job doesn't persist its token in the checkout, and @zubra/compiler's build runs cargo build --locked. Found by the pre-6.0 audit.

  • compress: true compresses a file once, however its path is spelled. The Node server kept what it had compressed by the request's path, and a path can be spelled without end (%7A for z, x/../): each new spelling of the runtime's base cost a synchronous Brotli at quality 11, about 40 ms of a blocked event loop, so a few dozen requests a second from anyone kept a production server busy. It is now kept by the content it sends. The server starter turns compress on. Found by security audit 4.

  • @zubra/sync's empty-collection warning holds one page of the log at a time. A live stream read from the start kept every page of the backlog until the last, for the warning it gives in development (and wherever NODE_ENV isn't production): a few streams from since=0 held a large log several times over. It now counts per collection as the pages go. Found by security audit 4.

  • Zubra DevTools write the page's numbers as numbers. A line, column, update number or count from the inspected page went into the pane's markup as the page gave it, so a page could put markup of its own into its inspector (no script: the extension's policy blocks it). Found by security audit 4.

  • The server starter's guest book keeps its latest 50 notes. Anyone can sign it, and every page showed every note ever written. Found by security audit 4.

  • A streamed prop's error stays on the server. When a prop given as a promise rejected, @zubra/server sent the error's message to the browser as it was, for the component's <zb-catch> to show: a database's error (hosts, users, queries) reached the visitor. In production the browser now gets "Internal error"; development keeps the message. The error goes to the new createZubra({ onError: (error, { component, prop }) => … }), or to warn with its stack. @zubra/server/edge is production unless given production: false. Found by the call-store app serving real data.

6.0.0-rc.0 — 2026-11-20#

A release candidate for 6.0.0, on npm's next tag: npm install @zubra/runtime@next @zubra/compiler@next (and the same for the other packages) tries it, and a plain npm install keeps 5.23. The VS Code extension stays on 5.23.0 until 6.0.0.

6.0.0: Zubra's own reactive engine is the default, and the TC39 Signals API is an experimental mode. Components, templates and the script API don't change, and neither does compiled output: code compiled by 5.18 and later runs on either engine. What changes is only for code that relied on a state being the proposal's object; signals: true keeps 5.x's behaviour for that code. Migrating to 6.0 lists what to look for.

Changed#

  • The repository is github.com/zubra-js/zubra, and the site zubra-js.github.io/zubra. The old repository address redirects; the old site address doesn't. Update git remotes (git remote set-url origin https://github.com/zubra-js/zubra) and bookmarks. npm package names, the VS Code extension and the crate's name are unchanged.
  • Releases can be prereleases. scripts/bump-version.sh 6.0.0-rc.0 sets a prerelease; release.yml publishes it to npm under next, marks its GitHub release as a prerelease, and leaves the VS Code extension and the browser extension on the last release.
  • The server renders with less than half the allocations, and a large list in about half the time. The lowered tree borrows tag names, attribute names and literal text from the parsed component instead of copying them for every element of every render; a branch's or a list's rows go straight into the list they're part of, not through a list of their own; a text of one part needs no list; {row.name} in a list of a prop is read where it is (one copy, not two); a comparison with a string literal (type === "money") copies neither side; a request's props are moved into the render, not copied; a list's rows share one scope, their names borrowed, and their keys are checked for duplicates without being written out as text; a script binding that is a prop (const sorted = sortKey ? … : rows while there's no sort key) is that prop, not a copy of it; a zb-switch case ((column.type || "text") === "money") compares the side ||, ??, && or ?: picks where it is; a string method on an ASCII string reads it where it is instead of copying it to UTF-16 first, and + and template literals add to the string they're building instead of copying it; each component a page renders borrows its props' and script's names from the parsed component instead of copying them, and makes an attribute's camelCase name, a prop's kebab-case one, and its spread bookkeeping only when they differ or are used; an element's children are reserved from its template's shape instead of growing; a list inside a list's rows reuses the scope and key set the last one emptied, and reads its items without collecting them first; a call's one or two arguments are kept inline; toFixed rounds in the one string it answers with; names are lowercased only when they have an uppercase letter; and toFixed rounds from 20 digits more than asked instead of a number's whole 1,100-digit expansion, which it now writes only for a value that rounds to exactly half. The comparison table with 100 orders, per render (native, callgrind and DHAT): 19.5M → 11.0M instructions, 28,406 → 6,328 allocations, 4.4 MB → 1.9 MB allocated; wall-clock 1,653 → about 680 µs (3 orders 99 → about 54 µs; the field and quantity controls, one component each, 158 → 119 and 202 → 158 allocations and about 15% faster). Every .zb file in the repository renders to the same bytes as before.
  • The README is an introduction, and the reference is a page of its own (docs/reference.md). The README was 840 lines and served as both; it is now under 200: what Zubra is, a link to try it in the browser, the command to start an app, one component, who it is for, the packages and where the documentation is. Every section from "Writing a component" to "Standards" moved to the reference unchanged, with the same headings, so on the documentation site its address and anchors are as before. A link to a section of the old README (github.com/…/zubra#the-cli) now lands on the README's top, which links the reference; the skills' links point at the new page.
  • Hydration reads each marker once. Finding a component's parts in server markup steps over regions (<?zb [?> to <?zb ]?>), and it read each node's marker two or three times on the way, parsing a comment's text each time. Ten 100-row tables hydrating: 494,710 marker reads to 265,350, and about 9% less script time (CPU slowed 2×). 28 B gzip.
  • Effects keep half the memory and are made and disposed twice as fast. Each effect kept three arrays of what it read (each with room for about 20 entries on its first push), each signal two of what read it, a closure around the effect's function, and a Set of its children: for a scope with three effects, 49 objects and 3.8 KB alive. Dependencies and subscribers are now one array each, at their exact size while short; every effect runs through one shared method; an owner's children are a list through the children themselves. The same scope is 27 objects and 1.9 KB, and 1,000 of them are made in 0.65 ms instead of 1.4 and disposed in 0.37 instead of 0.8 (Node, perf microbenchmark). On the js-framework-benchmark's script-time profile, replacing 1,000 rows is about 9% faster (35.8 to 32.2 ms, and 34.6 to 31.6 in a second run); the other operations move by a few percent either way, within the noise. About 0.17 KB gzip on the runtime's base. Signals mode is unchanged.
  • Removing items from a long list is about a quarter faster. items.splice(i, 1) on a reactive array went through the proxy's traps for every element it shifted, a thousand sets with their bookkeeping for one row of a thousand, and the list then ran its whole keyed pass (every key, three maps, the longest run in order). Now push, pop, shift, unshift and splice run on the array itself and re-run only the readers of indexes from the first one they change (and of length when it moves); they no longer make the effect that calls them depend on the list. A keyed zb-each settles the rows that kept their key at either end first, and a removal from one place is done without the general pass. In the js-framework-benchmark's script-time profile, removing 10 rows of 1,000: 39.0 ms to 29.4 ms per cycle; the other operations are unchanged. About 0.3 KB gzip on the runtime's base.
  • @zubra/server minifies the component modules it sends in production, the CSS in them too. A module went as the compiler writes it, comments, indentation and authors' names included: across the registry's 26 components, 39.5 KB compressed (102.9 KB raw) is now 33.1 KB (75.5 KB raw), 16.4% fewer compressed bytes on every page. The compiler does it, with oxc's mangler and code generator (a new request command, minify; not oxc's whole minifier, which would bring JavaScript imports into the compiler's WebAssembly build), after everything the server changes in a module, and once per module; with bundle, the joined module is minified once, after joining. The CSS loses its comments and the whitespace next to {, }, ; and ,, and nothing else (a space before :, around + or before ( can mean something). Development and the DevTools get modules as the compiler writes them, and so does createZubra({ minify: false }); with a compiler from before the command, they go as they are. The compiler is larger for it (the native binary 8.1 MB to 8.6 MB). ZUBRA_MINIFY=1 runs the runtime's and the registry's browser suites on minified modules, and CI does.
  • Zubra's own reactive engine is the default; the TC39 Signals API is signals mode, experimental. The model doesn't change: state, computeds and effects, dependencies tracked as they're read, lazy, cached and glitch-free computeds with the equality cut-off, no virtual DOM, setup run once, each binding its own effect. The engine (runtime/src/signal.js) is one the runtime owns, so how an app updates no longer depends on a Stage 1 API, or on a browser shipping a native Signal that behaves differently. An effect is one node the graph marks directly, where on the API it was a Computed and a Watcher's links to it. In Node, creating and disposing 2,000 effects went from 6.6 ms to 1.5 ms, selecting one row of 1,000 from 0.54 ms to 0.47 ms. What every page of @zubra/server loads, file by file, went from 16.1 KB to 15.1 KB compressed, and the whole script API from 20.5 KB to 19.5 KB.
    • What changes for code (none of it for components, templates or the script API):
      • A native globalThis.Signal is no longer used, and isNative is always false.
      • The runtime's Signal export is State, Computed and subtle.untrack/subtle.currentComputed. new Signal.State(0) and Signal.subtle.untrack(fn) work as before; Signal.subtle.Watcher, the introspection functions and the watched/unwatched options don't exist. The typings say so.
      • What state() and computed() return is not an instance of another library's Signal.State, so it can't be handed to another Signals library as one. Zubra's own bridges (subscribe, toStore, React and Vue useSignal, @zubra/sync) work as before.
      • The Signals Inspector shows Zubra apps in signals mode only. Zubra DevTools work on both engines.
    • Signals mode: signals: true in @zubra/unplugin, in createZubra() of @zubra/server and @zubra/server/edge, and in buildRuntime() and buildApp(). Each puts signal-tc39.js where the runtime's engine is: the API, native where a browser has it, Zubra's implementation (signal-impl.js) otherwise, as in 5.x. @zubra/server then serves the runtime file by file in production too, since its one-file builds hold Zubra's engine. A built runtime must be built with the same option as the server that sends it, or the server refuses it. At the edge, serve dist/production with signal-tc39.js as signal.js, and not with bundle.
    • Both engines are tested. Every runtime suite (unit, browser, the production build) and Sync's run on both, and CI has a job for signals mode. The unit tests take ZUBRA_ENGINE=signals through a module hook (node --import ./test/engine/register.js), and the browser harness serves the engine it names.

Security#

  • compress: true compresses a file once, however its path is spelled. The Node server kept what it had compressed by the request's path, and a path can be spelled without end (%7A for z, x/../): each new spelling of the runtime's base cost a synchronous Brotli at quality 11, about 40 ms of a blocked event loop, so a few dozen requests a second from anyone kept a production server busy. It is now kept by the content it sends. The server starter turns compress on. Found by security audit 4.

  • @zubra/sync's empty-collection warning holds one page of the log at a time. A live stream read from the start kept every page of the backlog until the last, for the warning it gives in development (and wherever NODE_ENV isn't production): a few streams from since=0 held a large log several times over. It now counts per collection as the pages go. Found by security audit 4.

  • Zubra DevTools write the page's numbers as numbers. A line, column, update number or count from the inspected page went into the pane's markup as the page gave it, so a page could put markup of its own into its inspector (no script: the extension's policy blocks it). Found by security audit 4.

  • The server starter's guest book keeps its latest 50 notes. Anyone can sign it, and every page showed every note ever written. Found by security audit 4.

  • A streamed prop's error stays on the server. When a prop given as a promise rejected, @zubra/server sent the error's message to the browser as it was, for the component's <zb-catch> to show: a database's error (hosts, users, queries) reached the visitor. In production the browser now gets "Internal error"; development keeps the message. The error goes to the new createZubra({ onError: (error, { component, prop }) => … }), or to warn with its stack. @zubra/server/edge is production unless given production: false. Found by the call-store app serving real data.

Fixed#

  • The starters' own tests run inside the repository's. A test that runs node --test for a starter (the server starter's, each framework's, Astro's, the minified form script's) passed the runner's NODE_TEST_CONTEXT on, and a nested node --test that has it exits 0 whatever its tests did, so these never failed. They now run, and the one that had been failing was fixed: the Lit starter's test looked for #seen and async-tip p with document.querySelector, which doesn't reach into <my-app>'s shadow root; it uses Playwright's locators, which do (the app itself worked).

  • @zubra/unplugin with Vite: saving a component that doesn't compile no longer reloads the page. The error went to the overlay as it should, but the browser's fetch of the broken module then failed and Vite reloaded the page, so a typo threw away what it held: in every bundler starter, a counter clicked to 3 came back at 0 after the fix. The plugin now compiles a saved component in Vite's hotUpdate hook; one that doesn't compile is reported there (the overlay, with the source line and the compiler's help, and the terminal) and nothing is updated, so the page keeps the last version that worked; the fix is an ordinary hot update. Vite reloads when the first update after a page load finds its overlay up, so the overlay is closed before an update; a page loaded while a component was broken still reloads, as before. Found by trying the nine bundler starters as a newcomer: in each, the count now survives a broken tag, a misspelt name and an unknown name in a handler. In Astro the mistake keeps the page too, and saving the fix reloads it, as Astro does for a server-rendered page. In Vite's dev server, a component's compiler warnings (className on an element, say) now also go to the browser's console, where they only reached the terminal.

  • NaN.toFixed(2) in a template no longer fails the render. The server's evaluator wrote NaN as digits, and any precision but 0 panicked; a missing price formatted with toFixed failed the page. It renders NaN now, as JavaScript does (and Infinity, -Infinity).

  • Memory that grew for as long as a page or server ran. Found by an audit that made and removed thousands of elements of each kind and counted what stayed:

    • Shadow components: each kept a reference to its shadow root after it was gone, and only adoptStyles() let them go, so a page that never called it kept one per shadow element it ever made (about 48 bytes each). A root's reference now goes when the root is collected.
    • @zubra/sync: each document an element left kept an empty entry for its presence room, in the page and, with WebRTC, in the mesh (which also made one for every goodbye from a room it hadn't seen). Moving through a thousand documents kept a thousand. A room no one on the page is in is forgotten.
    • @zubra/sync/server: a live stream that closed while its backlog was being read (a viewer who left during a long first load) started its keep-alive anyway, and nothing stopped it: an interval every 15 s for the life of the server, holding the request. It doesn't start for a stream that has gone.
    • @zubra/server: each warning was remembered so as to be said once, and a surrogate-pair warning names its place in the data (reviews[57].name), so a server rendering such data kept every place it ever saw. After a thousand different warnings it starts again, so one may be said a second time.
  • @zubra/actions: a component that doesn't compile no longer takes a development server down. createActions() compiles every component when the server starts, to find its 'use server' functions, and threw at the first that didn't compile: an unclosed tag or a half-typed line of script in any file ended the process, node --watch started it into the same error, and the browser was left with "can't connect" while a mistake found later, when a page is rendered, gets an error page. In development that component is now left out with a warning that names the file and gives the compiler's error, the other components' functions are served, and the page shows the error when it is rendered. In production, and in zubra-actions build, it is still an error that stops the start. Found by making a newcomer's mistakes in the server starter.

  • origins lets another site in from a browser. createSyncServer({ origins }) and createActions({ origins }) were asked only when a request had no Sec-Fetch-Site, and every browser sends one, so a page on a listed site was refused like any other ("Cross-site writes are refused"). A listed Origin is now let in whatever Sec-Fetch-Site says; any other site is still refused.

  • A page on one of origins can read Sync. @zubra/sync/server sent no CORS headers, so even a listed site's browser kept every pull and live stream from the page, and refused to send its pushes (a JSON post asks first, and nothing answered yes). It now answers a listed Origin, preflights included, as the zubra-sync binary does for its --origins: access-control-allow-origin, -headers: content-type, -methods: GET, POST, OPTIONS, vary: origin. An unlisted site gets none. The server tests run this against both, and a browser test has a page on another site (127.0.0.1 to localhost) write, read and follow live, and one the server doesn't list get nothing.

  • @zubra/sync: presence goes only to the server whose scope has the room. Every connect() on a page was sent every element's presence, so a page connected to two servers (one for its rooms, one for its chat) posted each room's presence, and goodbyes, to both: the other server refused them (403), or took presence that wasn't its business. A connection with a scope now sends only its own rooms'. Found by open.chat in open.parlor, whose house chat has a Sync server of its own beside the rooms'.

  • @zubra/sync: a connection started after another stopped keeps the page's peer id. The live stream's key belonged to its connection, and went with stop(); the server keeps a stopped stream's peer id a while for its key, so the next connect() to the same server was refused (409) and gave the whole page a new peer id, under every other connection too. stop() now leaves its key for the next connection to the same server, which takes the stream over quietly. Only a stopped connection hands its key on: two open ones never share it. Found by open.chat, which had kept one connection open for the life of the page to stay clear of it.

  • choice-cards (registry): a card is only as tall as what it has. Its detail line and its price row were drawn for every item, so a card with only a title had an empty band beneath it. They're drawn when the item has them.

  • A streamed page always ends. A prop given as a promise that never settled held the response open for ever. After streamTimeout (30 s by default; createZubra({ streamTimeout }), or page({ streamTimeout }) for one page; 0 for none) it is rejected like any other error, and the stream ends.

  • A render that failed doesn't break the page. page.render() of a name that isn't a component threw, as it should, but recorded the name first, so head(), scripts() and finish() threw too, for the whole page. A component is now the page's once it has rendered.

  • Prop values JSON can't carry fail where they came from. NaN and ±Infinity arrived as null ("must be a number, found null"), a BigInt threw "Do not know how to serialize a BigInt", and a string with half a surrogate pair (text cut inside an emoji) failed every page that showed it with "the request isn't JSON: unexpected end of hex escape". The first three are now refused naming the component and where in the value (<book-card>'s prop book.price is a BigInt…); the last renders with U+FFFD in its place and a warning saying where. Functions and undefined are still left out, as JSON leaves them; a Date is still its ISO string. The same for slots and context.

Added#

  • zubra.errorPage(error): a development error page for any @zubra/server app. The server starter wrote its own: the error's message in the open page, which went away once the fix was saved; an app without that code got whatever it wrote itself (often plain text, or the stack). errorPage(error) gives { status: 500, type, body } to send from the app's catch. In development: an HTML page with the message, escaped (a component's comes with its file, line, a caret and often a fix), and the stack's frames, carrying the reload script when that's on. In production: "Something went wrong" as plain text, never the message, which can hold a query, a path or a host. errorPage(error, { nonce }) for a Content-Security-Policy nonce. Node and the edge (a Worker is production unless production: false). The server starter and the help desk example use it.

  • The Zubra DevTools pane shows more of the reactive engine. A binding that re-ran says why: the signals it reads that the update wrote, followed through computeds (re-ran because doubled ← count changed). A Signals section lists the component's props, state and computeds with their values, how many times each has changed, what reads it (bindings by their DOM operation, computeds by name) and what a computed reads. Live counts the effects in the component, the components on the page, and the effects made since the pane connected that are still alive, with how that count moved over the last updates (counting starts when the pane connects, so a page that never opens it pays nothing; removed elements' effects leave the count when they're garbage-collected). Updates lists the page's last 50: what each wrote (from and to), what it re-ran, in which component, and how long it took. The header names the engine. Read-only, as before; development builds only (the production runtime is byte for byte the same); the pane's DevTools version stays 1, so an older extension and a newer runtime, or the reverse, still work together. Signals mode shows everything but the change counts. The Signals Inspector is unchanged.

  • A warning for className and htmlFor in a .zb template. They are React's names for class and for. HTML has neither, so <button className="more"> was sent as written, the browser read an attribute nothing uses, and the styling was gone with no message; zubra check said "no errors". The compiler now warns at the attribute, with write \class`as the help, inzubra check, the editors and the server's log. Not for a child component that declares a prop of that name, and not in a JSX component, where those names are the right ones. (onClickneeds none: attribute names aren't case-sensitive, so it isonclick`.)

  • createZubra({ reload: true }): saved components update the open page in place, and the server starter uses it. npm create zubra -- --framework server restarts its server on a saved file (node --watch), but the open page stayed as it was until someone reloaded it, where every bundler starter updates on save. With reload, page.finish() and page.scripts() add a small script (<prefix>/reload.js, a file, so no policy has to allow it inline) that keeps an event stream to the server open; when the stream is lost and then opens again, the server is back. The script then asks what each of the page's components is now (<prefix>/reload/versions/…), imports the ones that changed, and the runtime swaps each into its live elements, keeping their state, as the bundler starters' hot updates do; a change to anything else (the server's own code, a component's props or events, one that doesn't compile) reloads the page. In the starter a saved template edit shows in about 0.6 s with the counter's count kept. Nothing watches files: the restart is the signal, so a server that doesn't restart doesn't update. Off by default; Node only.

    • The starter turns it on in development, its error page in development is a page with the same script (so it goes away when the fix is saved), and the counter's comment and the welcome line ("updates in place, keeping its count") are now true of it too.
  • Compared on one app (docs/compared-on-one-app.md): one slice of an ordering app (live menu, bag, pickup time, checkout, live order page) built twelve ways, in Zubra twice, Lit, Enhance, Stencil, FAST, WebUI, SvelteKit, Next.js and Nuxt, on one backend and one set of browser tests, measured on 5.23.0. Where Zubra is ahead (a tap on a slow phone, pages served, lines of code) and where it is behind (download size, menu load, start-up, memory). Each build's code, the spec, the tests, the measuring script and the raw results are in docs/compared/slice/; the backend they share is not published, so they can be read but not rerun.

  • @zubra/unplugin: autoImport, tags without imports. A page can only use a component's tag once something has imported it, so an app with many pages kept a side-effect import in every file or one file listing them all (open.parlor has seven such files, 154 lines). zubra({ autoImport: ['./src/components', '@acme/ui/components'] }) names folders of components, the app's or a package's, and a .svelte, .vue, .jsx or .tsx file that opens one of their tags gets import '…/tool-bar.zb?element' written for it. A component is known by its host tag, not its file's name; only the tags a file uses are imported, so an unused component stays out of the build; the import goes on a line that is already there, so line numbers don't move. In Vite, Rollup, webpack, esbuild and Rspack. Off by default. Not for Astro pages or Angular.

  • createZubra({ compress: true }): the server's files in Brotli or gzip. zubra.handle() and zubra.fetch() sent every file as it is, so the sizes these notes give held only behind a CDN or proxy that compresses: on a plain Node host the browser was sent the runtime's base as 30.5 KB, not 12. With compress: true they answer in Brotli when the request's accept-encoding takes it, in gzip when it takes that, and as before otherwise, with vary: accept-encoding either way. Off by default, so no existing app's responses change; npm create zubra's server app turns it on.

    • Each file is compressed once and kept: what stays the same until a restart gets the smallest encoding (the base is 11.0 KB in Brotli, 12.0 KB in gzip; Brotli takes about 36 ms for it, once), and what an edit may change in development a quick one. Files under 1 KB go as they are.
    • Measured on the comparison's menu page, on a slowed phone over slow 4G: 570 ms to 481 ms to the load event, and 39.4 KB to 21.2 KB sent (20.0 KB in Brotli). On fast 4G, 240 ms to 225 ms.
    • Leave it off where something in front compresses already, and at the edge, where the platform does. It covers what Zubra serves under its prefix; the page's own HTML and CSS are the app's to compress.
  • buildApp() from @zubra/server/build: the whole app as one module (experimental). A page loaded the runtime, a module per component and each script of its own: four requests on the comparison's menu page, and on a slowed phone the requests, not the work in them, were most of the time between Zubra and the single-file libraries. buildApp({ components, scripts }) builds what buildRuntime() does and puts every component, the plain modules they import and the page scripts you name into the same module; passed as createZubra({ runtime }), it is a page's only script and only preload. On that menu page, CPU slowed six times, thirty interleaved loads: 301 ms to 242 ms to the load event, level with Lit (244), and 12.7 KB in four files to 12.1 KB in one. @zubra/sync is in the module too, where a component or a script of the app's uses it, and the package's own address (/_zubra/sync/index.js) then answers from the module, so a script outside it shares the one store; connect()'s peer-to-peer module stays a file loaded when asked for. On the comparison's build with Sync, thirty interleaved loads, sent in Brotli: 522 ms with the package beside the module (three files, 14.7 KB) to 452 ms with it inside (one file, 13.5 KB); the same page on 5.23.0 was five files and 567 ms in that run.

    • Every page loads the same module, so it is cached once; it defines every component of the app, whether the page uses it or not.
    • A script you name runs on the components' copy of the runtime: import { effect } from '@zubra/runtime' in it is theirs.
    • A component added since the build is refused when its page is made, with a message that says to build again. A component's own address (/_zubra/components/<name>.js) answers with an import of the module, so nothing defines an element twice.
    • As buildRuntime(): needs esbuild installed by the app, production only, not at the edge.

5.23.0 — 2026-11-18#

Added#

  • buildRuntime() from @zubra/server/build: an app's own build of the runtime (experimental). @zubra/server has no bundler, so the runtime file a page loads holds everything any component might use of it. An app that installs esbuild can now have one built for it: every name its components, the plain modules beside them and @zubra/sync import from the runtime is collected, and the result is one module with those names and only what they reach. createZubra({ runtime }) serves it in production in place of the base and the files beside it; development ignores it. It takes a fraction of a second, so const runtime = await buildRuntime({ components }) when the server starts is enough.

    • On the comparison's menu app the runtime file goes from 12.0 KB to 10.5 KB compressed (the app has a list on another page, so zb-each stays in). On an app that uses context, form controls, event modifiers, shadow roots and resource(): one file of 12.1 KB where a page loaded seven, 18.4 KB.
    • A component that names something the build doesn't have (added since it was built) is refused when it is compiled, with a message that says to build again; it never reaches the browser half-working. keep: ['watch'] adds names for a <script type="module"> of your own.
    • While a built runtime is served, the runtime's own files answer with a module that throws and says why: loaded beside it they would be a second copy, with signals the first can't see.
    • Not at the edge, not with imports['@zubra/runtime'], and not for components compiled by Zubra 5.19 or older. esbuild is an optional peer: nothing changes for an app that doesn't install it.
  • --emit element provides onFormReset, onFormRestore and onFormDisabled (#367). A plain element had formValue and validity, half of the form-associated API, and refused the other half, so a control that wanted to hear a disabled <fieldset> couldn't be a plain element (zubra-ui's toggle-switch worked around it with a disabled prop). The three hooks are now the class's formResetCallback, formStateRestoreCallback(state, mode) and formDisabledCallback(disabled), written only for a component whose script asks for them. As with the runtime, a script's own onFormReset is the reset, in place of a single two-way prop going back to what it started as, and a control disabled before its script ran hears it once it has. zubra convert reads the hooks back. One difference from --emit js: in a component without form-associated, where the browser would never call them, the compiler says so ("onFormDisabled() needs form-associated on the component's host tag") where the runtime throws when the element starts.

Changed#

  • The Preact example (examples/frameworks/preact-habits) is on Preact 11.2.0, from 10.29.8, so the framework tests run against the Preact people install today. The example passes unchanged. It has no keyed list inside a component's slot, so what guards moveBefore() on a host (below) is the runtime's own browser test, not this example. The Preact starter (npm create zubra -- --framework preact) still asks for ^10.29.8.

Fixed#

  • @zubra/server's types have packages and imports (#375). createZubra took both, the guide documents packages ("Components from a package") and the tests use both, and ZubraOptions had neither, so a TypeScript server that followed the guide didn't compile: "'packages' does not exist in type 'ZubraOptions'". A test now compares the options the function reads with the ones the type declares.
  • A .zb import in a .svelte file is the element, in any project (#377). In a Vite app whose framework is React or Vue, a Svelte file's import fell through to the project's wrapper: a React component Svelte can't render, or, for a bare import './x.zb', the wrapper and its adapter loaded for nothing. Svelte renders custom elements directly, so its files now get the element class whatever the project around them, as a .vue file gets the Vue component in a React app. ?react or ?vue on the import still picks a wrapper. Found in open.parlor's Svelte editors inside its React app, which had to import with ?element.
  • A light-DOM host routes moveBefore() to its slots, so Preact 11 can reorder slotted children (#370). Frameworks manage an element's children through the host, and the host passed insertBefore, appendChild, removeChild and the rest on to its slots, but not moveBefore. Preact 11 reorders keyed children with moveBefore() where the browser has it (Chromium and Firefox), so reversing a keyed list inside a component threw "The node before which the new node is to be inserted is not a child of this node" and the list kept its old order. host.moveBefore(node, before) now places the node as insertBefore does, and a node already in its slot is moved there with its state kept. It is defined only where the browser has the method, since frameworks ask for it by name. The same in --emit element output, whose own helper for moving a row now calls the platform's moveBefore and not one a host overrides. Found by open.parlor's conformance suite on Preact 11.2; examples/frameworks pinned Preact 10, which only uses insertBefore.

5.22.0 — 2026-11-17#

Changed#

  • A page of @zubra/server loads less of the runtime: its base, and only the rest its components name. The file every page loaded in production (runtime/zubra.js) carried the whole script API, used or not: 14.3 KB compressed. It is now the base, 11.7 KB, and what only some components use is in files beside it, each sent to the pages whose components name it: context (provide.js, 0.85 KB), form controls and their helpers (form.js, 1.2), event modifiers and helpers (modifiers.js, 1.1), shadow roots (shadow.js, 0.6) and resource() (resource.js, 0.65). A page that uses none loads 2.6 KB less; one that uses event modifiers about 1.5 KB less, in one more request (preloaded, so not another round). The server sends each module the names it imports from the file that has them, by address, as it already did for zb-await and slots; that covers components, the plain modules they import and @zubra/sync's.
    • Nothing to change in an app. The script API is the same, from the same import (@zubra/runtime); @zubra/runtime/core exports what it did; bundlers and @zubra/unplugin are untouched.
    • A <script type="module"> of your own that imports @zubra/runtime gets the whole API as before, from the same modules the components use, now as the base and five small files where it was one.
    • With imports: { '@zubra/runtime': … } (a CDN) nothing changes: every name comes from the address you gave.
    • A server from before this release with this runtime is unaffected: dist/bundled is still whole, and the split build is a folder of its own (dist/split).
    • At the edge, serve dist/split where you served dist/bundled (which still works, without the saving). Pages using @zubra/sync from static assets load the whole API there, since the Worker can't rewrite files it doesn't serve.
    • In the runtime, the helpers moved out of element.js into provide.js, form.js and modifiers.js, and base.js is the new smaller entry; @zubra/runtime/modules gained split.

5.21.1 — 2026-11-17#

Changed#

  • @zubra/actions serves its browser scripts minified in production. actions.script()'s module and the form script (/_zb/enhance-forms.js) were sent as written, comments included: 1.34 KB and 1.85 KB compressed. In production (NODE_ENV=production, or createActions({ production: true })) they now come from the package's dist/production: 0.78 KB and 1.04 KB. Development serves the source as before. Found by Potomac's comparison, where the form script added more to the menu page than follow() took off. At the edge, serve dist/production/client.js and dist/production/enhance-forms.js from your static assets, or pass their text as client and forms.

5.21.0 — 2026-11-17#

Added#

  • Plain form posts without the reload: data-zb-updates and @zubra/actions/enhance-forms (experimental). A form that posts to an app's own route and is redirected back loaded the whole page again. A form that names the parts of the page its post changes, <form method="post" action="/add" data-zb-updates="site said">, is now sent with fetch, and those parts' children come from the page the server redirects to; the rest of the page, components and typed input included, stays. The server is unchanged, and so is every form without the attribute. actions.formsScript() writes the script tag and createActions serves it at /_zb/enhance-forms.js (0.9 KB compressed). On the comparison's menu page on a slow phone, adding an item took 264 ms, from 525.
  • follow() from @zubra/sync/follow: a connection for a page that only reads (experimental). A page whose server writes its documents and never lets a page write loaded connect()'s outbox, pushes, presence and peer code for nothing. follow() pulls and listens exactly as connect() does (the same cursor, scope, merge by clock and reconnecting, tested against the same cases) and has none of the rest: 3.5 KB compressed against 4.9 on a read-only menu page. An edit on such a page stays on that device and is reported once in the console. connect() and every existing page are unchanged. @zubra/server maps and serves it beside connect.js.

Fixed#

  • The server starter (npm create zubra -- --framework server): an edited 'use server' function now applies without restarting by hand, and errors are 500s that say why. npm run dev restarted only for server.js, and @zubra/actions loads server functions once at start, so an edit to one did nothing until the server was stopped and started; a component broken at start left the server down after the fix was saved. The script now restarts for anything in src/ as well (data kept in memory starts over with it). An error while rendering the page was sent with status 200 and the words "Something went wrong"; it is now a 500, and in development the page shows the compiler's message (file, line, suggested fix) that the terminal shows. New apps only: an existing app can copy the dev script and the try block from the template.

5.20.0 — 2026-11-16#

Added#

  • Typings for Solid 2. Solid 2 (2.0.0-rc) keeps JSX in @solidjs/web/jsx-runtime, not solid-js, so the Solid typings declared nothing it reads: <choice-cards> was an unknown element. And it compiles on:valuechange to a listener for an event named ":valuechange", which never fires; onvaluechange (or onValueChange) is what listens for "valuechange". --framework solid2 (--emit dts, zubra types) declares the element there, with prop: for properties and on<event> for events, and zubra types and the build plugin's dts choose it when the app's solid-js is 2 or later (installed, or else asked for in its package.json). Solid 1 apps get what they did. The MCP server's component_usage takes solid2, and the consuming skills (the repository's, npm create zubra's and zubra build --lib's) have a Solid 2 row. Checked by TypeScript against Solid 2.0.0-rc.22's own types. (#234)

Security#

  • The release job runs nothing it didn't pin. .github/workflows/release.yml publishes every @zubra package and the VS Code extension through trusted publishing, with provenance, and ran third-party code from references that move: dtolnay/rust-toolchain@master, Swatinem/rust-cache@v2 and the actions/*@v4 tags, npx --yes @vscode/vsce (the newest vsce on every release) and npm install -g npm@11. A compromised upstream would have run with the job's publishing identity. Every action in every workflow is now pinned to a commit, with its version in a comment, and .github/dependabot.yml proposes updates weekly; the publishing job has no build cache (one any run on main can write); npm is pinned to 11.21.2; and @vscode/vsce is the extension's own devDependency (4.1.1), installed from its lockfile. Found in the 2026-11-16 audit.
  • The .vsix carries only dependencies its lockfiles name. editors/vscode/scripts/package.mjs installed the packaged extension's dependencies with --no-package-lock, so everything below its exact direct dependencies resolved fresh at release time, install scripts included. It now installs from the extension's committed lockfile without install scripts, takes only the language server being released from the registry, and checks every installed package's version and hash against the extension's and the language server's lockfiles, stopping the release on anything else (scripts/locked.mjs, tested in test/locked.test.js). The first run caught brace-expansion 5.0.13, published five days ago, which the old install would have shipped in place of the locked 5.0.12.
  • zubra-sync bundles SQLite 3.54.1. It built rusqlite 0.37 with SQLite 3.53 (RUSTSEC-2026-0459, CVE-2026-119375: a database opened with a crafted -wal file of another page size can return uninitialised memory). Now rusqlite 0.41. It only mattered where someone less trusted could write the --db file and its -wal; nothing in its code changed.
  • The edge examples use wrangler 4.162.0 (from 4.45.0), whose advisories (command injection in wrangler pages deploy, and undici, ws, sharp and zod through miniflare) were in the examples people copy, though nothing published used them.

Changed#

  • npm create zubra -- --framework server: a server-rendered app to start from. Every starter was a bundler's client-side app, so an app with no host framework had no "start here": the server, the forms and the router each had a page of documentation and no file that put them together (#333). The new choice writes a Node app with no bundler and no build step: server.js (about sixty lines: @zubra/actions' handler, @zubra/server's, then the page, rendered and finished by one zubra.page()), the same example components as the other starters rendered on the server, and guest-book.zb, a form whose action is a 'use server' function with a list that starts from what the server rendered and follows the function's answer. Its test starts the server and uses the page in Chromium with JavaScript and with it off. It has its own README.md and AGENTS.md (rendering a page, a function on the server, what renders where) and ships the zubra-server skill beside the other two; --typescript works as for the others. The docs follow: The starter app has a section for it, the tutorial's server chapters point to it, and docs/actions.md gains "Showing what changed", the list-after-a-post pattern.
  • npm create zubra writes a starter page you can learn from, and an AGENTS.md that explains the app. The app it wrote had one component on a bare page. Its first page is now a welcome, the counter bound to the framework's own state, and four example cards, each a live component with the lines it turns on and the file it lives in: todo-list.zb (a keyed list, conditions, input, mutating state), rating-input.zb (a form-associated control in a real form), async-tip.zb (resource() and <zb-await>) and example-card.zb (slots), put together by zubra-examples.zb (components using components). Every template has the same page, in its framework's own entry file, with one shared src/style.css whose colours are custom properties the components read, dark scheme included. The app's AGENTS.md went from a pointer to the two skills to the app on one page: commands, where things are, what each example shows, a whole component with its parts labelled, using one from the page, the mistakes that cost time, and what to delete when the page becomes yours. Its browser test now uses each example as well as the counter, in all nine templates. With --typescript the counter is still the TypeScript one, and npm run check type-checks all seven. The docs have a page for it (The starter app). In the app's README.md and AGENTS.md, the template with no framework is called "plain HTML and JavaScript" (it read "A No framework app").
  • npm refuses a compiler that is ahead of the runtime. @zubra/compiler now has an optional peer dependency on @zubra/runtime >= its own version. Compiled output is for its compiler's release, and a runtime runs what older compilers wrote, never what a later one writes; npm allowed the bad pair, and an app that pinned @zubra/runtime and @zubra/server got the latest compiler and pages where no element started (#324). With the peer, npm install @zubra/runtime@<older> @zubra/compiler@<this> stops with ERESOLVE and names both, where it used to succeed; the same release, or a runtime ahead of the compiler, installs as before. The peer is optional, so the compiler alone (zubra compile, zubra check, a server in another language) still installs no runtime. scripts/bump-version.sh moves the range with each release. An app that depends on a compiler ahead of its runtime on purpose can't install that way any more (--legacy-peer-deps aside); none of Zubra's own packages or examples do.
  • @zubra/server says when a page was finished by a different page object than rendered it. zubra.page() collects the components it renders, and finish() adds the CSS and modules of those. Rendering with one object and finishing with another (zubra.page().render(…) in one helper, zubra.page().finish(…) in the next), or rendering with zubra.render(), left the second object knowing of none: the page showed the server's HTML and no element ever started, with nothing said on the server or in the console. In development finish(), stream() and streamResponse() now name each such tag, once, with what to do (one zubra.page() per request). The same check finds a component whose template uses a sibling's tag without importing it (<price-tag> in menu-row.zb with no import './price-tag.zb'): the compiler takes such a tag for someone else's element, so the server left it empty and nothing loaded its module, also without a word. The warning names that cause too, with the import to add. A tag one of the page's own components imports, a tag whose module the page loads itself, and a tag in a comment or a script are left alone; nothing is read in production, and no page's HTML changes. Found on Potomac Solutions' comparison slice.
  • @zubra/sync/connect loads webrtc.js only for a page that asks for it (connect({ webrtc })). It was imported by every connected page, peer-to-peer or not: 2.2 KB gzipped on a page that only reads. A page with webrtc loads it while its first pull runs, and its live stream (which brings the peers and their signals) opens once it's there, so peers connect as before.
  • In development, @zubra/server shows an edit on the next request, with no restart. cache is on by default, so a component was compiled once and an edited .zb file showed only after the server was restarted; the way out, cache: false, compiles on every request, and until this release was documented only in the source (#331). With cache on and not in production, the server now looks at the components folder before it uses anything it kept (each file's time and size, once per request), and when a file there was written, added or removed it reads the list of components again and lets go of what it compiled and rendered. A page that hasn't changed still costs what cache makes it cost. Development also serves modules cache-control: no-cache, as cache: false does, or the browser would keep the old module for an hour. Production is untouched: it compiles once, never reads the folder again, and serves max-age=3600; cache: false is as it was. Not watched: a file a component imports from outside the folder, a package's components, and @zubra/router's list of routes (a new page still needs a restart).
  • @zubra/server sends @zubra/sync minified in production. It sent sync's source, comments and all, beside the runtime's minified production build. @zubra/sync now has one too (dist/production, its browser modules minified by npm run build, checked current by its tests), and @zubra/server sends it in production, as it does the runtime's. A read-only menu page: connect.js 5.38 to 2.55 KB gzipped, index.js 5.02 to 2.37 KB; with webrtc.js left out (above), sync goes from 12.56 KB in three files to 4.92 KB in two. Development and bundlers are unchanged. In production /_zubra/sync/ serves those browser modules only (it also served sync's other source files, server.js among them, which no page imports).
  • A hydration mismatch says where. zubra: <checkout-form>'s markup doesn't match its template; rendering it fresh named the element and nothing else, and the element has one template and many parts. In the development build a second warning now follows it with the first difference: the two top-level shapes (zubra: where <menu-item>'s markup doesn't match its template: the template's top level is <h3> <p> <form>, and the markup's is <p> <form>), or the first binding whose place in the markup holds something else, with what the template expects, the elements on the way to it, the position, and what is there (the template expects a zb-if region in <menu-item> › <p>, at position 2, and the markup has <span>; … an element (for its disabled binding) in <menu-item> › <form>, at position 3, and the markup has nothing). Only shape can mismatch (a different attribute value or text is written, not refused), so that is all there is to say. The explanation is a module of its own (mismatch.js), loaded only when a mismatch happens and left out of the production build, which is byte for byte the same; the development build is 85 B larger compressed, within its budget. The first warning, and what is taken over or rendered fresh, are as before. Found on Potomac Solutions' Counter, whose checkout page logged the bare line (#320).
  • @zubra/sync's server says, in development, when a page was refused every read of a collection. A page isn't told what it may not read, so a collection that authorize refuses, or the server's scope leaves out, looked exactly like an empty one: the components showed their defaults for good, with nothing in the page's console, no failed request and nothing on the server (a refused write, by contrast, is a 403 that says why). The server now logs once per collection when a page read the whole log, by /pull or /live, and was sent none of a collection that has documents, naming the collection, the request and which of the two refused (#328). The page is told nothing more than before. createSyncServer({ warn }) is new: a function to send the message elsewhere, or false. By default it's console.warn where process.env.NODE_ENV exists and isn't production, and nothing elsewhere (a Worker has no such variable, and stays silent). Nothing is said for a collection the page's own scope leaves out, one the page sees part of, or later batches.
  • Lists are created with about a fifth less script time. Three changes in @zubra/runtime, none to compiled output: a zb-each row's bound nodes are found by the places they had in the template's first copy, not by walking each copy for markers (rows with a custom element inside are found as before); a row that is one element is a copy of that element, with no fragment around it; and a list watches its array through one signal for "an item or the length changed", in place of one signal per index. A property read through reactive state that nothing is tracking (an event handler, a loop outside an effect) no longer makes a signal for that property. On the js-framework-benchmark's operations, script time in Chromium (CPU profile, 30 cycles, three runs): create then clear 1,000 rows 34.9 to 27.6 ms, replace 1,000 rows 70.6 to 55.0 ms, create, append 1,000 and clear 74.2 to 60.7 ms (Solid: 13.6, 25.9 and 27.5 ms on the same machine). The runtime is about 230 B larger compressed.
  • Server rendering a list does about an eighth less work. A zb-each over a list that outlives the render (a prop, a script value, or a field of a row of one) reads its rows where they are and lends them to their scopes; before, the list was copied for every pass over it, so a table's columns was copied once per row. The response is written straight to a string, and an element's name is no longer copied to check for <select> and <textarea>. Same HTML: all 277 .zb files in the repository render to the same bytes. Instructions per render of the comparison's table, native: 22.3M to 19.6M for 100 orders (0.88), 0.91 for 3 orders; about 3.1 to 2.5 ms a render on the machine it was measured on.
  • zubra check takes a folder. zubra check components answered components: unable to read source: Is a directory (os error 21), though zubra fmt and zubra check --types both take one (#334). A folder is now every .zb, .zb.jsx and .zb.tsx under it, by the rules fmt walks by (no node_modules, dist, target or hidden folder), alone or beside files, in the Rust CLI and in @zubra/compiler's. --format json is as for files named one by one: one entry per finding, each with its file. A folder with no component in it is an error that says so, not "checked 0 files". A file argument, and --stdin, are as they were.
  • @zubra/router says whose load threw. A load that throws was logged as the bare error, whose stack names only the generated server half (node_modules/.cache/zubra-router/boom-page.route.mjs:9): not the request, not the route, not the .zb file, and not that file's line. onError now gets a third argument, about: { route, component, file }, the route answered and, for a load, the component it's in and its file (both null when the page failed to render). The default handler logs @zubra/router: GET /boom/7: the load in components/boom-page.zb threw (the browser got a 500 without the message): and then the error, as before. An onError(error, request) an app already has is called as it was. The line numbers are still the generated file's.
  • The production runtime is about 145 B smaller, with nothing changed in what it does. Its build now gives short names to fields of objects that never leave their module: the signal graph's nodes and an effect owner's internals (PRIVATE in runtime/scripts/build-production.js). Minifying alone shortens variables and keeps every property's name. The unit tests, the comparison with signal-polyfill among them, now also run against dist/production itself. @zubra/server's zubra.js goes from 14,355 to 14,211 B and dist/production/index.js from 16,211 to 16,062 B, so both budgets go back down 0.25 KB; the comparison's six components with the runtime, 14,574 to 14,429 B.
  • Two errors say more. A prop a component doesn't have (page.render('slice-item', { 'left-now': 3 }), --props) was reported at line 1, column 1 of the file, which is a comment as often as not; it now points at the host tag, where the props are declared, with the same message and the same did you mean. And @zubra/server's no component "slice-itm" in … listed every component in the folder and suggested none: when a name is within two edits it now says did you mean "slice-item"? before the list, which is still there (#335). No message lost any text a tool could be matching.
  • A component carries the code for window listeners, class lists and toggles, style properties, URL checks and shadow DOM only if it uses them. Every element had what <zb-window>/<zb-document> listeners, class={…} beside class: toggles, class:name, style:property, the href/src/srcset URL checks and a shadow root need; now the output that has one names it (binder: $global, $classes, $toggle, $style; url: $url, srcset: $srcset; shadowing: $shadow), from parts.js and shadow.js. Same behaviour, the same checks on the same attributes: the compiler decided where a URL is checked before, and the part now carries the check itself. Found by running the comparison's host tests under V8 coverage and leaving each never-run piece out of a minified build. Its hosts: Svelte 25.84 to 25.40 KB, React 83.51 to 83.05, Vue 39.48 to 39.06, Angular 51.06 to 50.64 (each whole entry chunk, framework included). @zubra/server's core has them all, 60 B more (zubra.js 14.30 to 14.36 KB). adoptStyles is exported as before. This is part of interface 5 with the entry below, so the two ship together.
  • @zubra/server says when the installed @zubra/compiler is a later release than @zubra/runtime. A module is compiled for its compiler's release, and a later compiler can write an import the older runtime doesn't have: 5.19.0's output imports @zubra/runtime/hydrate, which 5.18.0 has no file for and its server doesn't map. The page still showed its server HTML, so nothing looked wrong on the server; in the browser no module loaded, no element started, and the one sign was Failed to resolve module specifier "@zubra/runtime/hydrate". npm installs that pair without a word, since the peer ranges are ^: pin @zubra/runtime and @zubra/server to 5.18.0 and the compiler still resolves to 5.19.0. createZubra() now warns once when it starts, with both versions and the install that puts them on one release. An older compiler says nothing (the runtime runs every interface from 2), and nothing else changes. Found on Potomac Solutions' upgrade drill, where this is why the slice failed both live-update tests "on 5.18.0": no prop's behaviour changed between the two releases, and with all three packages on 5.18.0 the slice passes.
  • The compiler warns about a child tag that was probably meant to be a component. A hyphenated tag the script doesn't import is an unknown element, and has to be allowed: it may be another library's. But two mistakes ended there with nothing said by the compiler, zubra check, the server or the browser: a sibling component used without its import (the tag stays empty on the server, nothing loads its module, and every check of its props is off), and a misspelt tag (#327). Both are now warnings, once per tag: <price-tag> is the component in \./price-tag.zb`, which this file doesn't importwith the import to add, when a component file of the tag's name sits beside this one; and isn't a component this file imports, and is close to one that is: when the tag is one edit from an imported component's (two for tags of eight letters or more). Another library's element, the component's own tag and the template's own elements say nothing, and nothing in this repository's components, examples or registry trips either. They are warnings, so no build fails; where the compiler is given only a component's own imports (@zubra/server`), the first can't be seen, and the server's own development warning covers it.

Fixed#

  • A named slot passed on to a component of your own shows its content. <named-relay><frame-box><zb-slot name="y"></zb-slot></frame-box></named-relay>: content given for y keeps its slot="y", its name in <named-relay>, and <frame-box> routed it by that, had no slot y, and kept it out of sight, in a fresh render and in plain HTML alike; a component filling y failed to compile (<named-relay> has no slot named 'y'). A slot right inside a light-DOM child's tag now says which of the child's slots it sits in (forward: "default" on its part), and puts that on each node it shows (under Symbol.for('zubra.forward'), naming the child, so --emit element output reads it too). The child routes the content there; every other host, <named-relay> included, still goes by the slot attribute, so changing it moves the content as before. The server already put such content in the child's default slot, and a parent's content hydrates there now. The development runtime is about 60 B larger compressed, the production build's bundle 2 B. (#323)
  • A component compiled by 5.19.0 or earlier starts again on this release's @zubra/server. Those compilers' output takes $element (interface 4) or $define (2 and 3) from @zubra/runtime itself, and the server maps that name to the runtime's core (core.js, or zubra.js in production), which stopped exporting both when they moved to legacy.js. So an app that updated @zubra/server and @zubra/runtime and kept its compiler got The requested module '@zubra/runtime' does not provide an export named '$element': no element of the page started, in development and in production alike, with the server HTML looking right. The server now sends that one name of an older module to legacy.js, beside the core, and leaves the rest of its import alone; a page of current components is byte for byte what it was and doesn't load legacy.js. Tested with the 5.18.0 output kept for the runtime's own tests, in a browser with the runtime file by file and as one file. Found on Potomac Solutions' Counter slice, which lost all twelve of its live updates (#346).
  • A component that fills a child's slot takes over its server markup whichever branch the child rendered. A child may put a slot in more than one branch of a zb-if at different places (Zubra UI's action-button: first in its link, after a spinner in its button). Content given to that slot was located by the first branch's place, so when the server rendered another branch the whole parent was rendered fresh instead of taken over (in development with <…>'s markup doesn't match its template; silently in production). Where a place is in doubt (a slot in more than one branch, or another slot at the same place in another branch), the parent's part lists each place with what its steps lead to in that branch (hydrate: [{ path, kinds }, …]: for each step it checks, the element's tag, a region or a filled slot), and the runtime takes the one the markup matches. Content for a slot whose place another slot has by the same steps isn't bound to that slot's nodes any more: the element renders fresh, as nothing in the markup says which the server rendered. A component that passes its default slot on to a component of its own (<frame-box><zb-slot></zb-slot></frame-box>) can be given content: a parent used to fail to compile (has no slot named 'default'), and the content now sits, and hydrates, where the inner component put it. Found on Potomac Solutions' Counter, whose <checkout-form> (the kit's) was re-rendered on every checkout. Part of interface 5; a part with one place is written as before.
  • A component a layout and its page both import is rendered once. @zubra/router renders the page, then gives that HTML to its layout's slot; a tag in it that the layout imports too (<my-button> in app.zb and in home-page.zb) was expanded a second time inside its own rendered markup: a <button> in a <button>, data-zb-filled written twice, and the axe failures that come with them. The same with error.zb, or a page put there by show(). Slot content given as HTML a server already rendered (slotSource: 'html', --slots-html, page.render()'s slots) is kept as written, as documented: no tag in it is expanded as the component's child, at any depth. To put a component in a slot, pass its rendered HTML (page.render('price-tag', props)). (#300)
  • A load that throws is reported at its line of the .zb file. The error's stack names the generated server half in the cache at the half's own line (boom-page.route.mjs:9 for line 5 of boom-page.zb), which is nowhere a person edits (#330). The compiler can now end a server half with a source map of its functions' lines to the component's (emit: 'server' with sourceMap: true on the request API; a function's text is the source's own, TypeScript included, so it's one entry a line), and @zubra/router asks for it. onError's about gains line, the line of about.file where the load threw, and the default log says it: @zubra/router: GET /boom/7: the load in components/boom-page.zb threw, at line 5. The map names the component by its address, so node --enable-source-maps makes the stack itself say boom-page.zb:5. zubra compile --emit server and @zubra/actions' halves are unchanged (no map unless asked), a compiler that doesn't know sourceMap is used as before, and a thrown value with no stack has line: null.
  • A property set before the element is defined wins over the server's attribute for it. The constructor takes over a property a page script or framework set before the module loaded, but the upgrade then replays the attributes already on the tag, and @zubra/server writes a prop's attribute whenever the value isn't the default (left-now="5"). The older attribute was applied last and the newer property was lost, with no warning: a page script's first update from an event stream, arriving before the modules, disappeared until the next one. The replay is now skipped for a prop taken over that way; an attribute set after the upgrade still applies, and so does the attribute when nothing was set early. The same in --emit element output, whose constructor takes such properties over too. (#326)
  • A component that fills a child's slot takes over its server markup whichever branch the child rendered. A child may put a slot in more than one branch of a zb-if at different places (Zubra UI's action-button: first in its link, after a spinner in its button). Content given to that slot was located by the first branch's place, so when the server rendered another branch the whole parent was rendered fresh instead of taken over (in development with <…>'s markup doesn't match its template; silently in production). Where a place is in doubt (a slot in more than one branch, or another slot at the same place in another branch), the parent's part lists each place with what its steps lead to in that branch (hydrate: [{ path, kinds }, …]: for each step it checks, the element's tag, a region or a filled slot), and the runtime takes the one the markup matches. Content for a slot whose place another slot has by the same steps isn't bound to that slot's nodes any more: the element renders fresh, as nothing in the markup says which the server rendered. A component that passes its default slot on to a component of its own (<frame-box><zb-slot></zb-slot></frame-box>) can be given content: a parent used to fail to compile (has no slot named 'default'), and the content now sits, and hydrates, where the inner component put it. (A named slot passed on still can't be: its content keeps its slot attribute, which the inner component routes by.) Found on Potomac Solutions' Counter, whose <checkout-form> (the kit's) was re-rendered on every checkout. Part of interface 5; a part with one place is written as before.
  • A component compiled by 5.18 keeps its event modifiers, form association and hydration on this runtime. 5.19.0 moved those out of every element: a component compiled by 5.19.0 names them (binder: $modified, forming: $form, hydrating: $hydrate), but one compiled by 5.18 said the same interface (abi: 4) without naming them, so on 5.19.0's runtime its key filters and .prevent did nothing, it wasn't form-associated, and it rendered over its server markup instead of taking it over. Apps compile their components with the runtime they ship, so this reached only components compiled ahead of time by 5.18 (a library built with zubra build --lib, say). Compiled output is now interface 5 (abi: 5, calling the runtime's $component); interface 4 output calls $element, which now fills in what it doesn't name, as $define does for interfaces 2 and 3, and a component compiled by 5.18.0 is checked in and tested beside the current output (since-4.test.js). The runtime still runs every interface from 2. A module compiled by 5.19.1 needs a runtime of 5.19.1 or later, as each new interface does.

5.19.0 — 2026-11-15#

Installing: keep @zubra/compiler, @zubra/runtime and @zubra/server on one release. A component compiled by 5.19.0 imports @zubra/runtime/hydrate (see "Added" below), which only 5.19.0's runtime has, so a 5.19.0 compiler beside a 5.18.0 runtime and server gives pages where no element starts (the browser's console says Failed to resolve module specifier "@zubra/runtime/hydrate"). npm allows that pair: @zubra/server's peer range for the compiler is ^, so pinning the runtime and the server alone leaves the compiler on the latest. No prop, attribute or from() behaves differently in 5.19.0 than in 5.18.0.

Security#

What the second 2026-11-15 security audit found, most of it in @zubra/router (new in 5.17.0), beyond what 5.18.0 fixed.

  • A layout's load guards every page under its prefix, however the page spells it. Layouts were chosen by comparing pattern text, so a page under 'use layout /org/:org' written as /org/:orgId/invoices, with a regex parameter, or reached by a catch-all route (routes/docs/[...path].zb under a guarded routes/docs/private/) skipped the layout's check. They are now matched against the path asked for, and the layout's load gets its own params. A root layout's pages still run the loads of the layouts over it (they are only not drawn inside them).
  • The router routes only what req.url says. A path starting // is no route (the URLPattern polyfill read //evil/staff/report as host evil and path /staff/report, past an app's own guard on /staff), and handle() answers a target that isn't a path (http://evil/staff, *) with 400 (5.18.0 already refuses a Host that isn't a host). @zubra/server's handle() leaves //host/… to the app.
  • redirect() stays on the site. //elsewhere is read as the path /elsewhere, and another origin or a non-http(s) URL is a 500 unless redirect(to, { external: true }) says it means to leave, and never a script URL. A page whose loads ran is sent Cache-Control: private, no-store; a HEAD no longer uses up an action's one-use result; two components' server halves can no longer share one cache file (a/b.zb and a__b.zb), in the router or in Actions.
  • Server code can't read the script's own values, and a shadowing name no longer ships a server import. A load or 'use server' function reading a top-level binding of the script (const API_KEY = …) is a compile error: the value was sent to every visitor in the browser module, and undefined on the server. Which code uses an import is now decided by what its references resolve to, so a browser function's parameter named like a server-only import no longer keeps import { db } from './db.server.js' in the browser module.
  • SyncObject passes every option to the sync server. It passed five, so a scope set in static options was dropped without a word and every tenant read every other's documents (maxBytes, maxChanges and maxSkew went the same way). An option it doesn't know is now an error.
  • A dropped live stream's peer id waits 60 seconds for its own key, in @zubra/sync and zubra-sync: whoever asked first in the gap took the id, and with it the signals sent to it. A field can't be named like what every object has (__proto__, constructor, toString…); __proto__ set a document's prototype. A live page's read is asked of authorize once per document in a batch, not once per change.
  • A spread never sets an animation's values or a <meta>'s http-equiv. <set {...anim}> could animate a link to javascript: from a visitor's data, which a click ran, on the server and in the browser. Interpolating a <meta http-equiv>'s content, or http-equiv itself, is a compile error: a refresh there redirects anywhere.
  • injectShadowRoots fills only host tags the browser would see. A host's name in another tag's attribute value (Solid and Svelte leave < unescaped there), a comment, a script or a textarea was filled too, and the template's own quotes then closed the value: a visitor's text became markup. It now reads tags as the browser does, streamed pages included.
  • Over HTTPS, result() reads only __Host-zb_result: the plain cookie can be planted by a sibling subdomain.
  • A spread leaves out what it can't set, instead of failing the render. A visitor's stored onclick, innerHTML or srcdoc in a spread object was a compile error at render on the server, so it failed every page spreading it; it is left out with a warning now, as the runtime does. ping is refused in spreads, and interpolating it is a compile error: a click posts to every URL it lists, with the visitor's cookies when they are the site's own.
  • A Sync tab whose peer id was taken while it was away takes a new one and says its presence again, instead of retrying the taken id forever.
  • createActions({ secure: true }) for an app behind a proxy that ends TLS: the result cookie is __Host- and Secure, and a planted plain one is not read, though requests arrive as http.
  • Lower: hydration markers at the top of slot HTML are left out (a visitor's <!--]--> made what followed vanish on hydrating); the language server uses a zubra checkout's own build only with ZUBRA_DEV_CHECKOUT set (any repository can say it is zubra).

Added#

  • hydrate: false in @zubra/unplugin, for an app whose pages are never rendered on a server. Taking over server markup (telling it from the page's own children, finding the parts in it, putting back markers a sanitizer stripped) moved out of every element into hydrate.js; compiled components import it (hydrating: $hydrate, from @zubra/runtime) unless compiled with --client-only (clientOnly in @zubra/compiler), which is what hydrate: false asks for in browser builds (server builds keep it). Such an element renders fresh over any children it starts with, as the page's own. The comparison's hosts built that way: Svelte, Vue and Angular about 1.0 KB smaller, React 0.4 KB, and the on-demand marker repair chunk (1.2 KB) is gone; all 24 host checks pass. The default costs about 0.08 KB in @zubra/server's zubra.js (14.17 to 14.25 KB), which every server page loads. Modules compiled by earlier releases get hydration through $define.

Changed#

  • @zubra/server sends the runtime's core as one file in production, with bundle or without. It was one file (runtime/zubra.js) only with bundle: true; by default a page preloaded the core's dozen modules one by one. Now bundle only joins a page's components into one module, and in production the runtime is zubra.js either way (development and the DevTools keep it file by file, as before). The comparison's server page without bundle: 22.1 KB in 16 modules to 17.8 KB in 5 (with bundle, 15.8 KB in 2, as before). writeAssets() writes dist/bundled in production accordingly. A page's import map, preload links and the modules' imports change with it; nothing a page or an app writes does.

  • A component imports the form controls' API only if it's form-associated. The form, validity, checkValidity()… properties, the form callbacks, a model prop's form value and reset, and removing the server's fallback input were in every component's runtime. Now a form-associated component names them (forming: $form, from @zubra/runtime) and others carry none; modules compiled by earlier releases get them through $define. The comparison's six (none form-associated) with the production runtime: 14.91 to 14.65 KB; its hosts with this and the two entries above: Svelte 14.2 to 13.0 KB, React 15.9 to 14.7, Vue 15.2 to 14.0, Angular 14.3 to 13.2. @zubra/server's core (zubra.js, core.js) includes the form controls and event modifiers, as it includes zb-if and zb-each, so a page with a form or a key filter needs no more requests; it's 0.2 KB larger for it than 5.18's.

  • A component imports event modifiers only if it uses one. What .prevent, .stop, .self, .once, .capture, .passive, .submit, the held keys and a key filter (onkeydown.shift.enter) do was in every component's runtime. Now a listener with modifiers names its binder (binder: $modified, from @zubra/runtime; @zubra/server's core has it) and a plain listener is just the handler; modules compiled by earlier releases get the binder through $define. The comparison's six components, none of which use a modifier, with the production runtime: 15.25 to 14.91 KB compressed; with the entry above, its hosts are about 0.9 KB smaller than 5.18.0's (Svelte 14.2 to 13.3 KB, React 15.9 to 15.0).

  • A component built by @zubra/unplugin carries its CSS once. A light-DOM component's stylesheet went into the page through Vite's CSS pipeline and into its module again as text (?inline), for an element inside someone else's shadow root, where page CSS doesn't reach. Now the page's copy is the only one: the module names stylesFromPage: $pageStyles, and for an element in a shadow root the runtime copies that component's rules (its @scope (tag) blocks, in the @layer, @media and @supports they're in) from the page's stylesheets into one sheet, once. A stylesheet the page can't read (another origin's, without CORS) is skipped. The comparison's hosts are each about 0.55 KB smaller: React 15.9 to 15.3 KB, Vue 15.2 to 14.6, Svelte 14.2 to 13.6, Angular 14.3 to 13.8. Shadow-DOM components, and the server's modules, are as before.

5.18.0 — 2026-11-15#

Security#

From a review of what changed since the 2026-11-12 audit (the joined modules, CSS and sources sent once, the render cache, the slot routers, interface 4 and @zubra/router).

  • A Host header that isn't a host is refused by @zubra/router, @zubra/actions (and its exported toRequest) and @zubra/sync's Node handler: a 400. Each built its request's URL from the header and the request line, so a header with a path in it moved the path: Host: site/admin with GET /public was routed as /admin/public, and with a ? or # the request line's path was dropped altogether, so Host: site/_zb/action/two? with POST /_zb/action/one ran two. A proxy or firewall in front that allowed or rate-limited by path saw one path while another was served. It takes a hand-made request (a browser always sends the real host), so it is no cross-site attack. A request with no Host header (HTTP/1.0) is still for localhost; a host, a port, a name with an underscore and an IPv6 address are as before.
  • routeLinks() leaves a link whose path starts with // to the browser. https://site//evil.example/ is a link on this site, but the path it handed the app's router, //evil.example/, is another site's address to a router that takes protocol-relative paths (Next.js's router.push does a full navigation to one), so a link a user could write in a component could leave the site.
  • @zubra/server keeps at most 64 joined modules that only a URL asked for. Any instance builds a page's joined module from its URL, so the names in it are checked but any set of the app's components can be asked for: one with the wrong hash was joined again on every request, and one with the right hash (computable from an open-source app's sources) was kept for good, so asking for set after set grew memory without end. Now each set is joined once and kept among the most recent 64; the sets the server's own pages use are kept as before.

Changed#

  • @zubra/server sends a page only the runtime features its components use. The runtime's core (@zubra/runtime/core, and with bundle: true dist/bundled/zubra.js) is now the runtime with zb-if and zb-each, and without what fewer pages need: zb-await's binder, the slot router and $define for modules compiled by earlier releases, each a file of its own (await.js, slots.js, legacy.js). @zubra/server maps @zubra/runtime to the core and compiles its modules to import the binders from their own entries (binderEntries in a request, zubra compile --binder-entries), which it then writes as @zubra/runtime for zb-if and zb-each (the core has them) and as a path beside the module for the others (../runtime/await.js). So no import map needs new entries: a page whose import map is a framework's own and names only @zubra/runtime loads them, a static site that serves /_zubra/ from elsewhere and rewrites only its pages finds them, and with imports pointing @zubra/runtime at a CDN they come from beside it there. The comparison's server page with bundle: true: 17.3 to 15.6 KB compressed, still in two modules; the bundled runtime 16.0 to 13.6 KB. Without bundle, 21.2 KB in 14 preloaded modules (22.1 KB in 11 before). @zubra/runtime itself still exports everything (index.js is the core, $await, the slots' binders and $define), so bundlers, the plugin and the CLI's default output are unchanged; a page that serves dist/production file by file with its own import map to index.js loads every feature as before, in more files (20.9 KB in 14, from 17.9 KB in 7): map @zubra/runtime to core.js and compile with --binder-entries for what @zubra/server sends.

  • A light-DOM component imports the slot router only if it has slots. What places a framework's or the page's children in a light-DOM component's slots (named slots, page order, stand-ins, frameworks that move content through its parent) was in every component. A component compiled now with light-DOM slots imports it (slotting: $slotted in its definition, $slotted beside the binders); one without slots, whose host shows none of what a framework adds to it, keeps that content in a fragment of its own instead, where the framework still finds it (firstChild, parentNode), and in development says it isn't shown, as before. So an app with no slotted component ships about 1.2 KB less: the comparison's server page's four components with the production runtime 13.99 to 12.80 KB compressed. An app with both kinds has both, about 0.17 KB more (the comparison's six, which include a dialog with a slot: 15.08 to 15.25 KB). Modules compiled by earlier releases get the slot router through $define, as before.

5.17.0 — 2026-11-14#

Added#

  • @zubra/router: components served as pages, for an app with no host framework. A new sibling package, like Actions and Sync: nothing changes for anyone who doesn't install it, and anyone with Next, Nuxt, SvelteKit, Astro or another router keeps it. It came from comparing two apps that had each written the same server routing by hand.
    • Routes. 'use route /farms/:id' at the top of a script (URLPattern syntax), or a bare 'use route' in a routes/ folder, where routes/farms/[id].zb is /farms/:id. One table from both, the more specific path tried first. Two routes for one path are an error naming both files.
    • load. A route or layout may export load({ params, url, request, route, context, result }). It runs on the server before the component renders, and what it returns becomes the props. The compiler leaves it, and the imports only it uses, out of the browser module, as it does a 'use server' function; it isn't an action, so nothing can post to it. A parameter that neither load nor a prop reads is a compile error, and a page's load returning a key that isn't one of its props is a warning. context is createRouter({ context }), the function createActions takes; result is an action's answer after a post without JavaScript (createRouter({ actions })).
    • Answers. Besides props, load can return a title for the document, notFound(), redirect(to), or show(component, props), which renders another component at the same URL: a sign-in form, a "not for you" notice.
    • Layouts. app.zb is the layout around every page; 'use layout /farm' (or routes/farm/layout.zb) wraps the pages under its prefix, nested to any depth, the page in the layout's own <zb-slot>; 'use layout /farm root' starts over there, outside app.zb. A layout's load reaches the pages inside it and answers for its whole section. A layout or page with a route prop is given { path, pattern, params }.
    • Errors. An unknown path, notFound() and a load that throws render inside app.zb (with error.zb in its slot, if the app has one), status 404 or 500; the message never reaches the browser.
    • Serving. const router = await createRouter({ zubra, components }), then await router.handle(req, res) in the app's own server beside zubra.handle and actions.handle, and router.notFound(req, res) last; router.fetch(request) for fetch-style servers. Every page is a whole document and every link a page load: there is no client-side navigation.
    • In core for it: 'use route' and 'use layout' join the directives the compiler knows; --emit server exports a route's route and load; --emit interface has route and slots; @zubra/server refuses to render a route without @zubra/router installed and says what to install; @zubra/actions no longer imports the server half of a component that has no actions. docs/router.md is the reference.

Security#

The lows from the 2026-11-12 security audit.

  • A > inside a quoted attribute no longer ends a host's start tag in injectShadowRoots() (Z10). Svelte and Solid leave > unescaped in attribute values; a value like Ann > Bob lost the host its declarative shadow root and left junk attributes behind.
  • The Actions result cookie is __Host-zb_result and Secure on HTTPS, and only the page the form came from reads it (Z11). A sibling subdomain or a plain-HTTP response could plant a "result" the next page would show; now browsers refuse that, and result() on another path leaves the cookie alone. Also fixed: a post with no Referer went back to <action path>/null; it now goes to /.
  • A backslash counts as a slash in URL checks (Z12): /\evil.example and \\evil.example are other sites to a browser, and the compiler, the runtime and --emit element output now refuse them like //evil.example.
  • SVG <set> and <animate> can't animate a link to an unchecked URL (Z13). Interpolation into their to, from, by or values is a compile error, as in srcdoc, and a literal value animating a URL attribute is checked like that attribute.
  • The language server only runs a target/{debug,release}/zubra inside a Zubra checkout (Z14), so opening a file in another repository can't run a binary it planted. The VS Code extension declares that it waits for a trusted workspace (untrustedWorkspaces: false), since it runs the compiler a workspace installs.
  • A Sync page hears nothing of writes outside its scope (S7). It used to get an empty changes event with the log's cursor for every write anywhere, which told one business when another was busy; the JavaScript server and zubra-sync both skip it now.
  • zubra-sync caps a push at 1000 changes, as @zubra/sync/server's maxChanges does, and @zubra/server no longer caches a 404 for an hour: only a 200 is cached, so a module added in a deploy isn't hidden by a cached 404.

Changed#

  • Components compile to interface 4: a component imports only the binders it uses. A module from zubra compile --emit js, @zubra/unplugin or @zubra/server now imports the runtime's $element (as $define, so the call reads as before and tools that rewrite export default $define( keep working) and, for each kind of block or slot it has, that part's binder: import { $element as $define, $r, $t, $each } from "@zubra/runtime", with binder: $each on the part. A bundler then leaves out the binders an app's components don't use, and $define's fill-in for older modules. The comparison's six components with the production runtime: 15.56 to 15.08 KB compressed (they use zb-if, zb-each and slots, not zb-await). The output needs @zubra/runtime 5.17 or later (an older one has no $element to import); modules compiled by earlier releases still run on 5.17. What the components render, in the browser and on the server, is the same.

  • The runtime reads interface 4. A component compiled for it calls $element in place of $define, and its block and slot parts name their binder (binder: $each, $when, $await, $slot), imported from @zubra/runtime, so a bundler leaves out the binders an app doesn't use. $define reads interfaces 2, 3 and 4 as before and fills in the binder for parts that don't name one; it is the only code that names every binder, so an app whose components are all interface 4 doesn't include it. ABI is 4.

  • The runtime's warnings are in development only. The production build (dist/production, the production export condition a bundler picks for a production build, and what @zubra/server sends in production) no longer has the runtime's console messages: an object rendered as text, an attribute that isn't one of its values or isn't JSON, a boolean attribute given something else, an object written to an attribute, a blocked unsafe URL, a duplicate or non-array zb-each, content for a slot the component doesn't have, an attribute HTML lowercased, and server markup that doesn't match. What the runtime does in each case is the same (the URL is still blocked, the row still unkeyed, the markup rendered fresh); only the message is gone, as with Lit's and Vue's production builds. Errors the runtime throws keep their messages. The production runtime is 0.7 KB smaller for it (14.97 KB compressed, from 15.68), and the comparison's six components with it 16.27 to 15.56 KB.

5.16.0 — 2026-11-14#

Added#

  • npx zubra types: an app's typings without a build (#276). With dts: { dir } the typings are written during a build, so tsc on a fresh checkout (a typecheck job that doesn't build) saw .zb imports loosely typed, and a strict project failed on its handlers. zubra types [file | dir]... [--dir .zubra/types] [--framework react|vue|svelte|solid|none] writes the same files the plugin does, in the same layout with the same tsconfig.json, for the framework in the app's package.json.

  • createZubra({ bundle: true }): the runtime as one file. A page from @zubra/server loaded the runtime's entry and the six modules it imports, each its own request: 18.6 KB compressed one by one. @zubra/runtime now also builds dist/bundled, where those seven are one module, zubra.js (16.0 KB), and with bundle: true a production server maps @zubra/runtime to it, preloads it and serves it, so a page asks for one runtime module. The runtime's other modules (spread, track, motion, primitives, …) import that file in this build, so there is still one signal graph, and each module that went into it is still served by name, re-exporting from it. Off by default in 5.x, and without effect in development or with the DevTools, which read the runtime file by file. At the edge (@zubra/server/edge), serve dist/bundled where dist/production went. @zubra/runtime/modules gains bundled, the same list for this build. With bundle: true a page's components are one module too: /_zubra/b/<names>.<hash>.js holds the components the page ships and the ones they import, each as a block of one module with their other imports merged at the top, so a page asks for two modules (that one and the runtime) where the comparison's server page asked for eleven (22.5 KB compressed to 18.6 KB). The names in the URL are the set, sorted, so pages with the same components share it and any instance of the server can build it from the URL; the hash is of the module, and it is served immutable. zubra.writeAssets() writes the ones the rendered pages use. The compiler does the joining (command: "join" in a request) and renames nothing, so it answers that a set stays apart, with the reason, where joining could change what a module sees: two components import different things under one name, one reads a global another imports something as, one takes a binding from another, uses import.meta, a relative or computed import(), or a top-level var. Such a set is served module by module as before, with a warning that says why; so are a single component and a set whose names don't fit a URL (160 characters). One difference to know: the modules the components import from outside the set are now all loaded before any component runs. And the page's CSS is sent once: the head's <style data-zb-components> (or each stylesheet link) names the components whose CSS it has, and in a joined module a light-DOM component has its stylesheet's address (stylesHref) where it had the CSS text a second time. The runtime adopts nothing where the page names the component; for an element inside a shadow root, or on a page that doesn't name it (a fragment swapped into another page), it fetches the stylesheet once, so a Content-Security-Policy has to let the page fetch from its own origin (connect-src 'self') for those two cases. A set with a shadow-DOM component in it keeps the text in every module. With that the comparison's page is 18.1 KB. The runtime is 89 bytes larger for it (16.1 KB as one file).

Changed#

  • A component's sources go to the compiler once. Every request @zubra/server made (a render, a module, a description) carried the component's source and those of the components it imports, and the compiler read them each time: parsed them out of the request, copied each file, checked that the component it had parsed still matched, and worked out its warnings again. The compiler now keeps a set of files under a handle (command: "load" in a request, then "loaded": "<handle>" in place of "files"), and keeps with the set what it works out from it; the server loads a component's sources the first time it needs them and names the handle after that. The answers are the same: every component in the repository gives the same HTML, module, CSS and interface either way. Counted in instructions on the comparison's components, a render of the badge is 28% less, the field 25%, the quantity control 20%, the table with 3 orders 8%; with 100 orders the rendering is nearly all of it and nothing changes. The handle is a hash of the files, so a compiler that doesn't have it (a new instance after a crash, or one that let the set go past 64 MB of sources) says so and is sent the files again; a compiler that keeps nothing between requests (the native CLI answering one request per process, or an older @zubra/compiler) gets the files with every request as before, after one try. Without cache nothing changes: sources are read and sent for every request. The render benchmark (benchmarks/server-render.mjs) now sends what the server sends: each component with only the components it imports, loaded once where the build can.

  • A template's names are resolved once. Every render checked that each name in the component's template is one in scope (a prop, or something the script declares), branches that aren't rendered included. Whether they resolve depends on the template and on which names are in scope, not on their values, so a parsed component now remembers the names it passed with and isn't checked against the same ones again. An unknown name is the same error it was, on every render. On top of the entry above, counted in instructions: the quantity control 12% less, the field 10%, the table with 3 orders 4%.

Fixed#

  • In Vue, a bare attribute sets a boolean prop. <Field required> in a Vue template reached the component as '', as Vue passes it without a declared type, so required was not true and the element logged that it had been given a string. The Vue adapter now reads '' as true for a prop whose default is a boolean, as HTML reads the attribute; a string prop given '' is still ''. Found by the comparison (docs/compared/coexist), whose Vue host writes :required="true" until it moves to a release with this.

5.15.0 — 2026-11-14#

Slots hold up in Vue, Svelte and Solid, a component can say its props' and events' types in its description, and the server renders the same thing once.

Added#

  • @prop {Type} name and @fires {Type} name in the description: a prop's and an event's type, said in the component (#270). A prop's type came from its default's shape, so card={{ kind: "pip", suit: "spades", rank: 14 }} was typed { kind: string; suit: string; rank: number }, wrong for a component that also draws jokers: every use with the app's own Card type was an error in React. An event fired with different values, or with a variable, was CustomEvent<unknown>. <script lang="ts"> could already say both (declare const card: Card, emit<Bid>('bid', n)); a plain <script>, and an emit in a template, could not. Now the description comment can: @prop {{ kind: "pip"; rank: number } | { kind: "joker" }} card - The card to draw. types card in the typings (the element, the props interface, the React, Vue, Svelte and Solid ones), the manifest and the type check, and its text becomes the prop's description there and in editors' completions; @fires {number | "nil"} bid - A bid. types the event's detail (the type may also follow the name). Between the braces goes one TypeScript type, which may name a type the component's TypeScript script declares. @prop name - text, without a type, documents the prop and leaves its type to the default; @prop lines no longer appear in the component's own description. Errors, each naming what to change: a @prop for a prop the host tag doesn't have (with a suggestion), the same prop twice, a prop typed here and in the script, braces that hold no type or are never closed.

  • @zubra/server renders the same thing once. A component's HTML is a function of its sources and what it is rendered with, since the server evaluates only what is deterministic. With cache on (the default), a render asked for again with the same props, slots, provided context and place on the page is answered from the last one: a page's navigation, its forms, a list that hasn't changed. The most recently used renders are kept, within 500 of them and 8 MB of HTML; one answer over 512 KB isn't kept, nor is a component given a promise prop. A render's warnings (a URL left out) are said again each time. On the comparison's server page (docs/compared/coexist/measure.mjs), where the form's two controls are the same on every request: 411 µs a page with new orders each time, from 641; and 23 µs where the whole page is the same again, from 534. Rendering something new costs what it did: the table with 100 new orders is 5.6 ms. cache: false renders every time, as before.

  • @zubra/server preloads a page's modules. A page's modules load in levels: its components, the runtime's entry they import, the entry's modules, and theirs. The browser found each level by fetching and parsing the one before, a round trip per level. page.head() (so finish() and stream()) now writes a <link rel="modulepreload"> for every module the page's components load: the components, the components and plain modules they import, and the runtime's modules, each once, after the import map. The browser fetches them together. Measured on the comparison's server page (four components, eleven modules; Chromium, 150 ms latency, 1.6 Mbit/s): the elements are defined 760 ms after navigation, where they took 1,108 (docs/compared/coexist/measure.mjs, median of five loads). The links carry the page's nonce, follow the stylesheets under inline: false, and leave out a component clientModules: 'needed' gives no module. The runtime's own modules come from a list it now ships, @zubra/runtime/modules (each production module's static imports, written by its build), so a page is the same on Node and on @zubra/server/edge, where the host serves the runtime and the server can't read it. createZubra({ preload: false }) turns it off.

  • @zubra/server runs under a Content-Security-Policy without 'unsafe-inline' (#216). page.finish() wrote an inline <style>, an import map and an inline module script, and such a policy refuses all three. Two ways, for two kinds of site:

    • zubra.page({ nonce }), where each response has a nonce: it goes on every inline <style> and <script> the page writes, a streamed prop's scripts included. zubra.head(names, { nonce }), zubra.scripts(names, { nonce }) and zubra.importMap({ nonce }) take it too. A value that isn't base64 is refused.
    • createZubra({ inline: false }), for a static site: a <link rel="stylesheet"> per component (/_zubra/components/<name>.css, served by handle()/fetch() and written by writeAssets()), each module a <script type="module" src>, and no import map. The modules are served and written with their imports of @zubra/runtime, @zubra/sync and imports resolved to what the map would have said, a component's plain .js modules and the runtime's and Sync's own files included. A prop given as a promise still needs the nonce. @zubra/server/edge takes both options.
    • Not covered: what a component's own markup has inline. A shadow-DOM component's declarative shadow root carries its <style>, so under style-src 'self' it is styled once its element starts, not before; style: bindings are inline styles.
  • @zubra/unplugin: dts: { dir }, typings in the app instead of beside the components (#263). The typings beside a component are for one framework, so when apps in different frameworks built one shared components folder, the last build to run decided what every app's tsc read. zubra({ dts: { dir: '.zubra/types' } }) writes them under that folder of the app, mirroring the root (a component above the root goes under a __ per folder up), with a tsconfig.json there to extend: it sets allowArbitraryExtensions and the rootDirs that pair each mirrored folder with the real one, so imports stay as written. A .d.zb.ts still beside a component is read first by TypeScript, so the build warns about it. The default is unchanged.

Changed#

  • The React and Vue adapters are smaller in an app. A .zb import in a .jsx or .vue file brought the adapter's server half (server.js, which only runs where there is no window) and the <zb-context> element (which only a ZubraContext uses) into every browser bundle. The server half now registers itself where a server build loads it, and the adapters reach it there; <zb-context> is defined when a ZubraContext is first rendered, and Vue's ZubraContext is a plain options object, so a bundler drops both from an app that provides no context. On the comparison's order desk (six components, docs/compared/coexist/measure.mjs): what the components add to the React host goes from 17.0 to 16.2 KB gzip, and to the Vue host from 16.4 to 15.6 KB. Server rendering through the adapters is unchanged. One thing to know: <zb-context> written as a bare tag in JSX or a Vue template (not through ZubraContext) needs import '@zubra/runtime/context', as in the other frameworks; importing the adapter no longer defines it.

  • Server rendering does less work per request. Three things the compiler repeated on every render, found by profiling the comparison's table (docs/compared/coexist): it copied the component's whole parsed tree out of its cache, twice (once for the warnings, once to render); it parsed each script expression again every time it evaluated it, a cell's once per row; and reading row.total or row[column.key] in a template copied the row first. The tree is now shared, parsed expressions are kept (up to 4,096 of them and 1 MB of source, in an arena that isn't freed, so past that an expression is parsed where it is used), and a path is read where the value is. The HTML is the same byte for byte: all 248 components in the repository render identically before and after. Measured on a native build, in instructions per render, which doesn't move with the machine: the table with 3 orders 28% fewer, with 100 orders 26% fewer, a form field 21% fewer. No API changes.

  • Server rendering copies less. A second pass over the same profile, after the trims above. A script expression that reads a path (order.lines[at].kg, row[column.key]) reads it where the value is instead of copying order to take one field from it; a child component's interface is worked out once for its parsed tree, where it was worked out for every use on every render (a badge in each of a table's rows); a request's props and slots go to the renderer as they were parsed, where they were written out as text and parsed a second time; an element in a list is added to the output directly, not through a list of its own; and an item of a zb-each moves into its scope where it was copied. The HTML is byte-for-byte what it was for every component in the repository. Counted in instructions on the comparison's table, a render with 100 orders goes from 28.1M to 22.5M and one with 3 from 1.50M to 1.22M (a fifth less); a field or a quantity stepper, about 5% less.

Fixed#

  • A child that looks like the component's own root is the page's content (#267). <status-badge><span>hi</span></status-badge>, where the badge's template is a <span> around its slot, has the shape of the badge's server markup with its hydration markers stripped, so the element took the page's <span> for its own root: it got the badge's class, and its text became the slot's content. Where the text arrived a moment later (Angular's {{ }} inside @for) it was lost. Shape can't tell the two apart, so the server now says which it is: it writes data-zb-filled on every light-DOM host that has slots, naming the slots it filled (a bare attribute for none; until now only for a slot hasSlot() asked about), and markup without markers is put back by structure only on a host that has it. Anything else is the page's own children, slotted. Recovery also reads the attribute for each slot, so content that happens to read like a slot's fallback stays content. Two things to know: server HTML gains that attribute on such hosts, and stripped markup from an earlier @zubra/server or zubra compile, which doesn't have it, is slotted as page content by this runtime, so render with the same version (markup that kept its markers hydrates as before).
  • Solid: signal text as a light-DOM component's direct child updates (#268). <status-badge>{count()}</status-badge> showed its first value for good: Solid updates a lone text child in place, parent.firstChild.data = value, and the host's first child was the component's own markup, so the new text landed on the host beside it. host.firstChild is now the page's first child (the text node, wherever its slot put it), and null when the page gave none. The loop while (el.firstChild) el.removeChild(el.firstChild) empties the slots and leaves the component's markup, where it used to remove that. In @zubra/runtime and in --emit element output.
  • Vue, Svelte, Solid: elements in a named slot go when the framework removes the block they are in (#269). {#if more}<span>…</span><action-button slot="actions">…{/if} (and v-if on a <template>, and <Show>): turning it off removed the <span> and left the buttons. These frameworks remove a block as a run of siblings, and an element moved to another slot isn't among them. In Svelte the walk, looking for a last node that had moved, ran on to the end of the parent and took its own anchor and the slot's closing marker with it, so the block never came back. The default slot now keeps a stand-in, a <!--zb-slot--> comment, where each element for a named slot belongs among the page's children: the walk meets the stand-in, and the element goes with it. What Svelte's walk took past the block is put back, and the stand-ins after the node Solid puts in a cleared run's place go too. Removing the element any other way removes its stand-in. insertBefore(node, sibling) also keeps its place when the sibling is in another slot, where it used to append. Still not covered, and best written as one block per slot: a Svelte block whose first node is in a named slot and whose last isn't, and a Solid <Show> whose first node is in a named slot. The runtime's size budgets go up by 0.5 KB for it (17 KB, and 15.75 KB for the production build). In @zubra/runtime and in --emit element output.
  • Angular: {{ }} text as a light-DOM component's direct child is slotted (#261). <action-button>{{ label() }}</action-button> rendered an empty slot: Angular creates that text node empty and writes it afterwards, empty text is a framework's marker to the runtime, and nothing heard the write. A slot's own text nodes are now watched: one that gets words becomes content (the default slot's, even when it was created after a named slot's element), and one that is emptied leaves, so the fallback shows again. An element defined after Angular has rendered keeps such a node too, where it used to discard a host whose only child was empty text. In @zubra/runtime and in --emit element output.
  • Several elements for one slot, added together next to another slot's marker, all reach it (#262). Angular adds an @if's nodes before its anchor, which sits in the default slot, and the element moves each slot="…" element on to its own slot. Moving one took it out of the list being walked, so the element after it was skipped and stayed where it was: of two slot="actions" buttons in an @if, the second landed in the default slot. Any framework that inserts beside its own markers could hit it. In @zubra/runtime and in --emit element output.
  • --runtime (the runtime compile option) moves the script's own @zubra/runtime imports too (#217). Only the compiler's imports were rewritten, so a component with import { hydrated } from '@zubra/runtime' still had a bare specifier in its output and needed an import map anyway. Now @zubra/runtime becomes the given module, and @zubra/runtime/primitives the file beside it (/assets/zubra/runtime/primitives.js) or the entry under it. The default leaves the script's imports as written.
  • A class on the host tag is warned about (#218). <welding-estimator class="welding-tool"> declares a prop named class whose default is the class, so no element got it: not in the server's HTML, not in the browser, and the script can't read a prop named class either. zubra check, the compile and the editor now say so, and what to do: style the element by its tag (or :host), and leave class to the page that uses it. Nothing about what compiles changes.
  • The docs' runtime size is the current one (#219): about 15 KB bundled (the size test's budget is 15.25 KB), where docs/plain-elements.md, the README and an example still said 13 KB; and what @zubra/server serves with no bundler, about 18 KB since 5.14.0 minified it.

5.14.0 — 2026-11-13#

The runtime a server sends is half the size, components' types reach .ts files in the editor, and the security audit's findings are fixed.

Added#

  • npm create zubra -- --typescript. It asks, or takes the flag: the app's component is <script lang="ts"> with an interface Props, a tsconfig.json is added (Angular keeps its own), TypeScript is a dev dependency, and npm run check runs zubra check --types src, for CI. The README and AGENTS.md say so. --js skips the question the other way.

  • Components' types in .ts and .tsx files, live in the editor. A TypeScript server plugin, @zubra/language-server/typescript-plugin, types an import of a component (./badge.zb, ?react, ?vue, ?element, a .zb.tsx component) from the component itself: errors, hover, completion, and go to definition that opens the component. Saving a component updates every file that imports it, including saves that replace the file. Nothing has to be built first, and allowArbitraryExtensions isn't needed. The VS Code extension registers it with VS Code's TypeScript and passes it the zubra.compiler setting; other editors whose TypeScript runs tsserver add it to tsconfig.json. A plain import is typed for the project's framework (from package.json), as the build plugin compiles it. A component that doesn't compile imports as any until it does.

  • One tag, one definition, in bundlers as on the server. An app's component and a package's with the same tag (both carrying a copy of a shared part): the Vite plugin (and its Rollup, webpack and esbuild forms) now gives the package's components the app's, as @zubra/server does, and warns once if the two copies differ, comments aside. Before, whichever module loaded first defined the tag, the package's as likely as the app's. The plugin finds the app's components from Vite's root or the current folder; root sets it. The compiler (so zubra check, the bundlers and the editor) refuses two of the app's components, or two packages', with one tag anywhere in what a component imports, naming both files and the import they came through. And in development the runtime warns once when a page ends up with two different definitions of a tag anyway (its own scripts importing both); two copies of the same component stay quiet.

Changed#

  • The runtime's production build is minified: about half the bytes a server sends. dist/production (the production export condition, and what @zubra/server serves in production) used to keep every comment, so a page served without a bundler loaded 38.4 KB of runtime, gzipped. scripts/build-production.js now minifies each file after leaving out the development code, with the pinned esbuild: still one module per file, imported the same way, under a header pointing back to src/, which stays the runtime to read. The runtime as served is 17.9 KB. Measured on Tailgate in production: 777 KB → 491 KB of JavaScript over 14 page views (37% less), and 41.9 → 21.8 KB on its form page. Apps that bundle (Vite, Next…) minified it already, so they don't change. The size test now also budgets what's served, file by file.

  • More of a fetcher's later reads are followed (experimental). The compiler's track() rewrite (5.9.0) now also covers a signal's explicit .get() after an await (const rate = state(1) … await auth() … rate.get()), a fetcher that isn't async reading in a callback that runs later (resource(() => load().then((rows) => rows.slice(0, page)))), and .zb.jsx and .zb.tsx components, which didn't get the rewrite at all. A fetcher with no read that can run later is now left as written and doesn't load @zubra/runtime/track; before, every async fetcher did.

Fixed#

  • zubra check --client no longer calls a component client-free when the server leaves part of it empty. It looked for parts the server leaves to the browser by rendering with the default props, so a branch the defaults skip went unchecked: a const list = sorted ? [...items].sort(…) : items counted as complete, while the server can't run the mutating .sort() and a sorted chart rendered empty without its module. Now the methods it accepts are exactly those the server computes (a test runs each one through the evaluator; sort, reverse, fill and toString aren't, while toSorted and toReversed are), and method calls in the template count whichever branch they're in. In the other direction, hasSlot() and a spread into an array ([...items]) no longer count as browser work, since the server renders both. In Zubra UI that moves content-card, empty-state and hero-section to client-free, and bar-chart once its sorted uses toSorted() instead of .sort() (23 of 81).

Security#

  • One malformed request no longer stops a Node server. Three handlers threw on input only a client controls, and the documented wiring (if (zubra.handle(req, res)) return;, if (await actions.handle(req, res)) return;, if (await sync.handle(req, res)) return;) let that end the process. Each now answers 400 and the server keeps serving. From the 2026-11-12 security audit (Z7, Z8, S3).
    • @zubra/server: a /_zubra/ path with a malformed % escape (/_zubra/%E0%A4%A) threw URIError.
    • @zubra/actions: a post whose Host header isn't a host ([::1) couldn't make a URL.
    • @zubra/sync: the same for any sync request, now refused before the body is read.
  • The server evaluator limits how long a string can get (audit Z6). padStart, padEnd, repeat, replace/replaceAll, join and + leave an expression for the browser when its string would pass 1 MiB, checked before anything is allocated; before, a prop like width in padStart(width, '0') could ask for a billion characters and abort zubra serve (and every server using it) or stall @zubra/server. Every string built also spends the step budget (one step per 64 bytes), so a loop can't build many large strings either. Ordinary output is unchanged.
  • @zubra/sync limits request bodies (audit S4). Push, presence and signal bodies are at most maxBytes (default 1 MiB, matching the binary) and a push at most maxChanges (default 1000); over either is a 413, before authorize is asked. Before, a body of any size was held in memory, unauthenticated: 200 MB took the process past 1 GB. connect() now sends its outbox in batches under both limits.
  • A no-JavaScript action post can't redirect off the site (audit Z9). The page to go back to came from the Referer's path, and a path starting with // (https://site//evil.example/) is protocol-relative in a Location header. It's now written with one leading slash, so it stays on the site.
  • A Sync peer id belongs to its live stream (audit S5). Presence and WebRTC signals named their peer, and nothing checked it: another viewer could speak as someone, make them leave a room, or open /live?peer=<their id> and receive their signals (SDP and LAN ICE candidates), across businesses on a shared log. Now the live stream's first event, hello, carries a secret key; presence and signals sent as a peer must carry it (403 otherwise), a signal must come from a peer with a live stream, and a second stream asking for a held peer id gets a 409 unless it presents the key (a reconnect, which takes over without a goodbye). Signals reach their peer only if its scope has the room. connect() handles the key itself, and the zubra-sync binary does the same.
  • The URL check refuses numeric references without their ; (audit Z5). &#106avascript: and javascript&#58alert(1) passed the check, since the decoder only decodes references that end in ;, but browsers decode them in attributes. Anything before a URL's path that still contains &# is now refused, in templates and in slot content supplied at build time.

5.13.1 — 2026-11-13#

A box ticked or a field typed in before a component starts stays ticked or typed.

Fixed#

  • What someone does to a form before the element starts is kept. On a server-rendered page, a visitor can tick a box, type or pick an option before the component's module has loaded. When the element then started, it wrote its state into every bound control (checked={…}, value={…}), undoing what they had done, so the form submitted something else. Outfitter's booking test found it: a day ticked while the page loaded was unticked, and the booking went off with no day ("Pick at least one day"), about one run in three. Now a control that no longer shows the server's default when the element takes over (checked against defaultChecked, value against defaultValue, a select's options against defaultSelected) keeps what the visitor did; the bound value applies to it again once the state changes. A control nobody touched is set from state as before. Browser tests: early input in a checkbox, a text field, a select and a textarea survives and is what the form submits; untouched controls follow state.

5.13.0 — 2026-11-13#

The server runs functions with loops and ifs, and Array.from, so lists a component builds that way are in the server's HTML.

Added#

  • The server runs functions with statements in them. A function declaration, or an arrow with a block body, can now have lets that change, if/else, for, for…of, while, break/continue, push onto its own arrays, and return. Before, the server ran only an expression or a run of consts and a return, so a list built by a loop (Zubra UI's page-nav, Front Desk's free times) was empty in the server's HTML. It changes only the function's own names. A function that changes the component's state or anything else, or calls something for its effect, is still the browser's, as is one that runs past the step limit.
  • Array.from on the server: an array, a string (by code point), or { length: n } with a mapper. String, Number and Boolean as callbacks (.map(String), .filter(Boolean)).
  • With these, Zubra UI's star-rating, skeleton-block, code-input, page-nav, typing-text, word-rotate and data-table render whole on the server; all ten checked hydrate without a warning and read the same before and after JavaScript.

5.12.0 — 2026-11-13#

The server answers hasSlot, so markup a component wraps around a used slot is in the server's HTML and works without JavaScript.

Changed#

  • The server answers hasSlot. const hasFooter = hasSlot('footer') was left for the browser, so whatever a component wrapped around a used slot (a footer, an actions row) was missing from the server's HTML and without JavaScript. The server knows which slots it was given, so it now renders the binding as the element will decide it: an element, or text that isn't only whitespace, counts as content. The slots it found filled go on the host as data-zb-filled, and the element starts from them, so it keeps that markup instead of removing it before it has seen its slotted content. This covers hasSlot() (the default slot) and a name written as a string; a name in a variable is still the browser's. Found by 5.11.0's new warning: six of Tailgate's eleven gaps were Zubra UI parts asking hasSlot('actions'). The markers test now takes its browser-only region from chat-message, since kanban-column no longer has one.

5.11.0 — 2026-11-13#

@zubra/server says when part of a component's server HTML is left for the browser, so a page that's empty without JavaScript doesn't go unnoticed.

Added#

  • The server renders regular expression literals and URI encoding. A component that trimmed an address with server.replace(/\/+$/, "") or built a link with encodeURIComponent(code) rendered that part empty on the server, because both were outside the subset; open.blog's build of the card room's <card-room> component showed an empty box to readers without JavaScript. Regex literals now run on regress, an ECMAScript regex engine, matching on UTF-16 code units as the browser does (without /u, /./ takes half of an emoji). They work in .replace and .replaceAll (with $&, $`, $', $1–$99, $<name>, $$, or an arrow function), .split (with captures and a limit), .match with /g, .search and .test without /g; what depends on regex state (lastIndex, /y, .exec, a non-global .match) is still left for the browser. A build never waits on a pattern: one that could take exponential time (a repeat inside a repeat, | inside a repeat, a backreference) is left for the browser, and the text a pattern searches is capped by how many repeats it has. encodeURIComponent, encodeURI, decodeURIComponent and decodeURI are evaluated too, leaving a malformed escape for the browser to report. Every new case is compared with V8 in compiler/test/server-evaluation.test.js.
  • @zubra/server says when a render leaves part of a component's HTML for the browser. Anything the server can't compute (a list derived through a function with a loop, a formatted date) renders empty and is filled in once the element's module runs, so without JavaScript that part is missing. zubra check --server already listed these places, but with the component's defaults and only when asked; a server rendering real props said nothing. Front Desk's free-times shipped a list of time buttons that was empty in the server's HTML, and it was found only by a test without JavaScript. Now @zubra/server warns once per place, with the same words, file, line and caret as check --server. createZubra({ gaps: 'ignore' }) turns it off where that's intended. The compiler's request takes "gaps": true on a partial HTML render and answers with gaps.

5.10.3 — 2026-11-13#

Text given to a component before it connects no longer waits for remark.js.

Fixed#

  • A template that is only regions renders at once when the page gives its host text. Zubra UI's action-button and shimmer-button are an <a> or a <button> behind zb-if/zb-else, so their template has no elements of its own, and any text a framework put in the host first (React and Svelte do, then connect it) looked like server markup that lost its comments. The element loaded remark.js, a dynamic import, before rendering: a moment of bare text, and (until 5.10.1) an updateComplete that resolved too early. The compiler now emits roots for such a template, the elements its regions' blocks start with (roots: ["a", "button"]), and the runtime waits only when the host holds one of them. Server markup that lost its comments still does, and is put back as before. A template with elements of its own, or a block the compiler can't name (a slot at its top, text on its own, an zb-await), has no roots and is checked as before. Older compiled output has none and behaves as before.

5.10.2 — 2026-11-13#

Components that import other components by relative path render on Windows.

Fixed#

  • Relative component imports on Windows. @zubra/compiler's sources() keyed a component by its path and decided whether its imports were relative to a path or to a package specifier by checking for a leading /. A Windows path (C:\app\page.zb) has none, so ./parts/card.zb was keyed as parts/card.zb, and rendering the page in @zubra/server failed with "not among the request's files". It now tells a path from a specifier on any platform (drive letters and \\host\share paths included). Found by CineStack on Windows, which had patched the compiler (normalizing the keys to /); the patch can go.

5.10.1 — 2026-11-13#

updateComplete waits for an element's first render when that render is itself waiting.

Fixed#

  • updateComplete resolves after the first render, also when that's delayed. An element whose template starts with a condition (a button that's a link with href) and is given text before it's connected, as React and Svelte do, first checks whether that content is server markup whose markers were stripped. The check loads remark.js on demand, so the element renders a moment later, and updateComplete resolved before it had: a test that awaited it right after mounting found the element empty (Zubra UI's action-button and shimmer-button, in its React and Svelte snippet tests). It now waits for that render. The render itself still comes after the import, for the first such elements on a page.

5.10.0 — 2026-11-13#

An app and a package can each carry a copy of the same part. When an app's component and a package's share a tag (both have Zubra UI's action-button, say), the app's is used everywhere, instead of the server refusing both. Also: the playground's React and Vue previews render the page.

Changed#

  • @zubra/server: an app's component wins over a package's with the same tag. An app and a package that each carried a copy of a shared part (an action-button from Zubra UI) couldn't share a server: rendering by that tag threw "is defined by both". Now the app's copy is used everywhere: by tag, by the package's name, and by the package's own components, whose import of their copy is served as the app's module, so the browser defines the tag once. If the two sources differ (comments aside) the server warns once. Two of the app's components, or two packages', with one tag are still an error. Inside a package component's server HTML, a child still renders from the package's copy, so keep the copies the same.

Fixed#

  • The playground's React and Vue previews render the page. They ignored the page box and always rendered one default component. Now they read the markup as the plain HTML preview does: a host tag's attributes become typed props, its child elements become children and named slots, and other elements render as written. The preview controls stay readable in dark mode.

5.9.2 — 2026-11-12#

Security fixes from the November audit's high findings: what @zubra/server serves, what streamed values and spread keys can write into a page, Sync clocks and field names, and the server-language clients' deferred markers. Upgrade if you use @zubra/server, @zubra/sync, or the Django, Rails or Laravel integration.

Changes to note: @zubra/server now answers 404 for a plain .js module no component's browser code imports; Sync refuses a push stamped more than 60 s ahead (maxSkew) and a field named key; code that wrote the Django, Rails or Laravel markers by hand needs the request's token (below).

Security#

  • @zubra/server serves only the plain modules the browser imports. Since 5.9.0 it served any .js file in the components folder, so a module only a 'use server' function imports (an API key, database code) could be fetched from /_zubra/components/…, and so could a file a link led to outside the folder. Now a plain module is served only if a component's browser module imports it (statically or with import()), or one of those does, and never when its real path is outside the folder. Everything else is a 404.
  • A spread's keys can't write markup. {...attrs} wrote each key of a value raw into server HTML as an attribute name (and each style key as a CSS property name), so a key like x onmouseover=alert(1) y, from a user's data, became a handler on every page that rendered it. A key that isn't an attribute name (a letter, _ or :, then letters, digits and _ . : -), or a style key that isn't a CSS property name, is now left out, with a warning from @zubra/server, as an unsafe URL is; in the browser the spread leaves it out too (it used to throw).
  • A streamed value can't close the script it travels in. A promise prop's value or error went into an inline <script> through JSON.stringify, which leaves < alone: a review named </script><script>… ran as script on every page that streamed it. Values (and the import map) are now written with < as \u003c.
  • Sync refuses clocks far in the future. A page could push a change stamped 999999999999999-99999: it won that field's merge for ever, and every server write() after it threw (the next counter outgrew its five digits), surviving a restart. Now a push whose clock is more than maxSkew ahead of the server's (createSyncServer({ maxSkew }), default 60 s; 60 s in the zubra-sync binary) is refused with a 400. A device a little fast still works. A far-future clock already in a log doesn't drag the server's clock with it, devices don't follow one they hear, and clock counters carry into the next millisecond instead of overflowing.
  • A page's own text can't take the place of the head and scripts markers. The Django, Rails and Laravel middleware filled every <!--zubra:scripts:BASE--> and <!--zubra:head--> in the response, so a user's comment rendered with them (raw, or through a sanitiser that keeps comments) put a module script from any base they chose on the page. Each request's markers now carry a random token, and only those are filled. Code that wrote the markers itself uses the new forms: HEAD/SCRIPTS with a token in Python (request.zubra_marker), Zubra::Rails.head_marker(token) in Ruby (env["zubra.marker"]), Deferred::head($token) and Deferred::scripts($token, $base) in PHP (the zubra.marker request attribute); Page::fill and Zubra::Rails.fill take the token.
  • A field can't be named key. documents().all() lists documents as { key, ...fields }, so a field named key replaced the document's key: server code acting on the listed record acted on another one (another tenant's, under a shared log). The key is now listed last, and a push with a field named key is refused (400) in both servers, as $clocks already was; write() throws for it.

Added#

  • @zubra/unplugin has typings for every entry. @zubra/unplugin/vite (and /rollup, /webpack, /esbuild, /rspack, /astro and the package itself) ship declarations, so a vite.config.ts type-checks and its options are checked: zubra({ framework: 'svelte' }) is an error that lists the frameworks it takes. Before, TypeScript reported TS7016 for the import under strict, and apps declared the module themselves.

Documentation#

  • Class names inside light-DOM components. The README's styles section and the component skill now say that an unlayered page rule for a common class name (.table, .card) matches a component's elements with that class and beats the component's own CSS, and that variants are safer as attributes. Found by an app whose layout .table collapsed a card component's table size to 2px.

5.9.1 — 2026-11-12#

A security fix for @zubra/sync, and faster lists and Signals. Sync used to take any change from any page: a server without authorize now serves reads and refuses writes from pages until it's told who may make them (authorize, or allowAnyone for a page everyone may edit), and authorize is told the field and value a change sets.

One behaviour change, on purpose: an app that relied on Sync accepting every page's writes without an authorize now gets 403s, with a message saying what to pass. authorize: allowAnyone restores the old behaviour; the zubra-sync binary needs --open.

Security#

  • Sync takes no writes from pages until it's told who may make them. createSyncServer() used to default authorize to allowing everything, so any visitor could push any change: in an app with prices, stock or payments in its log, that meant setting a price, marking an order paid or taking every seat. Now, without authorize, pages may still read, but every push, presence and signal from a page is refused with a 403 that says what to do, and the page says so once in its console. The server's own write() is unchanged. To keep the old behaviour for a page everyone may edit, pass authorize: allowAnyone (new export). A Durable Object (SyncObject) without an authorize() method takes reads only, and the zubra-sync binary takes writes only when started with --open.
  • authorize is told what a change sets. A kind: 'change' call now has field and value, so an app can keep fields, or whole collections, for the server: a page may move a card but not change its price. authorize must be a function (anything else throws at createSyncServer).

Changed#

  • Lists put rows on the page with less work. A row zb-each makes in the browser has no comment markers of its own: it's its block's nodes, first to last (rows the server rendered keep theirs, so hydration is unchanged). A block with no custom elements is copied into the document once and cloned for each row; one with a custom element still uses importNode, so the element upgrades before its props are bound. A text binding on an element holding one Text node writes that node's .data instead of replacing it through textContent, which also no longer reads the subtree to compare. In js-framework-benchmark, clear rows went from 24 to 17 ms, append rows from 152 to 114 ms and replace all rows from 125 to 110 ms (docs/performance.md). The size budgets went up 0.25 KB, to 16 KB and 15 KB gzipped (about 100 B).

  • The Signals implementation is faster, with the same API. Each signal keeps its internal node in a private field instead of a WeakMap the garbage collector has to walk; nodes have one shape and make their arrays on first use; an effect makes its set of children on first child. Watcher.getPending() now costs O(pending) instead of O(watched): the Watcher records computeds as they're marked dirty, so an update no longer pays for every effect on the page. Its order is the one visible difference: roughly the order computeds were marked, not the order they were watched (runtime/README.md). The list holds at most one entry per watched computed, lets an unwatched computed go at once, and counts how often a computed is watched in whichever is shorter, its watchers or the watcher's computeds, so neither a computed shared by thousands of watchers nor a watcher of thousands of computeds turns quadratic. In Node, creating and disposing 2,000 effects went from 14–20 ms to 3–4 ms; in js-framework-benchmark, create rows from 137 to 100 ms, clear from 24 to 17 ms and select from 15.5 to 5.7 ms (docs/performance.md). The size budget for src/index.js went from 15.25 KB to 15.75 KB gzipped, and for the production build from 14.25 KB to 14.75 KB.

5.9.0 — 2026-11-12#

Package components, TypeScript completely, and server HTML that's complete before JavaScript. A .zb file imports components from an npm package by name, checked like its own. <script lang="ts"> compiles what was refused (enums carried over from 5.8.0, now namespaces, parameter properties, legacy and standard decorators), follows the nearest tsconfig.json, and is type-checked by the project's TypeScript: npx zubra check --types, and errors, hover, completion and go to definition in VS Code. On the server, id() and context render, so labels and aria-* references work and themes apply before JavaScript, and page.provide() gives a whole page a context. Also: effects, scopes and resources work with using, a fetcher's reads after an await are followed (experimental), keyed lists move only what's out of order, table lists are cheaper, and a long-lived compiler stops re-parsing components.

5.8.0 on npm was built before several entries its changelog listed had merged: they're here, where they shipped.

One behaviour change: in @zubra/server, rendering by a tag that two components share is now an error that names both (each still renders by its name); before, the last one found won silently.

Added#

  • Reads after an await in a resource's fetcher are followed (experimental). A fetcher's code after its first await runs outside the effect, and the Signals API records a read only while a Computed runs, so resource(async () => { const token = await auth(); return load(page, token) }) didn't load again when page changed. tracked(fetcher), from the new @zubra/runtime/track (about 570 B gzipped, loaded only where it's used), gives each run track(read): the read is followed, and a change runs the fetcher again. In a .zb script the compiler writes it for an async fetcher of the runtime's resource(): $run.track(() => …) around the props and state it reads that can run after the first await (in a loop that awaits, or in a function inside it, too), leaving the earlier reads plain. A replaced run, a run that has settled (a timer it left) and a disposed resource still read, without subscribing, and a detached element holds none of the reads. Reads the compiler can't see (a getter in another module) still need track(). The AsyncContext alternative was measured too; docs/standards/signals.md reports both.
  • id() renders on the server. const inputId = id() used to be computed only in the browser, so a server-rendered <label for> and its <input id>, and every aria-labelledby/aria-describedby/aria-controls, pointed at nothing until JavaScript ran. Now each host gets an id base on the server (its own id, or <tag>-s<n> in document order, written as data-zb-id), each call its number, and the element uses the same base, so hydrating keeps the ids. Elements made in the browser count their own ids, which can't collide with the server's. @zubra/server prefixes each page.render() after the first (r2-) and each host it fills in framework HTML (h1-); idPrefix on a request does it elsewhere. It applies when every id() call is a const x = id(). In the registry, date-range, dropdown-menu, tag-input and tool-tip now have no parts left for the browser, and modal-dialog one instead of three. After Enhance's instanceID.
  • page.provide() in @zubra/server: context for a whole page. page.provide({ module: './theme.js', export: 'theme' }, 'dark') provides a context to every component the page renders after it, as a component above them would, so the account, the locale or a theme doesn't have to be passed to each page.render() (Enhance's store, as context). They render with it and their elements start from it; a <zb-context> around the page changes it later. A render request takes the values as context (context key → value). And @zubra/server now serves the plain .js modules components import from the components folder (a module with the createContext(), a helper), which were a 404, with no way out of the folder.
  • Context renders on the server. A component's provide(context, value) now reaches const x = inject(context) in the components it renders, in the server's HTML (it was empty until JavaScript ran): the nearest provider wins, a provider's own inject sees the one above, and with no provider the server uses the context's default when it can read the module. Contexts are matched by their module and export name. The consumer's host carries the values (data-zb-inject), and inject() starts from them, so hydrating doesn't flash the default before the provider answers. After Enhance's state.context.
  • Components from a package. A .zb file can import a component by its package's name (import '@acme/kit/components/cart-panel.zb'), found in node_modules as Node finds a package and following its exports. The package's component is checked like any child (props, at your line), its own relative imports work, and a missing package or an unexported file is an error that says which. The CLI, @zubra/compiler, the Vite plugin and the language server all follow it (the language server keeps a copy of the rule, tested against the compiler's). createZubra({ packages: ['@acme/kit/components'] }) serves a package's folder beside your components, with one import map entry, and renders them by name or tag. Not yet: the edge entry, zubra build and the manifest.
  • @zubra/server: two components with one tag can't both be rendered by that tag. Rendering by the tag says which two; each still renders by its name. Before, the last one found won without a word.
  • Effects, scopes and resources work with using. effect()'s returned function, scope(), root() and resource() are disposables ([Symbol.dispose]), so using stop = effect(…) and DisposableStack end them where the engine has Explicit Resource Management (Chrome 134+, Firefox 141+, Node 24; not Safari yet). Where it doesn't, they use the symbol TypeScript's downlevel using and the polyfills look up, and nothing else changes. resource() gains dispose(), which aborts the request in flight. Pausing a detached element stays separate from disposal. The typings add [Symbol.dispose] only when the project's TypeScript lib has it, so older settings still type-check; a tools test checks both. CI also runs the disposal tests on Node 24.
  • Compared with WebUI, FAST, Enhance and WebC (docs/compared-with-html-first.md): the README's copy button written in each, with what each sends to the browser and how fast each server renders a page of ten, measured by docs/compared/html-first/measure.mjs and checked in Chromium in a new CI job. It says plainly that rendering without Node.js isn't unique to Zubra (WebUI renders natively; Enhance runs in QuickJS compiled to WebAssembly), and what is: one compiler for server and browser, JavaScript expressions evaluated by Rust (WebUI's templates drop {{count + 1}} without a warning, which the test checks), framework wrappers and --emit element. It found Zubra's server about 20 times slower than WebUI's on that page, because each component is parsed again on every render.
  • A FAST Element 3 example, examples/frameworks/fast-orders: Zubra elements inside a FASTElement's shadow root, set by :prop bindings, heard by @valuechange, and reading a currency FAST's Context provides through inject(). Tested in the framework examples job.
  • The rest of TypeScript. What was refused in <script lang="ts"> is now written as tsc writes it, in place and with the same number of lines; a plugin test compares each with tsc's output when run.
    • namespace: TypeScript's function wrapper (const N = {}; (function (N) { … })(N);), exported members assigned to it, references to exported variables read through it (N.x), names another declaration of the same namespace exports read through it too, nested and dotted (A.B.C) namespaces, merging into an earlier namespace, function, class or enum, and nothing at all for a namespace with only types. A component script can't export one; the error says why.
    • Parameter properties (constructor(private x: number)): a field (TypeScript's useDefineForClassFields default) and an assignment first in the constructor, or after super(…) in a subclass.
    • import X = A.B: const X = A.B, or nothing when it names a type. this parameters and <T>value assertions are types, and go.
    • Still refused, as tsc refuses them in an ES module: import x = require() (TS1202) and export = (TS1203).
  • TypeScript components follow their tsconfig.json. The nearest one above a component (with a relative extends; comments and trailing commas allowed) is read for the options that change the JavaScript, by the CLI from disk and by @zubra/compiler, which sends it to the WebAssembly build. useDefineForClassFields off (or a target below ES2022) writes class fields as tsc does then: initializers assigned in the constructor (a constructor is written if there's none), statics in a static {} block, and no field for a parameter property. verbatimModuleSyntax keeps imports as written and makes a type imported without type an error (TS1484). paths and baseUrl find a non-relative TypeScript module, for its enums.
  • TypeScript review fixes (from a specialist review of the TypeScript work, every bug checked against tsc):
    • Moved code keeps its meaning: a field's value moved into the constructor and a decorator moved into its call keep the rewrites inside them (N.x in a namespace, a nested class's own lowering), and are put on one line safely (comments go, statements keep their ;, a template literal's line break is written \n). A multi-line decorator argument with a // comment, the usual Angular and Lit shape, compiled to an error before.
    • With useDefineForClassFields off, #private instance fields and accessor storage are assigned in the constructor in order with the other fields, as tsc does; they ran first before. A <script lang="ts"> spelled with extra spaces reads its tsconfig.json too.
    • <T>value is (value), so it's right after return and a line break, as an arrow's object body, and at the start of a statement.
    • Namespaces: a parameter property with constructor overloads; nested namespaces declared twice; namespace A.B read from A; an outer name another declaration exports; ({ x } = value); a namespace declaring its own name (its parameter becomes N_1, as in tsc); a line break after export const; an alias only the template reads.
    • Enums: a function's own parameter named like a member; a computed member's types, namespace references and { A }; members after one computed from a const or a namespace's enum or constant (no initializer needed, as in tsc); template literals with substitutions; numbers printed as JavaScript prints them (1e+21, 5e-7); enums declared twice in a namespace.
    • Legacy decorators: a class decorator's class sees what the decorator returns in its own references and static initializers (tsc's A_1); export default with a class decorator; a decorator on a class expression is TS1206, as in TypeScript. @abstractSomething abstract class compiles.
    • Standard decorators: a decorated field followed by an undecorated computed name.
    • import { type A } from "./a" goes entirely, as in tsc (it left import {} from "./a").
    • check --types: positions after non-ASCII characters; running from another folder (a monorepo); open:bind (a false error on every binding); objects with a get method read as signals; const enums; <zb-window>/<zb-document> events; .zb.tsx children; components imported from outside the project; props named like keywords; errors reported twice; zb-switch values; text defaults against Props; interface Props extends, method members and type Props = A & B; --format json paths and help. The terminal's check and the editor's no longer remove each other's files, and a stopped editor check's files are cleaned up.
    • Editor: hover and go to definition in files with CRLF line endings.
  • Standard decorators and accessor fields in TypeScript. TC39's decorators (TypeScript's default) are lowered as tsc lowers them for ES2022, which no browser runs natively yet: TypeScript's helpers on the script's first line, the class wrapped in a function that holds the bookkeeping, and every member's code left on its own line (a #private method's function is created where it was). Methods, getters, setters, fields, accessors, static and #private members, literal and computed names, class decorators that replace the class, addInitializer, access and metadata all behave as tsc's output does, checked by running both. accessor x is lowered without decorators too. A parameter decorator needs experimentalDecorators, as in TypeScript (TS1206).
  • TypeScript decorators, with experimentalDecorators. Legacy decorators are written as tsc writes them, keeping lines: each @ goes, and __decorate calls follow the class (instance members, static members, then the class with its constructor's parameter decorators); a class decorator wraps the class. TypeScript's helpers go on the script's first line when used.
  • npx zubra check --types: templates checked against TypeScript. The project's own TypeScript checks each <script lang="ts"> component: the script, every template expression in its scope (a zb-each item has the list's element type, a zb-if narrows, a signal reads as its value), each child's props against the child's types, and each event handler with its event typed (MouseEvent, or the child's CustomEvent<…>). Errors land on .zb lines. The compiler writes each component as a TypeScript file with a map back (--emit tsx shows one; zubra request command virtual gives the map); @zubra/compiler/typecheck puts them in .zubra-types/, joined to the project with rootDirs, and runs the project's tsc. emit from @zubra/runtime is now typed emit<Detail>(name, detail). --format json gives the errors as the Rust CLI's check --format json does, with each one's code; new projects ignore .zubra-types.
  • Type errors in VS Code. The language server shows what zubra check --types finds in a TypeScript component when it opens and each time it's saved, beside the compiler's diagnostics, from the project's own @zubra/compiler and typescript, in a process of its own so the editor never waits on tsc. checkTypes() takes an editor's unsaved text, checks one component with the components it imports (reporting only its own errors), and can use a folder of its own.
  • interface Props types a TypeScript component's props in one place. interface Props { size: Size; maxCount?: number } (or type Props = { … }) gives each prop its type in the typings, the manifest and zubra check --types, and must name the same props as the host tag: a member with no prop, or a prop it doesn't have, is an error that says which. declare const still works.
  • TypeScript hover, completion and go to definition in .zb files. In a <script lang="ts"> component the VS Code extension gives TypeScript's hover, completion and go to definition in the script and in every {…} of the template, through the same file zubra check --types checks (held in memory beside each component, so imported components' types resolve). A zb-each item has its list's element type; completion works after a . that doesn't compile yet; go to definition from the template lands on the script's declaration. It's TypeScript 5.9's language service, which the language server now ships with: the native TypeScript 7 has no JavaScript language service API yet.

Fixed#

  • Lists in tables are cheaper to build and clear. Blank text between table rows and cells (inside table, thead, tbody, tfoot, tr and colgroup, and in the zb-each, zb-if and zb-await bodies there) is no longer kept: a browser never lays it out, and a list's indentation in a <tbody> was two more text nodes per row to create, keep and remove. Text inside cells, and whitespace anywhere else, is unchanged. And clearing or replacing every row of a list that is all its parent holds (but blank text) now empties the parent at once instead of deleting a range. In the js-framework-benchmark operations, a 1,000-row table has 3,002 nodes instead of 5,004, and creating rows went from 92 ms to 74.
  • A keyed zb-each moves only the rows that are out of order. It walked the new order and moved every row that wasn't where the walk expected, so swapping two rows of a thousand moved every row between them. It now keeps the longest run of rows already in order and moves the rest, as most keyed renderers do: a swap moves two rows, moving the last row to the front moves one. Both outputs, @zubra/runtime and --emit element. In the js-framework-benchmark operations, swap rows went from 63 ms to 13.5 ms, level with Lit and hand-written JavaScript. Browser tests count the rows moved and check forty seeded random reorders with rows added and removed.
  • A long-lived compiler renders a component again without parsing it again. zubra serve, the WebAssembly build behind @zubra/server and the language server parsed each component (and each component it imports) on every request, and parsed it a second time for its warnings. A parsed component is now kept by its path and text, and reused only while every import it loaded still has the same text, so an edited file or child is parsed again; the warnings are kept by text. Rendering itself still runs per request, since it depends on the props. The README's copy button renders in 17 µs instead of 30 through zubra serve (native, JSON included). Found by comparing server rendering with WebUI's.
  • signal(x) passes the signal for a let, a from() and a derived const, as the README documents (watch(signal(count), …)), instead of compiling to signal(x.get()), which passed the value: a context provided with provide(theme, signal(mode)) now follows mode.

5.8.0 — 2026-11-12#

Zubra ready for the business kit, and Zubra beside other frameworks. For the kit: Sync's documents are a synchronous store with a key prefix, Actions take files, class: and style: work on child components, and a device offline for hours (or one whose tab closes mid-write) never loses its edits or shows an older change over them. Beside other frameworks: context and signals shared with the app, form libraries, the app's router, experimental React outlets, testing through every framework, a no-build --embed output, an MCP server for coding agents, and server templates for Django, Rails and Laravel. Also in this release: TypeScript enums (as prop types, from attributes and from other modules), ::slotted() and ::part() in light DOM, components and pages that ship no JavaScript when they need none, the ES2019–ES2024 array and object methods on the server, and a type-only import no longer reaching the browser.

One behaviour change: Actions now read a post only up to maxBytes, 10 MB by default. A bigger post gets { error: 'Too large' } and the function doesn't run; set createActions({ maxBytes: Infinity }) for the old behaviour.

Added#

  • Sync: documents().all(collection, prefix) gives only the documents whose key starts with prefix (all('seats', 'show-12/')), as scope does for pages. With it, documents() and write() are a synchronous store in a few lines, for code that keeps its rules apart from where documents live: reads with no await, and a write in the documents before its promise settles. Documented, and tested on each log and inside a Durable Object, including after an eviction.
  • Actions: files, and a limit on what a post may be. A file input reaches a server function as a File on both paths (documented and tested in a browser, with and without JavaScript). createActions({ maxBytes }) caps a post, files and fields together, at 10 MB by default: a bigger one gets { error: 'Too large' } (413), isn't kept (the rest is discarded as it arrives, so a browser still sending gets the answer), and the function doesn't run. Before, a post of any size was read into memory; set maxBytes: Infinity for that. For listing photos, logos and damage reports.
  • ::part() reaches into light-DOM children. A rule like zb-meter::part(label) in a component that imports a light-DOM <zb-meter> is rewritten to @scope (zb-meter) to ([data-zb-slotted]) { [part~="label"] { … } }, so it styles the child's own elements with that part (several names need all of them, as in shadow DOM) and stops at content slotted into the child. A shadow-DOM child, or a tag the compiler doesn't know, keeps the real ::part(). In a light-DOM component's stylesheet those real ::part() rules now go outside its @scope, as :where(tag) child::part(x) (WebKit doesn't match ::part() inside @scope); zubra convert reads all of it back. It works in both a light and a shadow parent, in server HTML before JavaScript, and in plain elements. Browser test, mutation-checked.
  • Components that need no JavaScript, and pages that ship none for them. The compiler now works out whether a component needs its module in the browser at all: it doesn't when it only shows its props and slots (no state, handlers, two-way props, lifecycle hooks, browser imports, zb-await, motion, or values the server can't compute, in it or in the components it uses). zubra check --client prints the answer and the reasons for each file, the interface (--emit interface, and describe(name) in @zubra/server) has them as client, and a check request takes "client": true. createZubra({ clientModules: 'needed' }) in @zubra/server then leaves those components' modules out of a page: they're complete as server HTML, styles included. It's opt-in, since a page that changes such a component's props from its own script still needs the module. In the registry, progress-ring and spark-line need none. From Enhance's "elements first".
  • A warning for camelCase attributes that HTML lowercases. <star-meter maxvalue="8"> on a component whose prop is maxValue is ignored by the element (its attribute is max-value). zubra check and zubra compile now warn about it in .zb templates, with the fix, and in a page, where the browser lowercases maxValue itself, the element warns in the console once, naming the attribute to write. Plain elements (--emit element) stay without the runtime warning.
  • docs/stability.md: the stage Zubra is in, and a tier for everything it maintains. Pre-adoption: majors follow new standards as they land, nothing Stable breaks within a major, and the page says what changes once someone else ships on Zubra. Every npm package entry and command is Stable, Supported or Experimental, with the CI job that tests it and what uses it, and so are the crates, server clients, editors, embeds and the registry. A test in the guide-pages job fails when an entry has no row or a row names one that's gone. Writing it found @zubra/unplugin/rspack untested (Experimental now) and the Laravel provider never executed in CI.
  • ::slotted() works in light DOM. A light-DOM component's <style> stops at slotted content, so until now it couldn't lay out what it was given (masonry-grid set align-self from script). The compiler now rewrites ::slotted(x) to the slotted mark, :where([data-zb-slotted="tag"]):is(x), in a second @scope with no lower boundary, so the same stylesheet places slotted elements with or without shadow, in server HTML before JavaScript and after hydrating. It reaches the slotted elements, not their descendants, adds no specificity, and stays in the component's cascade layer, so page CSS and utilities still win, as across a shadow root. Selector lists are split, and @media, @supports, @container and @layer blocks are split inside. Idea from Enhance's style transform. Browser tests: alignment, spans, descendants untouched, page CSS winning, and server-rendered markup.
  • Server templates in Django, Rails and Laravel. Clients of zubra serve for more server languages, each with the same shape as the Python package (a long-lived compiler process behind a lock, a page per request that collects the CSS and modules, a replaced process after a timeout or a crash, so no request gets another's answer), plus their framework's template helpers. Django (zubra.django): {% zubra "plot-map" plots=plots %}, {% zubra_head %}, {% zubra_scripts %}, a middleware and a module view. Ruby (clients/ruby, the zubra gem): Zubra.new("components"), and for Rails <%= zubra "plot-map", plots: @plots %>, zubra_head, zubra_scripts, a Railtie, a Rack middleware and a mountable module endpoint. PHP (clients/php, zubra/zubra): new Zubra\Zubra(...), and for Laravel @zubra('plot-map', [...]), @zubraHead, @zubraScripts, a discovered service provider, a module route and a middleware. In all three the middleware fills in the head and scripts after the response is rendered, so a layout's <head> gets the CSS of components its view renders further down. Tests run each against the real compiler; a new CI job runs the Ruby and PHP ones.
  • npx zubra mcp: an MCP server that describes a component library to coding agents. Built from the Custom Elements Manifest, from a components folder, a custom-elements.json or an installed library's package name. Its tools: list_components; describe_component (props with types and defaults, events with their detail types, slots, which props are two-way); component_usage (the import and markup for HTML, React, Vue, Svelte, Solid or Angular, in that framework's syntax for props, two-way binding and events); and check_markup, which finds props a component doesn't have and events it doesn't fire in markup an agent wrote, with the nearest real name. It speaks MCP over standard input and output, and needs no network, model or account. @zubra/compiler/mcp has the pieces. The CLI's help now lists every command.
  • zubra build --embed: components for sites with no build step. One flat folder of ES modules with relative imports (an entry that defines every component, each component, and the production runtime it uses), so a single <script type="module"> from any static host or CDN is enough, including Shopify's asset folder, which allows no subfolders. Beside it: an HTML snippet per component (Webflow's Embed, Squarespace's code block, any CMS); a WordPress plugin with a block per component (a sidebar field per prop, previewed by the server render) and a shortcode per component ([star_rating max="10"], content into the slots), loading the components as a script module only on pages that use one; and a Shopify theme app extension with an app block per component, its props as settings. All from the components' interfaces; @zubra/compiler/embed has buildEmbed(). A component that imports an npm package is refused, by name. Tests: the folder's imports, the Liquid blocks rendered with LiquidJS, the plugin run under PHP, and the components loaded in Chromium from one script tag.
  • Testing a library through every framework: @zubra/runtime/testing. mount(Element, { framework, props, slots }) puts a component in the page as plain HTML, through the React adapter or through the Vue adapter, so one test runs the way each kind of consumer uses it: events reach the framework's own handlers (events('valuechange') lists their details), set(props) re-renders through the framework, slots are its children, and a <prop>change event updates the prop as a two-way binding would (so React's controlled pattern doesn't put the old value back). frameworks() lists the installed ones. It works in any browser test runner; examples/testing-vitest runs the registry's star rating through all three in Vitest's browser mode, in CI.
  • Outlets (experimental): a component asks React to render per item. <zb-outlet name="row" item={item}> inside a zb-each marks a place the app's framework fills; the React adapter fills outlets from render<Name> props (renderRow={(item) => <Row item={item} />}) through portals, so the rows keep the app's context, state and handlers, a keyed move keeps each row's state, and a removed row unmounts. A template with an outlet imports @zubra/runtime/outlet. Browser tests in React 19 and 18. React only for now, and client-only (the server leaves outlets empty); the protocol (outletconnect, event.claim) is there for other adapters.
  • Zubra in js-framework-benchmark, and docs/performance.md. An implementation in the benchmark's layout (benchmarks/js-framework-benchmark/frameworks/keyed/zubra, one .zb file written as the guide teaches), ready to submit upstream, and a runner that checks it with the benchmark's own steps in CI. Timed locally beside vanilla JavaScript and Lit, updates are on a par with Lit; swapping two rows is four times slower, because a keyed zb-each moves every row between the two; creating, replacing and clearing rows are 1.3 to 3 times slower.
  • Links inside components go through the app's router. routeLinks(navigate) from @zubra/runtime/navigation hands a click on a plain <a href> inside a Zubra component to the app's router, so it navigates without reloading the page: React Router (useRouteLinks(useNavigate())) and Next.js (useRouteLinks(useRouter().push)) from @zubra/runtime/react, Vue Router from @zubra/runtime/vue, SvelteKit's goto and Angular's navigateByUrl directly. New-tab and modified clicks, target, download, rel="external", other origins, same-page #… links and clicks already handled are left alone, as are the app's own links; without JavaScript it's a link. Not a router. A router already on the Navigation API (Baseline since January 2026) needs none of it. Browser tests with a hand-written router, React Router and Vue Router.
  • Form libraries: a Zubra control as a field. @zubra/runtime/forms turns what a form library hands you for a field into a control's props: React Hook Form (registerProps(register('seats')), and fieldProps(field) in a <Controller>), TanStack Form (fieldProps(field)), VeeValidate (vueFieldProps(useField('seats')), or a <Field> slot's field) and Felte (felteControl, a Svelte action that keeps Felte's hidden input in step, numbers as numbers). Changes are reported through the control's model pair ({ prop } for one that isn't value), focus leaving the control is a blur, and the library's reset() reaches the control. Nothing imports a library. A browser test runs each library against the same stepper: change, blur, validation, submit and reset. Angular forms keep zubraModel.
  • Context from the app: <zb-context> and ZubraContext. Components already read context with inject(); now the app can provide it. @zubra/runtime/context defines <zb-context>, a display: contents element that answers the Context Protocol for the elements inside it with its value (a value or a signal, followed either way) for its context key. React and Vue get a ZubraContext component (<ZubraContext context={theme} value={mode}>); Svelte, Solid, Angular, Lit and plain HTML set the element's two properties. Consumers that asked before it had its key ask again when it announces one, and nested providers answer for their own subtree. Lit's @consume is answered too. Browser tests in plain HTML, React 19, React 18 and Vue 3.
  • Signal bridges: state shared by elements and the app's own code. @zubra/runtime/bridge has subscribe(signal, callback) and toStore(signal), a store that is at once the Svelte store contract ($cart, and writable for bind:value), an RxJS-style Subscribable (Angular's toSignal, Solid's from) and an interop observable (RxJS from). React gets useSignal(signal) (on useSyncExternalStore, so concurrent-safe and server-safe) and Vue gets useSignal(signal), a ref that writes the signal when assigned. Any Signal.State or Signal.Computed works, or a function of them; { deep: true } also follows mutations inside an array or object. A browser test runs one store through an element and React 19, React 18 and Vue 3 code, each writing and each seeing the others' writes. docs/what-crosses-the-boundary.md and the consume skill have the table.
  • A page listing what JavaScript runs where (docs/javascript-support.md, on the docs site under Reference): what the compiler, the browser and the server each do with a component's JavaScript, every built-in the server evaluates, and what it leaves for the browser and why. A test checks the page against the server's V8 comparison both ways, so it can't list a built-in that isn't tested or miss one that is. zubra check --server's help links to it. Object.values, .lastIndexOf, .endsWith, .trimEnd and Boolean() were evaluated but untested; they now have cases.
  • TypeScript enums. enum in <script lang="ts"> (and at the top of a .zb.tsx file) was refused; it's now lowered in place to what TypeScript writes, with the same number of lines so every line after it keeps its number: an object literal when every member is a constant (const Size = { Small: 0, "0": "Small", … };), TypeScript's own statements when a member is computed or the enum is declared twice. Values are worked out as TypeScript works them out (auto-increment, constant arithmetic and bitwise expressions, strings, template strings, earlier members, other enums), and a test runs each kind through both the compiler and tsc and compares what they do.
    • An enum as a prop's type. export enum Size { … } is exported by the element module (--emit js and --emit element), declared in the typings as export declare enum, and re-exported by the React and Vue wrappers, so import MyBox, { Size } from './my-box.zb?react' works. A default of Size.Medium types the prop as Size. A prop typed with an enum the component doesn't export is an error when the enum has a string member (no consumer could pass a value TypeScript accepts) and a warning when it has only numbers.
    • Enum attributes. An enum prop's attribute takes a member's value or its name: size="5" and size="Large" both set 5; anything else keeps the default, with a warning listing the members. The runtime, --emit element, server rendering and --props all read the same forms. The manifest records an exported enum as a variable of the module with its values, the prop's type references it, and --emit html-data lists the members for the editor's attribute completion.
    • Enums from other modules. For an enum imported from a relative TypeScript module (re-exports followed; ./x.js meaning ./x.ts), the compiler reads its values. A const enum, which TypeScript erases, is inlined: the component gets its own const Size = { … }; in place of an import that would fail in the browser, and one the compiler can't work out is an error at the import. @zubra/compiler sends a TypeScript component's TypeScript modules to the WebAssembly build. Imports from packages aren't followed.
    • zubra convert turns an exported enum in an element back into export enum, and the enum prop's default back into its member.

Fixed#

  • Sync: a device never shows an older change over its own newer edit. Three windows, each found by the long-offline test failing now and then, each now reproduced every time by its own test: a change from elsewhere merged while this device was still storing its edit's clock (it saw no clock, won, and stayed on screen); a change being stored when the device edited the same field (shown after the edit); and a tab closed with writes still queued, which could leave the stored value or its clock behind what the outbox held, so the reopened page showed the old value (and on another device the new one). Edits are now remembered the moment they're made, a change is checked again before it's shown, and on start the outbox is replayed into the store wherever it's newer. The server always had the right value; the device showing the wrong one stayed wrong until that field changed again.
  • Sync: a device offline for hours queues one change per field, not one per keystroke. The queue of changes waiting to be pushed kept every edit, and rewrote all of them to localStorage on each one, so a long session of typing offline grew it without bound until localStorage refused it, and from then on a closed tab lost the edits. A newer change now replaces what's waiting for the same field (this device's later write would win anyway); a queue saved before this loads that way too. Proved in a browser: a long offline session, the tab closed before the network came back, another device writing meanwhile, and the app opened again.
  • Actions: processes starting together each find every action. Each start rewrote the compiled server halves in the shared cache folder, so a second process starting at that moment (another worker, a parallel test file) could import a half-written file, find no actions, and answer every post with 404. They're written beside it and renamed into place now. This was the Fastify adapter test that failed now and then in CI.
  • class: and style: on a child component set its host element, as on any element, in both outputs. They were refused as unknown props (<quantity-stepper class:out={…}>: "has no prop class:out"). Found by Tailgate.
  • Server rendering: an object with an undefined field is left for the browser. The server dropped the key, so Object.keys({ a: undefined, b: 1 }) read b there and a,b in V8; JSON can't hold the key, so the expression now renders in the browser.
  • Server rendering: the ES2019–ES2024 array and object methods. .findLast, .findLastIndex, .toSpliced, .with, .flat and .flatMap, and Object.fromEntries, Object.groupBy and Object.hasOwn, now render on the server instead of leaving an empty region for the browser. An object's keys now come out in JavaScript's order (index-like keys first, ascending), for object literals too, so Object.keys({ b: 1, 2: 2 }) reads 2,b on the server as in V8. What the browser would throw on (.with out of range, Object.hasOwn(null, …)) or that JSON can't hold (.flat(Infinity), an entry with no value) is still left for the browser. Each is in the differential test against V8.
  • TypeScript: an import used only as a type no longer reaches the browser. TypeScript, esbuild and Babel drop an import whose names a module uses only in types, even without import type; Zubra kept it, so import { Option } from './types' (an interface) made the browser refuse the component's module, and every module importing it, because ./types has no runtime export named Option. Such names are now dropped from the module, and the import with them when nothing else is left, unless the host or the template reads them ({Size.Large}). The typings still import them as types. An import the script never mentions is kept, for the template or for its side effects. Both front ends, .zb and .zb.tsx.

5.7.0 — 2026-11-11#

Sync grows up for real apps, from what CineStack, the kit and Tailgate found: a page subscribes to only what it shows, and a server can impose that scope for tenancy by key prefix; a log can keep each field's latest value instead of every change; a device whose cursor is past the end of a replaced log starts over; a returning visitor sees what the log has now rather than what their device stored last time; and a field a component doesn't declare is now a tested guarantee. The editor also stops marking every file red when it can't find the compiler.

Added#

  • Sync: a page asks only for what it shows. connect({ scope: { seats: 'showing-12/', brands: true } }): per collection, true or a key prefix (or a list of them). Pull, the live stream and presence send nothing outside it, so a page's store holds only its own documents, and each scope keeps its own cursor. createSyncServer({ scope({ request }) }) imposes one from the server, which a page's can only narrow, and refuses pushes and presence outside it: tenancy by key prefix on one log. The zubra-sync binary honours a page's scope. Found by CineStack, where every guest's phone received every seat in every showing.
  • Sync: a log that keeps each field's latest value. sqliteLog(path, { keep: 'latest' }), and the same option on memoryLog and durableObjectLog: a newer clock replaces a field's row and takes the next cursor, an older one is dropped, so the log doesn't grow with every change and a new device reads what's there now. Opening an existing full log this way carries each field's latest value across, after the old cursors. The SQL logs now share one implementation. Found by CineStack, where seats are held and released all evening.
  • Sync: a field a component doesn't declare is a guarantee now, documented and tested on both servers: a server-written field with no let (the kit's hold since) is kept on the device and in the log through the component's own edits.

Fixed#

  • Sync: a returning visitor sees what the log has now, not what their device stored last time. On a connected page, a component waits for the first pull (at most 1.5 seconds, and not at all once it fails, as it does offline) before applying its stored document. Before, a stored value showed until the pull landed: a seat that had been taken since the last visit showed free. Found by CineStack.
  • Sync: a device whose cursor is past the end of the log starts over. When the log was replaced or wiped, a device that had read far into the old one heard nothing until the new log passed its cursor. Pull and the live stream now answer it from the start, with reset: true, and the device takes the new cursor. Logs gain head() (the built-in ones and the zubra-sync binary have it; it's optional for your own).
  • The editor no longer marks every .zb file red when it can't find the compiler. "couldn't run the compiler zubra (ENOENT)" was an error at line 1 of each open file, though nothing was wrong with them. Now it's one warning, and the language server looks in more places first: a cargo build in a zubra checkout (target/debug or target/release, as @zubra/server already did), the @zubra/compiler nearest the file rather than only the workspace's (an example app with its own node_modules), and on Windows the zubra.cmd npm installs, which spawning without a shell never ran. A compiler built or installed afterwards is picked up without reloading the window.

5.6.0 — 2026-11-11#

Sync and Actions on Cloudflare Workers, and five fixes found by building a real app on Zubra (Tailgate, a farm-to-door marketplace): the Sync server can read and write documents itself; a Durable Object holds it on Workers (@zubra/sync/durable), with the log in the object's own SQLite; server functions are built ahead of time for the edge (zubra-actions build, @zubra/actions/edge); and the standup board runs on a Worker in CI. On the server, an unsafe URL from a value is now left out and reported instead of failing the render, rendered components go inside slots, nested form controls submit before JavaScript, and hydrated() is false.

Added#

  • The standup board on a Cloudflare Worker (examples/edge/standup-worker), the proof for Sync and Actions on Workers: its Sync server is a Durable Object, its "Lead today" form posts to a server function that races through the object, and its pages come from @zubra/server/edge. A CI job runs it in workerd with two browsers (the page before JavaScript, typing and presence, two people racing for the lead, the form without JavaScript, the log surviving a restart) and runs Sync's log contract inside a Durable Object. docs/edge.md has the section.
  • Actions on Cloudflare Workers: @zubra/actions/edge and zubra-actions build. A Worker can't compile a components folder when it starts, so zubra-actions build components --out src/actions writes the server functions as plain modules for the bundler, and createActions({ actions }) from @zubra/actions/edge answers posts exactly as the Node entry does: both now run the same request handling (core.js), and a test sends each the same posts (plain and enhanced, errors, redirects, cross-site, unknown) and compares status, headers and body. context gets fetch's second argument, so a Worker's env reaches server functions. docs/actions.md has the page.
  • Sync on Cloudflare Workers: SyncObject and syncStub in @zubra/sync/durable. Extend SyncObject for a Durable Object that holds the sync server (one per app, its log in the object's SQLite) and asks your authorize; the Worker's syncStub(env.BINDING) forwards /_zb/sync/* to it, reads a copy of the documents for rendering, and writes as the server. What must not interleave (the last item, a job two drivers claim) goes in the object's own methods, which the stub calls over RPC. A page whose connection is cut leaves its presence rooms within about three keep-alives (2 s each here): a Durable Object only learns it's gone when it can't write to it. documents() gains collections(). docs/sync.md has the page.
  • A sync log in a Cloudflare Durable Object: durableObjectLog(ctx.storage) from the new @zubra/sync/durable. The same table and cursors as sqliteLog, over the object's own SQLite, one transaction per batch; table names it if the object keeps tables of its own. Every log Sync ships now passes one contract (order, cursors and paging, JSON values, a failed batch adding nothing), and the edge example runs it on workerd's storage. The first part of Sync and Actions on Workers (plan/roadmap-durable-objects.md).
  • The Sync server can take part: sync.documents() and sync.write(). documents() is every document as the devices merge it, kept current, with synchronous reads; write(collection, key, fields) writes as the server, with a clock later than any it has seen, to the log and every live page. A server action can now check and decide what two people both want (the last item, a job two drivers claim) and every page showing it follows. Tailgate wrote these 40 lines itself; they're in @zubra/sync/server now.
  • authorize is told what kind of request it is: kind is 'change', 'presence' or 'read'. A rule that kept a collection the server's alone used to refuse joining its documents' presence rooms too, since both are writes; now it can tell them apart. write is unchanged.

Fixed#

  • zubra check --server points at the right place for a gap inside a child component. It reported the child's line and column as if they were the parent file's, often landing on a CSS rule. Now the warning is at the child's tag in the parent and says where in the child it is: inside <user-avatar> (user-avatar.zb:26:60): …. Found by Tailgate.
  • hydrated() called in a template is false on the server, as const live = hydrated() already was. <zb-if test={!hydrated()}> rendered nothing on the server, so the no-JavaScript fallback it guarded was missing exactly when it was needed; !hydrated() || … and hydrated() && … are decided by it too. Found by Tailgate.
  • A form control inside another component submits before JavaScript. A form-associated child with a name (a quantity stepper in an order form) now carries a hidden input with its rendered value, as one under a framework's SSR bridge already did, so a form posted without JavaScript sends it. The element removes it when it starts. Before, the server rendered nothing for the form to send. Found by Tailgate, whose order form submitted no quantity without JavaScript.
  • A rendered component can go inside another's slot on the server. page.render('frame', props, { default: page.render('chart', …) }) failed with "doctype and processing instructions are not supported": slot HTML is kept as written, but since 5.0 the hydration markers are processing instructions (<?zb [?>), and only comments were kept. Processing instructions are kept now, so both components render on the server and hydrate. Found by Tailgate's dashboards (charts inside dashboard-shell).
  • An unsafe URL from a value no longer fails the server render. A computed href, src or srcset that isn't safe (a user's javascript: link, a data: image) is left out of the HTML, as the element leaves it out in the browser, and both say so: the browser in the console, @zubra/server through a new warn option (console.warn by default), naming the attribute and the start of the value. Before, @zubra/server threw, so one bad value took the whole page down. Unsafe literal URLs are still compile errors. Found by Tailgate, where a farmer's uploaded logo returned a 500 for the market page.

5.5.0 — 2026-11-10#

Motion, and six lines of work reviewed and released together: content that leaves instead of vanishing; Zubra on Cloudflare Workers; a Rust crate and a Python package for servers that aren't Node; spread onto components; Extract to component and Format Selection in the editor; a Prettier plugin; and pages for Angular, Vue, Svelte and React developers.

Added#

  • Motion: animate on <zb-if>, <zb-switch> and a keyed <zb-each>, and zb-animate beside an element's zb-if. Content going away stays with data-leaving and inert until the transitions and animations that starts have ended (infinite ones aren't waited for), beside what replaces it; keyed rows that stay glide to their new places (FLIP, with the Web Animations API, timed by --zb-move-duration and --zb-move-easing), and removed rows leave held where they were on screen, out of the flow (even in a list anchored to the bottom, which shrinks from the top). Coming in is left to CSS (@starting-style). Under prefers-reduced-motion: reduce, nothing waits or glides. Both outputs have it: @zubra/runtime and --emit element (its leave and glide helpers, written only when a component animates), and zubra convert reads them back as animate. The same functions are leave() and glide() in the new @zubra/runtime/motion, which a compiled module imports only when its component animates (the runtime's own hooks are about 160 B, and its size budgets rise by 0.5 KB for them). animate without a key, with a value, or zb-animate anywhere but beside zb-if are errors that say what to write. Tested in the browser on both outputs, including reduced motion.
  • Zubra for Angular developers (docs/guide/for-angular-developers.md, in the docs site's navigation): a translation table (signals, @if/@for, output(), model(), ng-content), how to use a component from an Angular app with ZubraModel and formControlName (its code is quoted from the angular-booking example, and the guide-pages check fails if they drift), each claim linking the test that checks it, and what doesn't cross, including that templates aren't type-checked and Angular's own SSR is untested.
  • The Vue, Svelte and React guide pages now have the same four parts as the Angular one: the translation table, how to use a component from your app (quoted from vue-budget, svelte-flashcards and react-board through marked regions, checked by guide-pages), each claim linking the test that checks it, and what doesn't cross for that framework, ending with the survey question.
  • A check that the "Zubra for … developers" pages match the code that runs in CI (docs/test/, a guide-pages job). A code block that says where it comes from (<!-- snippet: examples/frameworks/vue-budget/src/App.vue#name -->) must equal the zubra-snippet:start name … end name region of that file; links must resolve; and every framework page has the same sections (translation table, using a component from the app, what you get with each claim linking its test or example, what doesn't cross, and the survey question). No page uses it yet: the Angular page and the revised React, Vue and Svelte pages follow.
  • The repository is formatted with zubra fmt, and CI checks it (zubra fmt --check . in the Compiler job). The reformat is one commit, listed in .git-blame-ignore-revs so git blame skips it (git config blame.ignoreRevsFile .git-blame-ignore-revs). Every component compiles the same before and after.
  • Range formatting. Format Selection in editors (and format on paste) formats the lines the selection touches, and nothing else: the edit is cut from the whole file's formatting, so the depth and line widths are the file's, not a fragment's. In the request API, command: "formatRange" with start and end (bytes) answers { "edit": null | { start, end, text } }; in Rust, format_range. The language server advertises documentRangeFormattingProvider; a compiler without the command is told to update. Tested over every component in the repository: the text outside the edit is unchanged, what the component compiles to is unchanged, applying the edit twice changes nothing, and the range of the whole file is the whole format.
  • <!-- zubra-fmt-ignore --> as a file's first line leaves it exactly as written, in zubra fmt (and --check), Format Document, Format Selection and the Prettier plugin. It's read before the file is parsed, so a fixture that is malformed on purpose can carry it.
  • prettier-plugin-zubra: Prettier for .zb files. The template is laid out by zubra fmt (the plugin calls format() from @zubra/compiler, at zubra fmt's line width of 100 by default instead of Prettier's 80, so a file Prettier has formatted passes zubra fmt --check), and the <script> and <style> bodies by Prettier with your configuration: JavaScript, TypeScript (lang="ts"), CSS, SCSS and Less, indented one level inside their tag, template literals untouched. A body that doesn't parse or has no parser is left as written; embeddedLanguageFormatting: "off" leaves all of them. Its tests format every component in the repository and check it compiles to the same JavaScript and CSS (ignoring only what Prettier chooses: whitespace, quotes, semicolons, trailing commas). Not published yet.
  • {...object} onto a Zubra component. <ui-button {...rest}> no longer needs every prop written out. The entries that are the child's props (isOpen or is-open) are passed as props and checked like written ones, the rest become attributes and listeners of its host, as on any element. A prop written on the tag wins over the spread's, in either order; null, or a key that goes away, puts the prop back to the component's default, on the server and in the browser alike; of two spreads the later one's value wins; and a spread may give a required prop (one known only in the browser isn't asked for it at build time, one known at build time must have it). A spread known at build time renders on the server; one known only in the browser leaves the child to render its defaults until it runs. Also in JSX components, and zubra convert no longer reports "spreading onto a component isn't converted"; the rest of the props spread onto a returned component (<Button {...props}>) are reported, not dropped, since they would be that component's props. Still an error on the host tag and on directives.
  • The bike shop on a Cloudflare Worker (examples/edge/hono-bikes-worker). The Hono + htmx shop's routes moved into src/shop.js, which reads no files, so the Node.js app and a Worker share them and the same four components. A test runs the Worker in workerd (wrangler dev --local) and compares status, redirects and HTML to the Node.js app's for lists, searches, pages, fragments, selling and edit errors, byte for byte. docs/edge.md has the setup and the measured bundle size.
  • @zubra/server/edge: the server on Cloudflare Workers. createZubra({ wasm, components: { 'price-tag': source } }) takes the compiler's WebAssembly module and the components' sources instead of a components folder, and returns what the Node entry does (render, page(), head(), scripts(), module(), describe(), injectShadowRoots(), fetch() for the browser modules), with the same output: a test compares the two entry points on the same components, nested relative imports included, down to the streamed page. page().streamResponse() streams as a web Response; stream() (a Node Readable) stays on the Node entry. The runtime isn't served from here (a Worker has no disk to serve it from): put @zubra/runtime in your static assets under <prefix>/runtime/, or point the import map at a CDN with imports. @zubra/server/hono-edge is the Hono middleware over it. Components in a Worker are text imports (a Text rule for **/*.zb in wrangler.jsonc).
  • @zubra/compiler/wasm: the compiler without a host. createCompiler(wasm) returns { request, render, renderToString, format } over the WebAssembly module you give it (a WebAssembly.Module, an instance, or its exports), and reads nothing: no file system, no process, no import.meta. That is what Cloudflare Workers, Deno and browsers need, since @zubra/compiler itself loads zubra.wasm from disk at import time, which a Worker can't do (the edge probe in examples/edge/probe shows the failure and the fix). In a Worker, import wasm from '@zubra/compiler/zubra.wasm' gives the compiled module (the package now exports that path). render takes the sources as files, since there is no disk to read them from. The Node entry is this one plus the disk loader, so there is one implementation of the request glue, render and format; its behaviour is unchanged, and a test renders every registry component through both and compares the results. Also exports CompileError and the marker constants, the same ones.
  • The zubra Python package (clients/python, version 0.1.0, versioned on its own): the Flask example's zubra.py as a package. Zubra(folder) keeps one zubra serve process (restarting it if it dies, with a lock for threads) and gives Page.render, Page.head() and Page.scripts(), css() and js(); zubra.jinja.install() adds zubra(), zubra_head() and zubra_scripts() to a Jinja environment. It finds the compiler from compiler=, $ZUBRA_COMPILER, a binary bundled in the wheel, then the PATH. scripts/build_wheel.py assembles a platform wheel (manylinux_2_35, musllinux_1_2, macosx, win_amd64) from a release archive, standard library only. The Flask garden now uses the package and its garden/zubra.py is gone; its tests are unchanged. Not on PyPI yet.
  • A Rust server example, examples/backends/axum-garden: the Flask garden's pages and .zb files from an Axum binary, with include_zb! checking the components at build and Component::render writing the HTML in the server's own process (no Node.js, no child process). Its test fetches every page from both servers and requires the same HTML (and byte-identical browser modules); CI runs it beside the Flask suite.
  • zubra-macros: include_zb!("components/price-tag.zb"), for Rust servers. A procedural macro that compiles the component (and every component it imports) during cargo build, so a broken .zb fails the build with Zubra's message, file and line, and expands to a zubra::Component with the sources embedded (include_str!, so editing any of them rebuilds the crate; paths are relative to the crate, not the build machine). Not published yet (publish = false).
  • zubra::Component, the Rust API for servers: a component and the sources it imports, held in memory, with render(&props) (partial server HTML, like @zubra/server), render_with (slots), css(), module() / module_for(runtime), tag() and check(). It resolves relative imports from the map, so a Rust server needs no disk, no Node and no child process. The crate documentation now lists the supported surface (Component, Diagnostic, compile_html_with_options, compile_js_options, compile_css, format, handle_request); the older entry points that take JSON strings are hidden from the docs, not removed.
  • Prebuilt zubra binaries on every release: Linux (glibc and static musl, x64 and arm64), macOS (Intel and Apple silicon) and Windows, each with the licence and readme, and a SHA256SUMS file uploaded last. Built from the release's tag by release.yml, started once the release exists and skipped when the release already has its checksums (so a failed build can be re-run). It's how a Flask, Rails or Laravel app gets zubra serve without Node or a Rust toolchain. scripts/package-binary.sh builds an archive; its test runs in the Compiler job. The first release to carry them is the next one.
  • Extract to component in editors. Select whole sibling nodes of a template and the language server offers the code action Extract to component (any LSP editor): a new .zb file beside the current one, <new-tag …> in place of the selection, and the import. When the compiler refuses the selection, the action shows disabled with the reason. It's offered only to an editor that said it can apply an edit creating a file (and a disabled action only to one that knows them), and a name whose file already exists is refused before any edit. The VS Code extension adds Zubra: Extract to Component…, in the palette and the context menu, which asks for the name (the code action uses a default). A compiler from before the command is told to update, not trusted.
  • command: "refactor", action: "extract" in the request API: markup to a new component. Give it a file, the byte range of whole sibling nodes in its template and a tag, and it answers with the new component's file and the edits to the current one (the selection becomes <new-tag prop={prop} onevent={handler}>, and the import is added). What the selection reads from outside becomes a required prop; a function of the component used as a whole handler (onclick={remove}) becomes an event the new component fires with emit and the parent listens to; names the component imports are imported again. It refuses, with the reason, a selection that assigns to the component's state (count++, value:bind={count}), contains a <zb-slot>, uses a function other than as a whole handler, fires the component's own events, splits a zb-if/zb-else or zb-await chain, holds markup that only works inside its parent (<option>, <tr>), or sits in a shadow DOM component. The selection is checked against the file itself: one that starts or ends inside a tag, a comment, a {…} expression, a word or a <textarea> is refused (parsed on their own, an attribute's value or a string in an expression can look like markup). Also refused: content placed in a slot (slot="title"), a handler function that takes the event as its argument (as a listener on the new component it would get that component's event), a function or browser-only value that would have to be a prop the server can't pass, and a tag that is Zubra's own or already used. A zb-each item's name is the loop's only inside the loop; an import brings in the names it binds, not any word in it; and what the browser provides (setTimeout, fetch, localStorage) isn't a prop. What would be written is compiled before it's offered: a component that compiled still compiles, and one that rendered on the server still renders. <pre> and <textarea> content is moved exactly as written. What it writes is laid out as zubra fmt would lay it out (the new file, and the lines of the edited one that the new tag is on) and in the file's own line endings, so a repository that runs zubra fmt --check doesn't fail on a refactoring its editor offered. No CSS moves: descendant rules still apply, but a rule or layout that depends on the selection being a direct child sees the new element instead. In the tests, every subtree of every component in the repository is extracted, and so are thousands of arbitrary selections (inside tags, comments, expressions): each is refused, or both files compile and the page is the same apart from the new tag. The language server offers it as a code action and VS Code has a command (below).

Changed#

  • zubra fmt keeps a file's line endings. A file with CRLF line endings stays CRLF (the first line break decides); it used to be rewritten with LF, so on a Windows checkout zubra fmt --check called every file unformatted. Format Selection's edits use the file's line endings too, instead of putting bare LF into a CRLF file.
  • @zubra/server is built on a shared core.js. Everything that doesn't need a disk (rendering, CSS, browser modules, a page's head and scripts, streaming, shadow roots) moved out of index.js into a file that imports nothing from Node; index.js adds the folder walk, the runtime from disk, writeAssets and the Node streams. Behaviour is unchanged and the existing server tests pass untouched; streamResponse() now builds its web stream directly rather than converting a Node Readable.

Fixed#

  • The docs no longer say Svelte's bind: works on a Zubra element. Svelte 5 refuses bind:value on a custom element at compile time; the Svelte page, docs/what-crosses-the-boundary.md, the framework matrix and the README now show the prop with its on<name>change event, which is what the flashcards example does.
  • The Angular example and npm create zubra's Angular template type-check their .zb imports ("types": ["@zubra/unplugin/client"]): TypeScript 6 reports an unresolved side-effect import.
  • Format Selection no longer fails on a position inside a multi-byte character. formatRange (and zubra::format_range) sliced the file at the offset it was given and panicked when that fell inside a character such as é or an emoji; the editor then said the compiler was too old. An offset inside a character now counts as the character's start.
  • A streamed page works from a bundled server. The two scripts page.stream() and streamResponse() put in the page were the server's own functions, stringified; a bundler rewrites those for the server it builds (esbuild's keep-names, which Wrangler turns on, wraps an inner function in a __name() helper that exists only in the bundle), and the page threw in the browser. They are now kept as text. A test bundles @zubra/server/edge the way Wrangler does and compares the page.
  • Markup nested more than 256 elements deep is a compile error, in a template and in slot content, instead of a stack overflow: natively a crash, and in the WebAssembly build a trap that left the compiler failing every request after it, for as long as the process or the Worker's isolate lived. Slot content is the page's HTML, so this could be reached from a request.
  • @zubra/compiler starts a fresh WebAssembly instance after a trap. The request that trapped throws a CompilerCrash (new, exported from @zubra/compiler and @zubra/compiler/wasm); the next request is answered. createCompiler() can do this when it's given a WebAssembly.Module; given an instance, it throws CompilerCrash from then on instead of raw traps.
  • zubra::Component (and the request API) resolve imports for a component whose path has no directory. Component::new("card.zb", …), which is what include_zb!("card.zb") writes for a component beside Cargo.toml, looked for ./badge.zb at /badge.zb: the build passed and every render failed with "not among the component's imports". A request whose path was a bare file name failed the same way.
  • The Python package can't hand one request another's HTML. A request that was interrupted after it was sent (a thread interrupted, or now a timeout) left its answer in the pipe for the next caller. Whatever ends a request early now ends the compiler process too, under the lock, and the next request starts a fresh one. New: Zubra(…, timeout=30.0); a compiler that isn't there, can't run, exits, or answers with something that isn't JSON is a ZubraError that says what to do.
  • Linux wheels of the Python package are built from the static (musl) binaries and tagged manylinux_2_17 and musllinux_1_1, so they install on RHEL 9, Amazon Linux 2023 and Debian 11. They were tagged manylinux_2_35, the glibc of the machine that builds the glibc binaries.
  • include_zb! reports one error, not two, when the component doesn't compile (the second was about a stray ;), and takes a literal passed on by another macro (macro_rules! page { ($path:literal) => { include_zb!($path) } }).
  • The release workflow: the jobs that build the binaries hold no publishing or release-writing token (each job now asks for its own permissions); a release tagged before binaries existed is skipped instead of failing the job on every push; and the Windows archive is uploaded by a path the upload step can open.
  • scripts/bump-version.sh updates the Axum example's own lockfile and the version zubra-macros asks of zubra (now exactly the release's). The example's cargo test --locked failed after any version bump.

5.4.1 — 2026-11-09#

The VS Code extension's language server starts, so .zb files have a formatter (and diagnostics, completion and hover) in VS Code. And the Zubra DevTools in the demo gallery, on the playground, and in builds when you ask for it.

Added#

  • The Zubra DevTools in builds, when you ask for it. zubra({ devtools: true }) in @zubra/unplugin, devtools in createZubra() (on by default outside production) and in buildLibrary(), or ZUBRA_DEVTOOLS=1 for all three. Components are compiled for the extension and @zubra/runtime resolves to its development build, which has the hook. Production builds still leave it out unless asked. The demo gallery builds with it, so the extension works in every live demo, and the gallery test checks that it does.
  • Zubra DevTools on the playground. The previews are compiled for the DevTools extension, so you can try it without a project: open the playground, select an element in a preview, and the Zubra pane shows it; clicking a line selects it in the playground's editor. The page's own __ZUBRA_DEVTOOLS__ passes the pane's calls to the preview frames, and the pane now reads the hook of the frame the selected node is in. The runtime's open() lets a page handle a location itself (a cancelable zubra:open event) before asking Vite.

Fixed#

  • The VS Code extension's language server starts. The extension looked the server up as @zubra/language-server/package.json, which that package's exports map doesn't allow, so activating threw before the server began: .zb files had no formatter ("There is no formatter for 'zubra' files installed"), and no diagnostics, completion, hover or go to definition either. It now resolves the package's own entry, and starts it as a Node module, which VS Code forks with ELECTRON_RUN_AS_NODE=1 (as a command, process.execPath is the editor's Electron binary). A test activates the extension and starts the server the way the client does.

5.4.0 — 2026-11-09#

The output you learn from: --emit element writes the custom element you'd write by hand, zubra convert takes one back to .zb, and the playground shows it. And Zubra DevTools, a pane in the browser's Elements panel.

Added#

  • zubra fmt: lays .zb files out consistently (indentation by nesting, tidy tags, one attribute per line for a tag too wide for its line) without changing what they compile to: it only touches whitespace that renders as one space, and leaves expressions, comments, attribute values, <script>/<style> bodies and <pre>/<textarea> as written. Files and folders, --check for CI, --stdin for editors, --indent, --tabs, --width. Also format() in @zubra/compiler, command: "format" in the request API, and zubra fmt in the npm CLI. Every component in the repository is formatted in the test suite and compiles the same.
  • Formatting in editors. The language server answers Format Document with zubra fmt's layout and the editor's indentation (tab size, tabs or spaces), so it works in any LSP editor. The VS Code extension makes it the default formatter for .zb (format on save with editor.formatOnSave), and adds zubra.format.printWidth. With a compiler from before this release it says once that formatting needs 5.4 and changes nothing.
  • An Element tab in the playground, next to Preview: the component as --emit element writes it, or why it's refused. The JavaScript tab is now called Runtime module, which is what it shows and what the preview runs.
  • npm run pack in editors/devtools makes the store zip with Node alone (no zip program, which Windows lacks): manifest.json at its root, the same bytes for the same files.
  • --devtools (and devtools: true in requests), for development builds: each part of the compiled module records where it was written in the .zb file (at: [line, column]), the definition records the file and its host tag's place (source), and setup hands the runtime the script's signals by name. It's what the browser DevTools panel reads; without the flag the output is unchanged, byte for byte.
  • globalThis.__ZUBRA_DEVTOOLS__, in the runtime's development build: what the browser DevTools panel reads. inspect(node) gives the node's component (its .zb file and line), its props and state by name with their values, its bindings as the DOM operations they perform (textContent = …, classList.toggle('done', …), addEventListener('click', …)) with each one's source line and the named signals it depends on (looked up through Signal.subtle.introspectSources, so items[0].done rather than an internal signal), what a parent binds onto a child component, and the last update: what was written and which bindings re-ran. Recording is small and always on in development (the size budget for src/index.js went from 14 KB to 14.5 KB, gzip); the reading side loads when the extension calls connect(). The production build has none of it: dist/production is byte for byte what it was.
  • @zubra/unplugin compiles for the DevTools in Vite's dev server (--devtools), where it already sets up hot reloading. Builds are compiled as before.
  • Zubra DevTools (editors/devtools), a browser extension for Chrome, Edge and Firefox: a Zubra pane in the Elements panel showing the selected node's component (with Open in editor at its .zb line, through Vite's /__open-in-editor), its props and state, its bindings with the signals they read, what a parent binds onto it, and the last update. Manifest V3, no permissions or content script: it reads the page with inspectedWindow.eval. Load it unpacked for now (its README says how); scripts/bump-version.sh keeps its version the project's.
  • zubra convert my-element.js: a custom element back to a .zb component. It reads the shape --emit element writes (one you compiled and changed, or one written by hand that way) and undoes the emitter: props from static zubra or observedAttributes and #props, the script as written (element.count is count, state(0) is let, hooks imported again), each bind() back on its node as an attribute, class:, style: or text, listeners as on… with their modifiers read back, list()/when()/slots as <zb-each>/<zb-if>/<zb-slot>, and the stylesheet unscoped. Every component --emit element accepts (61 in the registry and the runtime's tests) converts back to a .zb file that compiles to the same element, and a test checks that. What it can't place is reported with not converted: at its line.
  • service-status, a registry component (npx zubra add service-status): a service's status from a JSON endpoint, with "Checking…", the status and its message, the error with Retry, and Refresh that keeps the last answer showing. It's the registry's first zb-await, so the stripped-markers suite now covers a region the server leaves to the element. That suite now compares against the same markup with its markers kept (the same server nodes must survive), since a pending zb-await is re-rendered either way, and it fails if a component warns even with its markers.
  • Server markup with an zb-await hydrates in place without its markers. When a sanitizer has removed the <?zb …?> markers, remark.js now places an zb-await region by structure, as it does zb-if and zb-each: its zb-then block, for a value the server knew at build time, or its pending block, which the element renders afresh anyway. Until now such an element rendered entirely afresh, losing text typed and focus taken before JavaScript.

Changed#

  • A JSX component's --emit element output reads like a .zb component's. Its script was lowered for the runtime first ($p.text, __zubraAssign(…)) and bridged with a $p object; it's now lowered the way zubra convert --as zubra writes it, so the element has element.text, count.value += 1 and emit("change", …). Its text still follows JSX's whitespace rule, and a JSX child component is resolved to its tag.
  • --emit element writes the custom element you'd write by hand. Until now it was the --emit js module with a small runtime ($define, about 750 lines) inlined, which worked but was hard to read. It's now one class that extends HTMLElement: observedAttributes and an attributeChangedCallback that parses each prop's type, a getter and setter per prop, connectedCallback, your <script> as written (props as element.name, state as name.value), the template's changing nodes looked up by position and named after their class, id or tag, and one bind(read, write) line per dynamic spot with the DOM call it makes. Keyed lists, conditionals, light-DOM slots and deep state are small commented helpers after the class, each written only when the component uses it. The output is smaller too: about 2 KB gzipped for a small element (was 5.5 KB) and 3.5 KB with slots (was 7 KB). What it covers and refuses is unchanged, and the runtime's browser suites and the registry's tests pass on it as before.
  • A slot inside zb-then or zb-catch is reported as such. The error said "can't be inside zb-each" wherever the slot was; it now names the branch it's in and says to put the slot outside the zb-await.

Fixed#

  • DevTools: the last update names writes to elements that were on the page before the pane connected. It said "no named writes" for them until they had been inspected once.
  • DevTools: a form control's live state is named as the property the runtime sets (.value = …, .checked = …), not as setAttribute or toggleAttribute.

5.3.0 — 2026-11-09#

Zubra Actions and Zubra Sync: a component's form can post to a server function, with or without JavaScript, and a component's state can live on the device, shared across tabs and devices.

Added#

  • export async function save(formData) { 'use server'; … } in a component script. The function, and the imports only it uses, never reach the browser: its name becomes the URL of its endpoint (/_zb/action/<tag>/<name>), and <form action={save}> (or <button formaction={save}>) gets that URL as a literal action with method="post", in the server HTML and the template alike. Any other export is still an error.

  • --emit server (and emit: "server" in requests): the server half of a component, its server functions with the imports they need, and actions, a map from URL to function.

  • @zubra/actions, a new package that serves them. A post with Accept: application/json gets the return value as JSON; the browser's own post gets 303 See Other back to the page, with the result in a one-use cookie that actions.result(request) reads. Cross-site posts are refused, a thrown error is a generic 500, and a returned Response passes through. actions.script() adds a small module that sends those forms with fetch instead, sets aria-busy while they're in flight, and fires beforeaction (cancelable) and action on the form. A fetch-style core (fetch(request)), Node's handle(req, res), and Hono, Express and Fastify adapters.

  • 'use collection <name>' at the top of a component script. Its top-level lets become the fields of a document keyed by the doc prop (or the props after by: 'use collection rows by list, item'), and the compiled module calls @zubra/sync with them. A key prop the host doesn't declare is a compile error.

  • ephemeral(value) from @zubra/sync: state that isn't stored. The server renders its value.

  • @zubra/sync, a new package: keeps those documents in IndexedDB (in memory without it). Writes are signal assignments, saved behind the UI; an element saves nothing until its document has loaded; elements and tabs showing the same document follow each other (BroadcastChannel). Last-writer-wins per field. configure({ store }) takes another store.

  • @zubra/sync/connect and @zubra/sync/server: share documents between devices through a log over plain HTTP (POST …/push, GET …/pull?since=). Each changed field is stamped with a hybrid logical clock and queued until the network allows; every device applies last-writer-wins per field to the same changes, so they converge. The server keeps the log in order (in memory by default, or any { append, after }), with authorize() for writes and reads.

  • A live channel: GET /_zb/sync/live streams changes as they're pushed (server-sent events); connect() uses it and polls only while it's down. createSyncServer().handle(req, res) serves it on Node.

  • Presence: let cursor = presence(v) is shared live with the document's other viewers and never stored; let others = peers() is the array of them, { peer, ...presence }. Across tabs with no server (BroadcastChannel), and across devices through connect() (POST /_zb/sync/presence and the live stream). At most one message a frame, a heartbeat, a 30-second timeout, and a goodbye on pagehide or a dropped connection. The server renders presence() values and an empty peers().

  • sqliteLog(path) from @zubra/sync/sqlite: the log in a SQLite file, through node:sqlite or bun:sqlite. The live stream now sends a backlog longer than one page whole before anything live.

  • A write could be lost on a slow network. Two pushes can be out at once (the debounce and the poll loop). When they came back, each removed as many changes from the outbox as it had sent, counting from the front, so a change made while they were out could be removed without ever being sent. A push now removes exactly the changes it sent. Found by a CI run where the checkbox change never reached the log.

  • connect({ webrtc: true }): presence over WebRTC data channels between viewers of a room, once they've met; the server carries introductions, goodbyes and signaling (POST /_zb/sync/signal, a signal event on the target's live stream), and presence to anyone without a channel. ICE servers are configurable; TURN is the app's. Both servers support signaling.

  • zubra-sync, a binary (sync-server/, cargo build -p zubra-sync): the sync protocol, live stream and presence included, with SQLite built in and no Node.js. Same table as sqliteLog(); CORS for --origins. The protocol and browser tests run against it too.

  • @zubra/server serves @zubra/sync by itself when it's installed, and maps @zubra/sync and @zubra/sync/connect in the page, so 'use collection' needs no setup. When it isn't installed, the page fails as it's built, naming the component and npm install @zubra/sync; @zubra/unplugin says the same at build time. createZubra({ imports }) adds import map entries for other packages.

  • examples/standup: a local-first team board on plain Node: 'use collection' cards, presence, offline edits, a SQLite log, tested with two browsers.

  • The playground and the docs show both. Two playground examples, "State on the device" (a note kept in IndexedDB through a reload, shared by every preview) and "A server function" (submitting says what would be posted), a Server tab with --emit server's output, and #example=<name> links. Guide chapters 9, Forms that post to the server, and 10, State that lives on the device; the actions and sync pages in the docs site's navigation; and a section on the landing page.

  • Three documentation pages written against a critical reading of the README. TypeScript in .zb files: the erasable-syntax rule, what it refuses and the rewrite for each, and what reaches the typings and manifest. Compared with Lit and Stencil: where each is the better choice, with the one architectural fork (generated per-framework packages against one shared adapter) and sizes measured on the same component. Server rendering, honestly gains the hydration-marker contract, measured: which minifiers keep the <?zb …?> markers as shipped (html-minifier-terser, @minify-html/node), which need one option (@swc/html, htmlnano, with the option), and which strip them (DOMPurify, sanitize-html), leaving the element to put them back by structure. server/test/markers.test.js runs that table in CI.

  • export interface, export type and export type { … } in <script lang="ts">. They're type-only, so the no-exports rule for component scripts no longer refuses them: they're erased from the JavaScript and reach the generated typings exported, as every declaration does. A value export is still an error.

  • ZUBRA_MARKER_PATTERN and ZUBRA_MARKER_DIRECTIVE from @zubra/compiler, for the two minifiers that strip the hydration markers unless told otherwise: preserveComments: [ZUBRA_MARKER_PATTERN] for @swc/html, and the posthtml parser option directives: [ZUBRA_MARKER_DIRECTIVE] for htmlnano. The markers test uses them, so they can't drift from what the tools accept.

  • The README says what Zubra is and isn't: the compiler and runtime are the project; @zubra/unplugin, @zubra/server, @zubra/actions, @zubra/sync, the starter, the editor extension and the registry are optional, separate installs, in one table that says when each is needed. The status line explains what the major version counts.

Changed#

  • Compile errors cite the rule they enforce. A hyphen-less element name points at the HTML spec's definition of a valid custom element name; a valueChange-style event name says that a lowercase name is what on… attributes, Vue's @…, Angular's (…) and React 19 can all listen for; each TypeScript refusal points at docs/typescript.md. (The README claimed minifiers keep the hydration markers; it now says which do, which need an option, and that sanitizers don't.)
  • An unknown directive in a component script gets a warning, with a hint: a likely typo gets "did you mean" ('use colection tasks' → 'use collection tasks'), 'use client' is explained as unneeded, 'use server' at the top of a script is pointed at exported functions, and anything else lists the two directives Zubra knows and the package behind each. 'use strict' is still allowed. It still compiles, as it did (a stray directive was ignored before); 6.0 makes it an error.

Fixed#

  • Text alone given to a light-DOM element whose template starts with a condition was lost. <x-button>Save</x-button>, with a template of <a zb-if={href}>…</a><button zb-else>…</button>, showed the slot's fallback. The page's text matched the whitespace around the template's condition, so the element took its own children for server markup whose markers had been stripped, and "restored" them. Static text in the template now has to match the markup's words for that to happen. Found building Zubra UI's action-button.

5.2.0 — 2026-11-09#

Plain custom elements: a component as one file with no runtime to install.

Added#

  • --emit element: a component as a plain custom element, with no runtime to install. One module, no imports, built from the same definition as --emit js. It covers light-DOM components: props, every template part, zb-if, zb-each, light-DOM slots kept live under React, Vue, Svelte and Lit, state/computed/effect, lifecycle, form association and scoped styles. Shadow DOM, spreads, zb-await and runtime extras such as resource and @zubra/runtime/zag are refused with a reason. Server hydration and hot reload stay with @zubra/runtime. About 5.5 KB gzipped for a small element (the slot code is left out when there are no slots), 7 KB with slots. Also in zubra request ("emit": "element") and @zubra/compiler. CI runs the runtime's browser suites and the registry's tests on both outputs. See docs/plain-elements.md.

5.1.2 — 2026-11-09#

Fixed#

  • A light-DOM component's own fallback lost its styles after slotted content changed. When content was added to or removed from any slot, every node in every rendered slot region was marked as slotted (data-zb-slotted), the fallbacks included. A component's styles stop at slotted content, so a fallback showing again (<zb-slot name="title"><h2>{heading}</h2></zb-slot>) was no longer styled by its component. Only provided content is marked now.

Tests#

  • The styles test that checked "a utility class beats the component's styles" passed only because of that bug: the fallback heading had lost the component's rule. The page in that test now declares the layer order first, as Tailwind's output does, and the test also checks that the fallback keeps its own colour. Found while building --emit element, whose element runtime didn't have the bug.

5.1.1 — 2026-11-09#

Fixed#

  • Vue could break reordering a light-DOM component's slotted list. Vue brackets a v-for (any fragment) with two empty text nodes and moves rows through the start anchor's real parent. When the fragment came right after content for a named slot (<nav slot="side"> then <p v-for>), the start anchor joined the named slot, because whitespace goes with the content before it. A keyed reorder then threw "The node before which the new node is to be inserted is not a child of this node", and the rows kept their old order. Empty text nodes now pair up, and both go with the content between them. Whitespace (Svelte) and comments (Lit) keep their rules. Found by Zubra UI's slot test, which runs React and Vue apps that add, remove, reorder and rename slotted children.

5.1.0 — 2026-11-09#

Dynamic srcset, for responsive images from data (a gallery, a CMS, a manifest).

Added#

  • srcset={…} and srcset="… {expression} …" compile. Each candidate's URL is checked under the same rule as src: on the final value at build time for the HTML output, and on every update at runtime, where one unsafe candidate (javascript:, data:, //host) removes the whole attribute and is reported. An empty value (a prop's "" default) leaves the attribute off, quietly. It used to be the compile error "dynamic srcset is not supported yet". The runtime exports the check as isSafeSrcset.

Fixed#

  • A spread checks srcset too. {...attrs} with an unsafe srcset candidate is refused (in the HTML output, a compile error; at runtime, the attribute is left off and reported). Before, a spread wrote srcset unchecked.

Compatibility#

Output compiled by 5.1 runs on a 5.0 runtime: a 5.0 runtime sets a dynamic srcset without checking its candidates (browsers don't run javascript: from srcset, but update the runtime for the check).

5.0.3 — 2026-11-08#

A documentation site, a landing page, a logo, and the VS Code extension on the Marketplace. Two diagnostics say more, and the language server finds the compiler in your project. No API changes.

Changed#

  • Two diagnostics taught the wrong thing. Assigning to a misspelled name (cnt = 1 for count) is now reported as an unknown name with a did-you-mean, not as "can't be assigned". The "can't be assigned" error says how to fix it. Browser globals such as location = "/" aren't reported as unknown.

Fixed#

  • The language server finds @zubra/compiler in the project you're editing. It looked only beside itself, so in the VS Code extension (where the server lives in the extension's folder) it never saw a workspace's @zubra/compiler and needed the zubra command on the PATH for diagnostics, completion and hover. It now looks in the nearest node_modules above the workspace folder first, then beside itself, then falls back to the CLI.

Added#

  • A documentation site at <base>docs/ on GitHub Pages: the guide, the topics, the README as the reference, the changelog, the migration notes and the standards reports. A link to a file that doesn't exist fails the build, and code is coloured.
  • A landing page at <base>, built with Eleventy with the docs. It shows the real compiler output for one component (compiled when the page is built), the same component written by hand, and the demo gallery. Its own Copy button is a Zubra component.
  • A logo (brand/): the mark, an on-dark mark and a tile, used for the favicon and the docs.
  • docs/guide/08-read-the-output.md: reads one component's real output through nine rules of the platform's custom elements, and ends with "change one line, read the diff".
  • docs/editor-support.md, a file icon for .zb files in the VS Code extension, and the extension as a package: npm run package in editors/vscode builds a .vsix with the published language server in it. It is on the Marketplace as JourneytoCode.zubra.
  • The playground colours the .zb source, the page HTML and the compiled output, and its header links the docs site.

Tests#

  • The hydration-dependent browser tests that flaked (Firefox stripped markup, WebKit's React adapter, SvelteKit workouts) wait for :state(hydrated) before they click.

5.0.2 — 2026-11-08#

Packaging fixes found on the first publish. No code changes.

Fixed#

  • Commands in published packages. npm 11 drops a bin written as "./cli.js" when it publishes. create-zubra, the zubra CLI (@zubra/compiler) and zubra-language-server would have installed without their commands. The bins are now written "cli.js", and a test keeps them that way.
  • @zubra/compiler's tarball on Windows. Its prepack was a node -e one-liner whose filter cmd.exe mangled, so registry/test/ was packed. It's now a script file (compiler/scripts/prepack.mjs), and files excludes registry/test as well.
  • @zubra/compiler can't be packed without zubra.wasm. prepack stops with an error instead of publishing a compiler that can't compile. This was meant for 5.0.1 but missed its merge.

Tests#

  • The stripped-markup hydration test waits for :state(hydrated) before clicking. remark.js loads on demand, and CI could click first.

5.0.1 — 2026-11-08#

A fix for Astro builds, plus the demo gallery and examples with the styling libraries people use. No API changes.

Fixed#

  • Astro: the server build couldn't find zubra.wasm when @zubra/compiler was linked, from a workspace or a file: dependency. Vite bundled the compiler into Astro's prerender chunks, so it looked for zubra.wasm there. The integration now keeps the compiler external in every server environment (resolve.external), including Astro's own prerender environment.

Added#

  • A demo gallery on GitHub Pages (demos/):

    • the playground (now at /playground/);
    • live builds of the static examples;
    • a screenshot of every example, also at the top of each example's README.

    demos/build.mjs builds it, and a CI job checks that every demo loads under the base path.

  • Examples with styling libraries, each with a browser test:

    • examples/frameworks/tailwind-cafe (Tailwind 4);
    • shadcn-invoices (React, shadcn/ui and Radix);
    • mui-clinic (MUI 9);
    • bootstrap-devday (Bootstrap 5 and Sass).

    docs/guide/styling-libraries.md covers how components get an app's styles in light and shadow DOM, for each library.

  • Lockfiles for examples/todo, examples/planner and examples/recipes. The Astro and Eleventy examples now take a DEMO_BASE.

Changed#

  • CI:
    • the gallery check builds with the WebAssembly compiler, as the Pages deploy does;
    • the focus-timer job caches Electron's binary and retries its download.

5.0.0 — 2026-11-08#

The platform's markers (plan/roadmap-5.0.md). The server markup's hydration markers are processing instructions instead of comments. Components and APIs don't change; update the packages together (docs/migrating-to-5.0.md).

Changed#

  • Hydration markers are processing instructions: <?zb [?> … <?zb ]?> for a region, <?zb [??> for a region left to the browser, <?zb [!?> for supplied slot content, and <?zb ?> before dynamic text. They were <!--[-->, <!--]-->, <!--[?-->, <!--[!--> and <!---->.
    • The Rust HTML output, @zubra/compiler's render(), @zubra/server and the framework wrappers' server rendering all write them.
    • Chrome and Edge 150+ parse them as ProcessingInstruction nodes; other browsers parse them as comments (<!--?zb [?-->). The runtime reads both.
    • The runtime still reads 4.x's comment markers, for all of 5.x, so servers and runtimes can be updated in either order.
    • Client templates (the compiled module's template) keep the comment form: the runtime parses them itself.
  • Streaming uses <template for>. A pending region is a named range (<?start name="zb-0-0"?>…<?end?>), and each resolved region arrives in a <template for="zb-0-0">.
    • Chrome and Edge 150+ put it in place themselves, without JavaScript.
    • The inline script hands the element the value, and puts the region in place where the browser didn't: other browsers, and shadow roots, which a <template for> can't reach.
    • An element that starts before its region arrives removes the range's name, so the browser has nothing to replace, and renders the region itself.
    • It replaces 3.3's <template data-zb-swap>.
  • The compiled code's interface is abi: 3. A 4.x runtime refuses 5.0 modules, with an error that says to update it, because it can't read 5.0's markers. The 5.0 runtime still runs modules compiled by 3.x and 4.x (abi: 2).
  • Range positions count elements and markers only. A comment or processing instruction that isn't a marker, such as a stream's <?start>, doesn't shift the paths after it.

Fixed#

  • Streamed regions with content after them. The server took the region's HTML from its opening marker to the end of the host, not to its closing marker. With more than one pending region the swap could put the wrong content in place.

Removed#

  • Workarounds the markers no longer need:
    • the Eleventy example minifies with plain removeComments: true;
    • the htmx example no longer deletes Document.parseHTMLUnsafe, which drops comments in Chromium and keeps processing instructions.
    • ZUBRA_MARKER_COMMENT stays, for a 4.x server's markup.

Tests#

  • runtime/test/browser/markers.test.js: hydration in place from the three marker forms (processing instructions, the comments other browsers make of them, and 4.x comments), and from minified markup.
  • @zubra/server: no-JavaScript streaming in Chromium, and the script's fallback for a shadow root and for markup parsed as comments.
  • The help desk's streamed activity appears without JavaScript in Chromium.

4.3.0 — 2026-11-08#

The rest of the template sugar (plan/roadmap-4.x.md, 4.3). Additive.

Added#

  • let:name={…} on <zb-each> and <zb-then> names an expression for the row or the result:

    <zb-each items={cart} as="{ price, qty }" let:total={price * qty} let:big={total > 5}>
      <li class:big={big}>{total}</li>
    </zb-each>
    
    • It's derived: each read is its current value, so it follows the row.
    • It's read-only: assigning it is the same error as assigning a loop variable.
    • Later let:s can use earlier ones, and the key can use them too.
    • The server evaluates them for values known at build time; a let: the server can't evaluate leaves the list to the browser.
    • On any other element, let: is an error.
  • <zb-switch value={…}> with <zb-case is="paid">, <zb-case is={["shipped", "delivered"]}> and an optional final <zb-else>.

    • The first case whose is equals the value, or whose array lists it, renders.
    • It compiles to the zb-if chain it stands for (===, and || for an array), so known values render on the server and the markers don't change.
    • A quoted is is a string.
    • Errors cover: other content in the switch, a case after the zb-else, no cases, an empty is={[]}, and a stray <zb-case>.
  • Tools and examples:

    • the language server and the grammar know zb-switch, zb-case and let:;
    • the README, the guide's templates page and the skill describe them;
    • the planner's event tabs are a zb-switch.

4.2.0 — 2026-11-08#

Async that reads well (plan/roadmap-4.x.md, 4.2). Additive: every 4.1 component compiles and runs as before.

Added#

  • <zb-pending> names <zb-await>'s pending content. Content written straight inside still works the same way.
  • <zb-await {user}> is short for value={user}.
  • An array value (value={[user, posts]}) waits for every promise and resource in it, as Promise.all does, and resolves to the array of their values. Any rejection goes to zb-catch. The value is evaluated again only when what it reads changes, so a resource settling doesn't call posts() again.
  • Destructuring in as, on zb-then, zb-catch and zb-each, and for the item of .map() in braces:
    • for example as="[{ name }, list]", as="{ message }" or as="{ id, address: { city } }";
    • names, renames, nesting and holes work;
    • defaults and rest elements are errors that say why;
    • each name reads through the row's or the branch's signal, so it stays reactive, and a value known at build time is destructured on the server.
  • retry() in zb-catch refreshes the value's resources and evaluates the value again.
  • delay={ms} shows the pending content only once the value has been pending that long. Until then the previous content stays, or nothing the first time.
  • keep keeps the settled content while a resource reloads, instead of showing the pending content again. The host has :state(loading) meanwhile.
  • Tools and examples:
    • the language server and the grammar know zb-pending, delay and keep;
    • the README, the guide's async page and the skill describe all of this;
    • the help desk's recent activity and the recipe reviews use <zb-pending>, and the reviews retry on an error.

4.1.0 — 2026-11-07#

Conditions without wrappers (plan/roadmap-4.x.md, 4.1). Additive: every 4.0 component compiles as before, unless it has a zb- attribute on an element, which 4.0 silently ignored.

Added#

  • zb-if, zb-else-if and zb-else as attributes:

    <p zb-if={count === 0}>Nothing yet.</p>
    <p zb-else-if={count < 5}>A few.</p>
    <ul zb-else>…</ul>
    
    • A condition goes on one element. zb-else-if and zb-else go on the siblings right after it (whitespace may come between).
    • It compiles to the same thing as the <zb-if> wrapper, which stays, for conditions over several siblings or over text.
    • It keeps tables and lists valid HTML for editors and formatters (<tr zb-if={…}>).
    • Errors that say what to write: on a directive, on the host, without a sibling to follow, after the chain's zb-else, quoted, without a value, or two on one element.
  • Markup in braces, in the three forms that are directives:

    • {a && <p>…</p>} is a zb-if;
    • {a ? <b>…</b> : <i>…</i>} is a zb-if with a zb-else (either side may be text, an expression or null);
    • {list.map((item, i) => <li key={item.id}>…</li>)} is a zb-each, keyed by the element's key.

    The markup inside is the template's own HTML: directives, modifiers, class: and nested braces all work, and each brace holds one element. Anything else with markup in it is an error naming the form or directive to use. So is markup in an attribute's braces, which 4.0 reported as a parse error.

  • Tools:

    • the language server completes zb-if, zb-else-if and zb-else on any element;
    • the VS Code grammar highlights them as directives, and a tag inside braces as a tag;
    • the guide's templates page, the README and the zubra-component skill describe both forms (the skill keeps directives as the house style for markup in braces);
    • the playground has a Conditions example.

Changed#

  • The zb- attribute prefix is reserved. An unknown zb-… attribute is an error with a suggestion (zb-iff → "did you mean zb-if?"), and a host attribute can't start with zb-. data-zb-* stays yours.
  • The examples and the registry use the attribute form where a <zb-if> wrapped one element on its own lines: 56 wrappers in 40 components, compiling to the same output apart from the whitespace that was inside the wrapper. examples/stats.mjs counts what's left (9 wrappers, around several siblings or inline).

4.0.0 — 2026-11-07#

mnx is now Zubra. The only change in this release is the name (docs/migrating-to-4.0.md). The npm scope @mnx belongs to someone else, so the packages could never have been published under it. Nothing had been published yet, so this was the cheapest time to choose a name the project can own everywhere. The format, the runtime's behaviour, the compiled code's ABI and every API are those of 3.6.0.

Changed (breaking)#

  • Files: .mnx, .mnx.jsx and .mnx.tsx are now .zb, .zb.jsx and .zb.tsx.
  • Directives and attributes: <mnx-if>, <mnx-each>, <mnx-slot>, <mnx-await> and the rest are <zb-…>; mnx-props is zb-props, and data-mnx-* is data-zb-*. Class names derived from tags follow the tag (ZbPicker).
  • Packages: @zubra/runtime, @zubra/compiler, @zubra/unplugin, @zubra/server, @zubra/language-server and create-zubra; the crate is zubra.
  • Commands and variables: the command is zubra, the environment variables are ZUBRA_*, and the served assets are at /_zubra/.
  • Names in APIs: ZubraModel (Angular), createZubra(), res.locals.zubra and request.zubra.
  • Skills: the coding-agent skills are zubra-component, zubra-consume, zubra-cli and zubra-server.
  • The repository is https://github.com/journey-to-code-org/zubra.
  • No aliases for the old spellings: nobody outside the project used them.

Fixed#

  • The crate ships only the compiler: 51 files, about 210 KB, down from 797 files and 1.1 MB. It used to include the examples and the npm packages.
  • @zubra/unplugin's peer dependencies named the 2.x compiler and runtime (^2.0.0), so npm would have refused to install it next to 3.x. They are now ^4.0.0, and scripts/bump-version.sh keeps them in step.

3.6.0 — 2026-11-07#

Accessible primitives (plan/roadmap-3.5.md, 3.6). The Zag.js spike showed that the platform does most of what a headless library is for, that two keyboard behaviours are missing, and that Zag covers the hard widgets once spread exists. This release ships each of those.

Added#

  • @mnx/runtime/primitives (1.0 KB gzipped): rovingFocus(container, { selector, orientation, loop, onMove }), one tab stop for a group with arrow keys, Home and End between the items (it skips disabled and hidden items and swaps Left and Right in RTL), and typeahead(container, { selector, text, timeout, onMatch }), type a letter to jump to an item. Both work on any element in any framework and return their cleanup.
  • @mnx/runtime/zag (0.3 KB): useMachine(machine, props) runs a Zag.js machine in a component, and normalizeProps comes with it. The props function is read whenever Zag asks, so it can read state and props. The service is read reactively, so computed(() => x.connect(machine.current, normalizeProps)) stays current. Each connection gets a fresh machine, because a stopped Zag machine can't be restarted, so moving the element keeps working. @zag-js/vanilla is an optional peer dependency.
  • Five registry components, each tested by role, accessible name and keyboard (the registry now has 25):
    • accordion-panel: <details>; the same group gives an exclusive accordion.
    • tool-tip: popover="manual", aria-describedby on the trigger; shown on hover and focus after delay; Escape hides it without moving focus.
    • tab-list: rovingFocus, automatic or manual activation; the slotted data-tab elements become labelled tab panels.
    • dropdown-menu: popover with popovertarget; Up and Down open it, arrows and typing move, focus returns to the button, Tab closes it, and it fires itemselect.
    • combo-box: Zag's combobox through @mnx/runtime/zag and spread; a form control.
    • tool-tip and dropdown-menu use CSS anchor positioning, and place themselves with script where it isn't supported.
  • mnx add says which npm packages a component imports, and how to install them. registry/index.json lists them under packages.
  • The guide: Accessible widgets without a headless library. It maps Radix and shadcn/ui to the platform, the primitives, a registry component or Zag, and gives what each path costs.
  • mnx build --lib lists the npm packages its components import as peer dependencies, with the project's own version range where it lists one (@zag-js/combobox and @zag-js/vanilla for a library with combo-box).
  • The registry's tests run in Firefox and WebKit in CI as well, because the widgets rely on newer platform features. All 25 components hydrate in place from stripped server markup.
  • The test harness takes extra import-map entries (useBrowser(components, files, imports)).

Changed#

  • The example library (examples/frameworks/ui/) and the plugin's library test build the registry's components that have no npm dependencies. That leaves out combo-box, so their apps and the plain page don't need Zag.

3.5.0 — 2026-11-07#

Spread (plan/roadmap-3.5.md, 3.5). Two findings pointed at the same gap: mnx convert stopped at a spread in nearly every shadcn/ui component, and the Zag.js spike needed a ref callback for every part of its combobox. Both now go through one feature.

Added#

  • {...object} in a start tag, in .mnx and JSX: an object's entries as an element's attributes, listeners and properties, the way headless libraries hand out behaviour (<input {...api.getInputProps()}>).
    • Listeners: on<Name> functions are listeners, replaced when the function changes and removed with their key.
    • Properties: value, checked, selected and indeterminate are set as properties; className and htmlFor mean class and for.
    • Classes and styles: class merges token by token with the element's own classes and class: toggles; style is an object set through the CSSOM.
    • Values: true is a bare attribute; aria-* booleans are written as "true"/"false"; false, null and undefined remove the attribute; entries that disappear are removed.
    • Precedence: an attribute written on the element wins.
    • Refused: text handlers, style text, unsafe URLs and markup keys (innerHTML, srcdoc, children, …). Nothing a spread does could not be done by an attribute.
    • Server: a spread known at build time renders, with the same checks; one known only in the browser is left for the element.
    • Not allowed on the host, a directive or an imported mnx component, each with an error that says why.
    • Where the code lives: @mnx/runtime/spread (1.4 KB gzipped), which a compiled module imports only when its template spreads, so the main runtime is unchanged (12.9 KB). An import map needs its entry; @mnx/server, the playground and the Flask example have it.
  • mnx check: a runtime hook used without its import is an error, with the import to add (computed, emit, onMount and the rest). It would have thrown in the browser. Every component in the repository passes.
  • TypeScript in a .mnx.tsx template expression ((e.target as HTMLElement), a!) is stripped, like the script's.
  • The playground has a spread example.

mnx convert#

  • A spread onto an element is an mnx spread, not a report; a spread onto another component is reported.
  • ...props spread onto the returned element is dropped: the host carries the consumer's attributes. className becomes the host's own class. The props' React type goes.
  • A component built on a third-party React primitive (Radix, Headless UI, React Aria, Ark, Base UI, cmdk, vaul, sonner, Recharts, …) is refused up front, with what to use instead.
  • Fixed: an insertion at the edge of a removed span was dropped (useMemo(() => { … }, deps) lost its )()); a file's other components were checked as if they were converted; removing them left blank lines.
  • shadcn/ui, re-measured (docs/convert-measured.md): 50 of the 68 components in its plain-markup files convert and compile (0 in 3.2); its 46 primitive-based files are refused with one message each.

3.4.0 — 2026-11-07#

Evidence (plan/roadmap-4.0.md, 3.4): the claims the pitch rests on, with numbers, written for the people who argued against them.

Added#

  • docs/standards/one-source-n-consumers.md. The argument for one source made as the weaker claim it has become now that agents make ports cheap: N copies are N things to review and keep matching, and what goes wrong in a port is what the compiler generates. With numbers: the registry's 20 components across the matrix are 140 hand-written ports against 20 files and 367 lines of adapter written once; the ten framework-specific bugs the adapters absorbed, each fixed once; and an experiment (docs/standards/ports-experiment/, reproducible) in which an agent ported three registry components to React, Vue and Svelte in three minutes, a reviewing agent found 47 behavioural differences in the nine fresh ports (form reset and submission, event semantics, host semantics: the generated parts), and two fixes were then propagated to all six affected ports without error. The conclusion is the one the survey's instructor would accept: propagation is solved; divergence happens at port time.
  • docs/framework-matrix.md: what each framework's row in CI proves, row by row, and what isn't in a row (SvelteKit with light DOM, Next.js elements with React children, Qwik).

Corrected#

  • React 18 prop timing was already fixed. progress.md listed "React 18: props still arrive after the script runs" as open; since 2.8 the element reads the React wrapper's mnx-props when it starts, before React 18's effect sets properties, and runtime/test/browser/adapters.test.js asserts a script seeded from a prop sees it under React 18. No change was needed; the roadmap's decision 2 is moot.

3.3.0 — 2026-11-07#

The last server gaps (plan/roadmap-4.0.md, 3.3): "SSR isn't great with web components" was the belief two of the survey's nine respondents held, and three visible gaps confirmed it.

Added#

  • Light DOM under framework hydration, for an element given no framework children. The React and Vue wrappers (@mnx/runtime/react, @mnx/runtime/vue) render an element's content into its host on the server (a light-DOM element's rendered children; a shadow-DOM element's declarative shadow root, as since 2.11) and keep the framework out of the host while hydrating (React: dangerouslySetInnerHTML with an empty string in the browser and suppressHydrationWarning; Vue: a vnode with no children at all, so Vue never looks inside), so the element hydrates its markup in place. serverContent(Element, { props, name }) from @mnx/runtime/server is the function behind both (shadowContent remains, for shadow DOM only). @mnx/server's injectShadowRoots(html, { lightDom: true }) does the same for frameworks that leave nodes they didn't render alone (Solid). The React Router balance list, the Nuxt stock meter, the Next.js session card and the SolidStart dish board are light DOM now, with their no-JavaScript tests passing. Still shadow: an element given React or Vue children, and every component under SvelteKit. @mnx/unplugin's warning says which.
  • Streaming. In @mnx/server, a prop given as a promise renders as pending (the compiler's new pending request field: the prop is unknown, so its mnx-await shows the pending content in an empty region), and page.stream(html) (a Node stream) or page.streamResponse(html) (a web Response) sends the page first, then, as each promise settles, a <template> with the resolved region and an inline script that swaps it in before the element starts (or hands the element the value if it has; a held promise keeps the mnx-await pending meanwhile; a rejection reaches mnx-catch). The streamed page's module script is async, so the elements start before the stream ends. page.pending says whether a page is streaming. The help desk's dashboard streams its recent activity (components/recent-activity.mnx).
  • HtmlOptions.pending in the Rust API; --emit interface typings carry required.

Documented, not fixed#

  • Next.js elements given React children can't carry server-rendered content: dangerouslySetInnerHTML and children are exclusive in React, and a declarative shadow root as a React child breaks hydration. They draw in the browser until React understands declarative shadow DOM. docs/server-rendering.md records it.

3.2.0 — 2026-11-07#

Usable by agents (plan/roadmap-4.0.md, 3.2): the thing the survey said nobody had asked a web-component tool for yet.

Added#

  • Mutating state updates the DOM. let items = [] then items.push(x), items.splice(i, 1), items[0].done = true, form.email = "…", delete form.email: a let (or state(), or from()) holding an array or a plain object holds a reactive proxy, with a Signal.State per property, so a write re-runs only what read that property (runtime/src/deep.js, about 370 B gzipped). Nested arrays and objects are wrapped as they're read; class instances, Map, Set, Date, DOM nodes and functions aren't. raw(value) from @mnx/runtime gives the original back. Props aren't wrapped. mnx-each reads the list's length and indices, so pushes and splices re-run it and keyed rows keep their elements. The compiler's output is unchanged. (plan/decisions/deep-reactivity.md.) The runtime's gzip budgets are 13.5 KB (development) and 13 KB (production), up from 13 / 12.5.
  • skills/: mnx-component (writing one), mnx-consume (using one from each framework), mnx-cli, mnx-server, each written so an agent can do the job from it alone, and AGENTS.md naming them. skills/test/skills.test.js compiles every component example in them and checks the copies; skills/test/agent.test.js has an agent write a component from the skill alone and checks it compiles, renders on the server and works in Chromium (run with MNX_AGENT="claude -p"; a non-blocking CI job where ANTHROPIC_API_KEY is set).
  • npm create mnx writes AGENTS.md and skills/ into the new project; mnx build --lib writes skills/using-<package>/SKILL.md from the manifest, so a library tells agents its components' props, events, slots and two-way bindings.
  • mnx convert: useReducer becomes a let and a dispatch that assigns; createContext and useContext become the runtime's (inject()), with <Context.Provider>, exported contexts and contexts from other modules reported; a received event prop passed on (onClose={onClose}) becomes a call; --component <Name> converts one of a file's several exported components (export function X or export { X }); --as mnx writes the HTML-first .mnx file, with the script as written and the template's indentation, once nothing is left to finish. docs/convert-measured.md runs it over shadcn/ui's 325 components: 0 convert without a hand finish, 323 because of spread props, which is the next thing to build.
  • --emit interface includes required per prop; scripts/sync-skills.sh.

Examples#

  • The trail filter and the recipe reviews mutate their lists instead of rebuilding them; the scoreboard counts "a let rebuilt instead of mutated" (0).

3.1.0 — 2026-11-07#

Who this is for (plan/roadmap-4.0.md, 3.1). The first release whose evidence is what people who don't use web components said, rather than what building the examples took. Nothing in the compiler or runtime changed; the positioning did.

Added#

  • docs/who-this-is-for.md: where a compiled web component earns its place (a library or design system with consumers on more than one stack, components handed to other people's stacks, a CMS or an older app, a server that isn't JavaScript) and where it doesn't (one app on one framework, a container of the app's own components, one button on one page). The honest objections, with where mnx stands on each.
  • docs/what-crosses-the-boundary.md: what crosses a custom element (props, events, two-way binding, slots, form participation, the Context Protocol, host refs, server rendering, outside styling) and what doesn't (render props, framework context, Suspense and transitions, framework hooks, the consumer's components by name), with the rule of thumb: a leaf fits, a container belongs in the framework.
  • docs/server-rendering.md: the server story in plain terms, with what renders where, what works without JavaScript, and the four gaps that remain (light DOM inside hydrating frameworks, Next.js elements with React children, no streaming, Date/Intl browser-only).
  • scripts/bump-version.sh.

Changed#

  • The README's first screen is the copy button from the conversation that started this roadmap, next to the same element written by hand (about 55 lines, in a <details>), then let count = 0 updating one text node, then "who it's for" with the Astro line: Astro lets frameworks coexist on a page; mnx lets one component be used by all of them. The framework matrix moves below.
  • The guide's first page says in one sentence that the button renders in light DOM and shadow DOM is a flag.

3.0.0 — 2026-11-07#

The first major version since 2.0 (plan/roadmap-3.0.md). One change in meaning, one removal; docs/migrating-to-3.0.md has the upgrade. Compiled code is unchanged (abi: 2), so components built with 2.x run on the 3.0 runtime.

Changed (breaking)#

  • A signal const in a script means its value, as it already did in templates. A const holding a signal from state(), computed(), inject(), hasSlot() or hydrated() reads as .get() wherever the script names it, and a const derived from it stays in sync. count.get() and count.set(…) written out keep working, and signal(count) is the signal itself. Only 2.x code that passed the signal itself changes meaning (watch(count, …), formValue(count)): run mnx migrate --to 3 once, on the 2.x code, to wrap those in signal(…). --check now lists each place. 2.6–2.11 warned at each; in this repository it touched two runtime test fixtures.
  • The CLI's 1.x name, mnix, is gone. @mnx/unplugin and the language server no longer fall back to it.
  • @mnx/server needs @mnx/compiler and @mnx/runtime 3.

Unchanged#

  • The hydration markers, and <mnx-each> as the way to write lists.
  • Browser support: the target is Baseline 2026, and no fallback was dropped. moveBefore() isn't in Safari, ElementInternals.states isn't Widely available yet, and no browser ships TC39 Signals. docs/browser-support.md lists them.

Examples and docs#

  • The planner's event page reads its computed() event as a value.
  • docs/migrating-to-3.0.md; the README, the guide's props page and the runtime's signal() docs describe 3.0's reads.

2.11.0 — 2026-11-07#

Next.js in the SSR bridge (plan/roadmap-3.0.md, 2.11). All additive.

Added#

  • Shadow roots in Next.js's server HTML. Next streams React Server Components and has no hook for its HTML, so @mnx/server's injectShadowRoots can't reach it. Now the React wrapper writes the shadow root itself, for a shadow-DOM element with no React children: on the server, the host's inner HTML is its declarative shadow root (and a form control's fallback input). The browser attaches the shadow root while parsing, and React doesn't hydrate inner HTML. In the browser that inner HTML is an empty string, which React leaves alone. The conference app's cards show without JavaScript, and the elements keep the parser's nodes when they start.
  • The loader's server build. @mnx/unplugin/loader with options: { server: true } (a Turbopack rule with condition: { not: 'browser' }) registers how to render each component on the server, with @mnx/compiler from the component's embedded sources. README.md has the next.config.mjs.
  • shadowContent(Element, { props, name }) from @mnx/runtime/server: a shadow-DOM element's server-rendered shadow root and form fallback, for framework integrations.
  • An element's mnx description says which prop is its model (props[name].model).

Fixed#

  • injectShadowRootsStream() could give a host a second shadow root when a chunk ended right after the host's start tag and the next began with a shadow root the page already had ("A second declarative shadow root cannot be created on a host"). It waits for more of the stream after a host's start tag now. With the React wrapper rendering shadow roots in React Router's server build too, that case became common there.

Not covered#

  • An element given React children (slot content) still draws in the browser under Next.js. A <template shadowrootmode> as a React child breaks hydration (React finds a different child, reports #418 and re-renders the page). The spike that found it is in plan/roadmap-3.0.md.

2.10.0 — 2026-11-07#

Hydrating stripped pages, and props for Svelte and Solid (plan/roadmap-3.0.md, 2.10). All additive.

Added#

  • Server markup whose comments were stripped hydrates in place. HTML minifiers (removeComments), some sanitizers and htmx in some browsers remove mnx's hydration markers. Before, such an element rendered fresh with a warning, losing focus and input state. Now it puts the markers back by structure and hydrates the markup it has:

    • a text anchor's text runs up to the next element;
    • an mnx-if holds the branch the current values choose, and an mnx-each one row per item, each checked element by element;
    • a light-DOM slot that ends its range holds the rest: its fallback if it has the fallback's shape, the supplied content otherwise;
    • an empty region followed by what follows it in the template is one the server left to the browser.

    Where that can't be placed for sure (an mnx-await, content projected into a child component), the element renders fresh as before, with the warning. The code is a separate module, remark.js, loaded only when an element meets such markup, so the runtime's size is unchanged where it isn't needed. All 20 registry components hydrate in place from stripped markup (registry/test/stripped.test.js), and so do the Eleventy guide's naively minified build and the bike shop's htmx swaps without the parser fix.

  • mnx-props for Svelte and Solid. @mnx/unplugin adds it to mnx hosts in Svelte and Solid server builds, from the attributes that set the element's props (log={…}, {log}, bind:value={…}, Solid's prop:items={…}). The SvelteKit and SolidStart apps drop their hand-written ones.

Fixed#

  • 2.9.0 said Firefox doesn't focus an invalid mnx form control's input when a form won't submit. It does; it only logs "The invalid form control … is not focusable" as it goes. A new test checks the focus in every engine, and docs/browser-support.md is corrected. (Its message also comes without a name, "An invalid form control is not focusable", for a control created by script.)
  • The page-notes extension's injection test raced the bridge's own sends as the page loaded; it now sends until the bridge is done.

Changed#

  • The runtime has a second module, remark.js, loaded with a dynamic import. Bundlers split it into its own chunk. A single-file Rollup build (output.file) can't, so @mnx/unplugin sets inlineDynamicImports there; a Rollup build of the runtime without the plugin needs it set, or output.dir.
  • The runtime's size test measures the entry the way a bundler splits it (remark.js apart). The development build is 12.9 KB gzipped and the production build 12.5 KB, within their budgets.

2.9.1 — 2026-11-07#

from() across the examples and docs.

Examples and docs#

  • Three more components use from():
    • the planner's event dialog: let problem = from(event, "") clears its validation message when it opens another event, instead of a line in its watch();
    • the Eleventy trail filter: let longest = from(max) starts the slider at the longest trail, and again if that changes;
    • the recipe scaler: let people = from(servings) (a JSX component).
  • The React, Svelte and Vue guides map their patterns onto it: useState(prop) plus a reset effect, Svelte's writable $derived, and Vue's ref(props.x) plus a watch().

2.9.0 — 2026-11-07#

The additive part of 3.0, early (plan/roadmap-3.0.md, 2.9). Nothing changes meaning.

Added#

  • from() from @mnx/runtime: let left = from(seconds) is state that follows a prop until it's assigned, and starts over when the prop changes. let running = from(seconds, false) starts as false instead, again on each change. It works in .mnx scripts and JSX components, renders on the server as the prop's value, and a const with from() is an error that suggests the plain const. mnx convert turns React's useState(prop) plus a useEffect that resets it on [prop] into from(), and drops the effect.
  • A production build of the runtime (dist/production/), without hot reloading. Bundlers pick it through the production export condition (Vite and webpack do in production builds), and @mnx/server serves it when NODE_ENV is production (or production: true). It's 12.2 KB gzipped, against 12.7 KB for the development build.
  • Firefox and WebKit in CI: the runtime's browser suite and the React and Vue example apps run in both, through Playwright (MNX_BROWSER=firefox|webkit). The runtime's browser suite also runs on the production build (MNX_RUNTIME=production). Both engines pass, with three findings recorded in docs/browser-support.md: Firefox before 159 can style slotted light-DOM content with its component's <style> (a Firefox @scope style-sharing bug, fixed in 159); Firefox doesn't focus an invalid mnx form control's input when a form won't submit; and WebKit clears long lists relatively slowly.

Fixed#

  • The frameworks examples' test server no longer crashes on a request for a missing file (Firefox asks for /favicon.ico).

Examples and docs#

  • The Electron focus timer uses from() for its time left and running flag, and drops a saved length and a five-line effect.
  • The README, the guide's props page and the runtime README cover from() and the production build; docs/browser-support.md covers the engines tested.

2.8.0 — 2026-11-07#

Server-first (plan/roadmap-server.md, 2.8). All additive.

Added#

  • @mnx/server, a new package for rendering mnx components from any Node.js server. createMnx({ components }) compiles a folder of components and caches them. page() renders components into a page and adds their CSS and module scripts (finish(html)). handle(req, res) and fetch(request) serve the browser modules and @mnx/runtime, and writeAssets(dir) writes them for a static site. Express, Fastify and Hono have adapters (@mnx/server/express, /fastify, /hono).
  • The SSR bridge for frameworks. injectShadowRoots(html) (and injectShadowRootsStream() for a stream) finds the hosts of shadow-DOM components in a framework's HTML and renders their shadow roots into it (<template shadowrootmode="open">), from the host's attributes and a mnx-props JSON attribute. For a form-associated component with a model prop and a name, it adds a hidden input carrying the value, which the element removes when it starts. With it, SvelteKit, Nuxt, React Router and SolidStart pages show their elements and submit their forms before JavaScript. The React and Vue adapters write mnx-props; in Svelte and Solid the app writes it.
  • The server evaluates the script's deterministic JavaScript. Arrow functions, .map(), .filter(), .reduce(), .includes(), toFixed(), padStart(), Math, Object.entries(), template literals, spread and more now render on the server, in the CLI, mnx serve and @mnx/compiler alike. What isn't deterministic (Date, Intl, Math.random, toLocaleString, anything from fetch) is still left for the browser, and mnx check --server still lists it. A differential test runs each supported expression in V8 and checks the server agrees.
  • --emit interface (and emit: 'interface'): a component's tag, shadow and form flags, props (with attribute names, types, defaults and which is the model) and events, as JSON, for a server.
  • The Turbopack and webpack loader (@mnx/unplugin/loader): Next.js imports .mnx files directly as client React components, with no mnx build --lib step.
  • host-reset on a shadow host: :host { all: initial !important }, so a page's styles (even !important ones) don't reach the host. For components on pages you don't control.

Changed#

  • The runtime reads mnx-props when an element starts, and a form-associated element removes its server fallback input.
  • The runtime's size budget is 13 KB gzipped (it was 12.5 KB) for the above.

Examples and docs#

  • The help desk and the Eleventy guide use @mnx/server instead of their own compiler glue. The SvelteKit, Nuxt, React Router and SolidStart apps add the SSR bridge, and each one's no-JavaScript test now submits its form. The Next.js app uses the loader.
  • The Flask garden computes its checkbox state and chart in the components again, and the Hono price tag formats with toFixed. The page-notes widget uses host-reset.
  • The README and the guide's server-rendering page cover @mnx/server, the SSR bridge and what the server evaluates.

2.7.0 — 2026-11-07#

Progressive enhancement, said once (plan/roadmap-server.md, 2.7). All additive.

Added#

  • hydrated() from @mnx/runtime: a signal that's false in the server's HTML (and on the server) and true once the element has started. The host also gets the custom state hydrated, for CSS (:host(:state(hydrated)), my-filters:state(hydrated)). It replaces let live = false; onMount(() => (live = true)).
  • <select value={…}> and <textarea value={…}> in the HTML output. A select's value marks the matching <option selected>, and a textarea's value becomes its content. HTML ignores a value attribute on both, so before JavaScript the page used to show the first option and an empty box.
  • The .submit event modifier submits the element's form after any handler, with requestSubmit(), so validation and submit listeners run. <select onchange.submit> needs no handler. In scripts and JSX it's submit(fn).
  • The .mod key modifier: ⌘ on Apple platforms and Ctrl elsewhere (onkeydown.mod.enter, keys('mod+enter', fn)).
  • value:bind={x} on a child custom element keeps its two-way prop and a let (or prop) in step. It stands for value={x} plus onvaluechange={(event) => (x = event.detail)}.
  • mnx check --server lists what a server without JavaScript leaves out of a component rendered with its defaults (calls, template literals, runtime-only values). It's an error for checked, selected, value and disabled, which make a form wrong without JavaScript. It's also "server": true on a check request, and npx mnx check --server.
  • mnx serve: a long-lived process answering one JSON request per line, for servers in other languages. Requests can also be batches ({ "requests": [ … ] }). The Flask example uses it, and its pages got about 40% faster.
  • mnx build --lib --watch rebuilds after each change. A compile error keeps the last good build, because builds now go to a temporary directory and are swapped in. The Next.js example has npm run ui:watch.
  • MNX_MARKER_COMMENT from @mnx/compiler: the hydration markers' comment text, for minifiers' keep-lists.

Changed#

  • Partial rendering decides live && … and !live || … (any known first operand of && or || that settles the result), instead of leaving the whole expression for the browser.
  • A host whose hydration markers were stripped gets a warning that says so and names the usual causes (a minifier, a sanitizer, htmx), instead of the general "doesn't match its template".
  • @mnx/unplugin recognises React Router as a React project, so framework: 'react' is no longer needed there.
  • @mnx/unplugin warns when a light-DOM component is server-rendered in React Router, Nuxt or SvelteKit, whose hydration breaks around it.
  • The runtime's size budget is 12.5 KB gzipped (it was 12 KB) for the above.

Examples and docs#

  • The help desk's filter bar drops its nine selected=, its ref and its apply function. The reply box drops a listener and its ref. Seven components across the help desk, Flask, Hono and Eleventy apps use hydrated() instead of the hand-written pattern. The note composer uses value:bind.
  • The scoreboard (node examples/stats.mjs) counts the server and client apps too, and the patterns these replace are now at zero.
  • The README covers hydration markers, frameworks that hydrate, and what the server can render. The guide's Forms page covers forms that work before JavaScript, and a new page covers mnx on other people's pages.

2.6.7 — 2026-11-07#

Examples#

Three more framework apps in examples/meta/, each with a Chromium test in CI:

  • react-router-trips/: a shared trip budget in React Router 8's framework mode. It imports .mnx files as React components through the Vite plugin, and uses form-associated controls in <Form> with a server action and a useFetcher delete.
  • solidstart-potluck/: a potluck sign-up in SolidStart 2. It uses elements directly with prop: and on:, as form controls posting to a server action.
  • eleventy-trails/: a static trail guide in Eleventy 3. A shortcode renders the components at build time, and a transform adds their CSS and modules, with no bundler. The tests also build it minified, both keeping mnx's markers and not.

What they found (in examples/meta/README.md):

  • Solid's hydration tolerates light-DOM components, unlike React, Vue and Svelte.
  • React Router renders only the host tags, as the other frameworks do, and so does SolidStart.
  • An HTML minifier that removes comments removes the hydration markers. html-minifier-terser's ignoreCustomComments: [/^[[\]?!]*$/] keeps them.
  • The plugin doesn't recognise React Router as a React project, so it needs mnx({ framework: 'react' }).

2.6.6 — 2026-11-07#

Fixed#

  • The esbuild plugin reports compile errors as the compiler wrote them. Under esbuild and Bun, unplugin's this.error() records an error rather than throwing it, and it drops the error when the hook returns nothing. Depending on the file, a compile error came out as "Do not know how to load path" or as a TypeError. The plugin now always throws.

Examples#

  • examples/extension/page-notes/: a Chrome extension (Manifest V3).
    • mnx components appear in its popup, its options page, and a shadow-DOM widget on other sites' pages. It also has a service worker for the toolbar badge.
    • Content scripts can't define custom elements (customElements is null in their isolated world). So the widget runs in the page's own world, and a bridge script passes it data as text.
    • A host's :host rules lose to a page's !important styles, so the widget's are !important too.
  • examples/desktop/focus-timer/: a focus timer in Electron.
    • The renderer is sandboxed and exposes a three-call preload.
    • Its Content Security Policy allows no inline scripts, eval or inline styles. mnx works under it unchanged, because component CSS is adopted as constructed stylesheets.
    • Its tests drive the app with Playwright's Electron support and a fake clock.
  • CI runs both in a new clients job.

2.6.5 — 2026-11-07#

Examples#

  • examples/hypermedia/hono-bikes/: a bike shop's inventory built with Hono and htmx, running on Node.js and on Bun.
    • Every route answers a plain request with a page and an htmx request with the fragment to swap.
    • The mnx components in those fragments are rendered on the server and hydrate where htmx puts them.
    • Its tests run the server on both runtimes, with JavaScript off and on. CI runs them in a new hypermedia job.
  • What it found (in its README):
    • In the Chromium that Playwright ships, Document.parseHTMLUnsafe(), which htmx 2 prefers, drops HTML comments. That includes mnx's hydration markers, so swapped-in elements render fresh instead of hydrating. They come out right, but with a warning. The example works around it so htmx uses DOMParser, and a test covers both paths.
    • Custom elements can't be table rows.
    • Formatting money on the server takes arithmetic.

2.6.4 — 2026-11-07#

Examples#

  • examples/backends/flask-garden/: a community garden's plot sign-up in Python, built with Flask, Jinja and SQLite.
    • Its components are rendered by the mnx CLI (mnx request), so there's no Node.js on the server and no bundler. The browser hydrates them through an import map.
    • garden/mnx.py is the glue: about 100 lines, standard library only.
    • Every page works without JavaScript. Its tests drive them in Chromium with JavaScript off and on, using Playwright for Python. CI runs them in a new backends job.
    • Its README lists what it found about the server's expression subset, which is everything a non-JavaScript server has.

2.6.3 — 2026-11-07#

Fixed#

  • An empty URL prop no longer logs an unsafe-URL error. A URL attribute bound to a prop whose default is "" (href={href} before the app sets it) is now left off quietly.
  • An object prop written as "[object Object]" is treated as not given yet. Svelte's server rendering writes object props that way. The element now uses the prop's default until Svelte sets the real object, instead of warning about invalid JSON.
  • Library mode's React entries start with 'use client', so React Server Components (Next.js) can import them.

Examples#

  • examples/meta/: three meta-framework apps, each with a Chromium test in CI.

    • next-conference/: Next.js 16 with the App Router. Components come from a library built with mnx build --lib, since Turbopack takes no bundler plugins. Feedback is posted through a Server Action with useActionState.
    • nuxt-bookshop/: Nuxt 4 through the Vite plugin, with v-model on mnx controls and Nitro API routes.
    • sveltekit-workouts/: SvelteKit 3 through the Vite plugin, with mnx form controls in a form action using use:enhance.

    Their components use shadow DOM. Light-DOM components conflict with the frameworks' hydration today. That finding, and the others, are written up in examples/meta/README.md and planned in plan/roadmap-server.md (2.7 and 2.8).

2.6.2 — 2026-11-07#

Examples#

  • examples/helpdesk/: a help-desk ticket tracker built with Express, EJS and MongoDB. Its mnx components are rendered on the server inside EJS pages (with @mnx/compiler), and the browser hydrates them in place without a bundler. Every page works with JavaScript off, because the components render native form controls in light DOM. With JavaScript on, they add keyboard navigation, live filters, a smarter reply box and running SLA timers. The dashboard charts came from the registry with mnx add. Its tests drive every page in Chromium with and without JavaScript, and check the store contract. CI runs them on the in-memory store and on a MongoDB service container.

2.6.1 — 2026-11-07#

Fixed#

  • The React adapter sets props before the component's script runs (React 19). It used to set them after React inserted the element, so a script that seeds state from a prop (let draft = card, which is what mnx convert makes of useState(card)) saw undefined. React 19 now sets them as it creates the element. Under React 18 the script still sees the default.
  • mnx convert --out into another folder adjusts the output's relative imports to it.

Examples#

  • The React board and the Vue budget take their shared components from a library, examples/frameworks/ui/, built from the registry with mnx build --lib. They import it like a package from npm (@mnx-examples/ui/react, @mnx-examples/ui/vue). Their app-specific components stay .mnx files compiled by the plugin.
  • The React board's card editor was converted from React with mnx convert. react-board/CONVERTED.md has the before and after, and what was finished by hand.

2.6.0 — 2026-11-07#

Move in, and the 3.0 runway (plan/roadmap-adoption.md). The last release of the adoption roadmap.

Added#

  • mnx convert <Component.jsx> rewrites a React (or Preact) function component as an mnx JSX component:

    • useState → let, with setter calls as assignments;
    • useMemo and useCallback → plain consts;
    • useRef → a let without .current;
    • useEffect(fn, []) → onMount(fn), and useEffect(fn, deps) → onMount(() => effect(fn)), which keeps React's after-render timing;
    • onChange on text fields → onInput, and onDoubleClick → onDblClick;
    • a single named export becomes the default export.

    Only what changes is rewritten. What it can't convert (other hooks, props not destructured, spread attributes, dangerouslySetInnerHTML) is reported with advice, and the output is compiled to check it. A converted component is tested in Chromium against its React behaviour. It's also available as npx mnx convert and through the request interface (command: "convert").

  • Preparing for 3.0 (plan/decisions/3.0-scope.md). In 3.0, a signal const in a script will mean its value, as in templates. .get() and .set() keep working, so only a signal passed as itself changes meaning.

    • mnx check (and editors) warn at each such place.
    • mnx migrate --to 3 wraps them in signal(…), new in @mnx/runtime as the identity, which means the signal in 2.x and 3.0 alike.
  • The adoption check (scripts/adoption-check.mjs, run in CI): npm create mnx → mnx add → an edit → mnx check → the app's browser test → mnx build --lib → npm pack, timed against a 10-minute budget. It takes under two seconds of tool time, not counting dependency installation.

2.5.0 — 2026-11-07#

Share components (plan/roadmap-adoption.md).

Added#

  • Library mode: mnx build --lib <dir>. A folder of components becomes a publishable package with no bundler or mnx tooling needed by consumers. It contains an ES module per element, an index, React and Vue entries (<package>/react, <package>/vue) with their typings, custom-elements.json, and package.json exports. Tested by building the registry and using it from a React app and a Vue app (each with only its framework's Vite plugin), a plain page and TypeScript.

  • mnx on npm: @mnx/compiler now has a command, mnx, with build --lib, add, compile and check, running the WebAssembly compiler (no Rust needed). buildLibrary() is exported from @mnx/compiler/library.

  • The component registry: mnx add <name>. It copies one of twenty accessible components into your project (--dir, --force, --list). They are drawn from the examples:

    • inputs: tag input, date range, money input, star rating, toggle switch, choice cards, colour swatches, quantity stepper, segmented control;
    • display: donut chart, spark line, line chart, progress ring, streak grid, flip card, step indicator;
    • app pieces: kanban column, chat message, message composer, and a new modal dialog.

    Each has keyboard and screen-reader tests (role, accessible name, announced state). Every colour is a themeable custom property with a default.

  • Storybook through the manifest: the library's package.json points to its custom-elements.json, which @storybook/web-components reads for controls and docs (README, "Sharing components").

Fixed#

  • The chat message's action toolbar (the Lit example's, and the registry's) was display: none until hovered, so the keyboard couldn't reach it. It is now transparent until hovered or focused.
  • In the registry versions: the star rating is a named group with a two-way value; the spark line is an image named with its trend; the flip card's name is its visible face; the emoji picker is a named group rather than a menu without menu keys.

2.4.0 — 2026-11-07#

Start in a minute (plan/roadmap-adoption.md).

Added#

  • npm create mnx (create/, the create-mnx package). It asks for a framework (none, React, Vue, Svelte, Solid, Preact, Lit, Angular or Astro) and writes a working app: one component, the plugin wired up, typings, and a browser test (npm test). CI writes every starter and runs its own test.
  • Hot reloading that keeps state. In Vite's dev server, an edited component is swapped into the live elements, which keep their props, state and slotted content (light and shadow DOM). A change to the element's interface reloads the page instead.
  • Compile errors in Vite's overlay, with the location, the code frame and the compiler's suggestion.
  • The playground (playground/): the WebAssembly compiler in the page, the component running in plain HTML, React and Vue side by side, the JavaScript, server HTML, typings and manifest in tabs, and the example in a shareable link. Published to GitHub Pages by .github/workflows/pages.yml.
  • The guide (docs/guide/): a seven-step tutorial from a first component to server rendering, and pages for React, Vue and Svelte developers. The README is now the reference.
  • Runtime messages link to the docs: slot, hydration, list-key, hook, form and URL-safety warnings and errors name the README section that explains them.

Changed#

  • @mnx/unplugin dedupes Angular's packages too, as it does React and Vue, so a linked @mnx/runtime doesn't bring a second Angular.
  • The runtime is 12.0 KB gzipped (hot reloading and the doc links), within its 12 KB budget.

2.3.0 — 2026-11-07#

Components that say less (plan/roadmap-adoption.md). Rewritten with these, the example components went from 1,913 lines to 1,882, with no hand-fired <prop>change events (was 11) and 6 .get() calls left of 30 (node examples/stats.mjs).

Added#

  • Two-way props: value:model={0} on the host. Assigning the prop in the script fires valuechange when it changes; the event is declared in the typings (CustomEvent<number>) and the manifest. In JSX, a default of model(x).
  • Automatic form values: a form-associated control with one :model prop and no formValue() submits that prop, and a form reset restores its initial value.
  • Signals read like values in templates: a const from state(), computed(), inject() or hasSlot() is unwrapped where the template reads it ({user.name}), and a const derived from one is a computed.
  • hasSlot(name): a signal saying whether a slot has content, following it in light and shadow DOM.
  • declare const name: Type types a prop in <script lang="ts">; one naming no prop is an error, with a suggestion.

Changed#

  • The runtime's size budget is 12 KB gzipped (was 11 KB); it is 11.4 KB.

2.2.0 — 2026-11-07#

Templates that say less (plan/roadmap-adoption.md). Rewritten with these, the example components went from 1,968 lines to 1,913, with no class-string concatenation (was 22), no host() queries (6), no hand-added window or document listeners (2), and 4 preventDefault() calls left of 18 (node examples/stats.mjs).

Added#

  • class: and style: directives: class:open={…} (bare class:open reads open), class={{ … }}, style:font-size={…}, style:--tone={…} and style={{ … }}. Merged into class and style in the HTML output; bound one class or property at a time in the browser. A computed class beside toggles is bound token by token. Static style="…" attributes are now allowed.
  • Event modifiers: .prevent, .stop, .once, .self, .capture, .passive, and key filters (onkeydown.enter, onkeydown.shift.arrowleft, onkeydown.k) with exact modifier keys. Unknown modifiers get a suggestion.
  • ref={name}: the element, assigned to a let (or passed to a function), and null when it's removed. Also in JSX.
  • <mnx-window> and <mnx-document>: event listeners on the window or document while rendered.
  • <mnx-else-if test={…}>.
  • prevent, stop, selfOnly and keys in @mnx/runtime: the modifiers as functions, for JSX and scripts.
  • Object shorthand in template expressions: { open } means { open: open }.
  • examples/stats.mjs: the scoreboard each release reports.
  • The VS Code grammar highlights modifiers, directives and ref.

2.1.0 — 2026-11-07#

Added#

  • An app per framework in examples/frameworks/: a sprint board (React), a budget tracker (Vue), a flashcard trainer (Svelte), a live market dashboard (Solid), a team chat (Lit), a habit tracker (Preact) and a booking wizard (Angular). Each mixes the framework's own components with mnx elements, and a new CI job builds every one and uses it in Chromium.
  • Angular in Vite: with Analog's plugin, .mnx files are imported directly and MnxModel compiles ahead of time. Its typings now carry Angular's directive declaration, which ahead-of-time compilation needs (the Angular CLI included). The adapter file moved to fesm2022/, as the Angular Package Format lays out, so Vite-based Angular builds link it; @mnx/runtime/angular is unchanged.
  • Light-DOM styles in other libraries' shadow roots, through a bundler. With @mnx/unplugin, a component's CSS went into the page only, so an mnx element inside a Lit component's shadow root (or any other) was unstyled. The CSS text now comes along, and is adopted into shadow roots; the page keeps the bundled stylesheet.

Fixed#

  • Rows and branches of mnx-each/mnx-if inside <svg> (or <math>) were created as HTML elements, so they didn't render. They're now parsed in their parent's namespace.
  • The Vue adapter set props as Vue DOM props, where Vue turns null into 0, '' or false (by the property's current type). Props are now set by a directive, as given.
  • An invalid form-associated component made the browser log "An invalid form control … is not focusable" when a form reported validity: the message was anchored to the host. It's now anchored to the first focusable element the component rendered, which the browser focuses.
  • Bound value isn't written when the text is already the same, which moved the caret and lost a selection.

2.0.2 — 2026-11-07#

Added#

  • An event planner example (examples/planner/): a single-page app in nine .mnx components. It has a month calendar, a searchable list, a dialog form, and per-event schedule, guests, budget and tasks, plus .ics export. It uses context, hash routing and localStorage, and the plugin's tests use all of it in Chromium.

Fixed#

  • A <select value={…}> whose options come from an mnx-each inside it showed its first option: the value was set before the options existed. It's now set again once they do.

2.0.1 — 2026-11-06#

Added#

  • Example projects in examples/: a to-do list (Vite, two .mnx components) and a recipe site (Astro: static components, a JSX island, a form-associated star rating, reviews loaded with resource()). Both are built and used in Chromium by the plugin's tests.

Fixed#

  • An element that a list row inserted stopped working once the list changed again: its effects belonged to the list's effect and were disposed with it. Each element now owns its own effects.
  • value={…} and checked={…} on form controls are set as the live property, so draft = "" clears what the user typed; the property is written only when the bound value changes, so typing isn't overwritten.
  • Rows that a light-DOM component's own mnx-each added after the first render could be dropped: they were moved through the host's slot routing (meant for content a framework adds) instead of the native DOM methods.

2.0.0 — 2026-11-06#

mnx leans on the platform more and on itself less, and .mnx scripts mean what JSX components already did. Upgrading: mnx migrate, then see docs/migrating-to-2.0.md.

Changed (breaking)#

  • Props are names in the script. value reads the prop and value = 2 sets it, as in the template; props() stays for custom hooks. A script can no longer declare a name a prop has (the 1.x title={title} default pattern), which is an error that points at mnx migrate.
  • A top-level let is state. Assigning it (count++, count = 0, count += 2, in the script or in an inline handler) updates what reads it. A top-level const that reads props or state is derived, so it stays in sync. Initial values still render on the server, and script values that read props are now evaluated with the props' values there.
  • The CLI is mnx (crate mnx-compiler). mnix stays as an alias through 2.x.
  • Compiled code is versioned. Modules call $define() with abi: 2; define (what 1.x modules call) throws an error that says to recompile, and so does a module for another interface. $define, $r and $t are internal.
  • Tools look for mnx on PATH first, then mnix.

Added#

  • docs/browser-support.md: the Baseline 2025 target, what each newer feature is used for, and what happens without it.

Unchanged#

  • The hydration markers. DOM Parts hasn't settled on a serialization (see docs/standards/dom-parts.md), so 2.0 keeps 1.x's.
  • The Signals API, which hasn't changed since mnx adopted it.

1.7.0 — 2026-11-06#

The runway to 2.0: everything 2.0 changes for .mnx files now warns, with a migration tool. See docs/migrating-to-2.0.md.

Added#

  • mnix migrate <files…> [--check]: rewrites .mnx files for 2.0. A script binding that shares a prop's name (the title={title} default pattern) is renamed, with its uses in the script and in host defaults. It also lists lets that will start updating the template. --check only reports, and fails if anything would change.
  • Deprecation warnings (in mnix check, the plugin and the language server): a script binding that will clash with a prop in 2.0, and a let the script changes and the template reads.
  • The mnx binary, the CLI's 2.0 name, installed alongside mnix.

1.6.0 — 2026-11-06#

Added#

  • Leak suite: removed elements, including ones React and Vue unmount and ones that read a signal that outlives them, are garbage-collected. Checked in Chromium by counting live instances through the DevTools protocol.
  • Benchmarks: the js-framework-benchmark operations on 1,000 keyed rows, and hydration against fresh rendering, with budgets that catch quadratic operations and hydration that re-renders.
  • Size budgets: the runtime, the Signals implementation included, within 11 KB gzip (9.7 KB).
  • Standards write-ups in docs/standards/: a Signals integration report, a parts usage report for DOM Parts and declarative templating, and the .mnx format as a declarative custom elements explainer.

Fixed#

  • Clearing or replacing a long list was quadratic: each removed row unwatched its effects separately. A subtree now unwatches in one pass, so clearing 1,000 rows went from 112 ms to 28 ms and replacing them from 118 ms to 46 ms. New rows are built in one fragment and inserted once.

1.5.0 — 2026-11-06#

Added#

  • resource(fetcher): async data as signals (value, error, status, loading, refresh(), awaitable). The fetcher re-runs when what it read changes. A new run, or the element's removal, aborts the previous one through its AbortSignal, and late answers are dropped.
  • <mnx-await value={…}> with pending content, <mnx-then as="…"> and <mnx-catch as="…">. Only the latest value's outcome shows, and a resource() is followed through its states. On the server, a value known at build time renders mnx-then; otherwise the pending content is rendered in a region the element renders when the value settles.
  • Partial server rendering (--partial, request partial: true): what only the browser can compute is left for the element. Text renders empty, attributes are left out, and conditionals and lists render as empty <!--[?--> regions, which the element renders without a hydration warning. @mnx/compiler's render() and the plugin's server builds render partially, so every component server-renders, including JSX components with state, in Astro too.

Changed#

  • Streaming server rendering moves from 1.5 to after 2.0. Partial rendering and mnx-await cover sending the shell first.

1.4.0 — 2026-11-06#

Added#

  • JSX components (.mnx.jsx / .mnx.tsx): a function component compiles to the same custom element as an .mnx file. The function's name is the tag, destructured parameters are props, on<Name> parameters are events (onValueChange(x) fires valuechange), children is the default slot, a top-level let is state, and a top-level const that reads props or state is derived. && / ? : are conditionals and .map() with a key is a keyed list. It's lowered to the .mnx format with a source map, so every output and check works and errors point into the JSX. .mnx and JSX components import each other, and @mnx/unplugin resolves .mnx.jsx / .mnx.tsx imports with the same variant rules.
  • JavaScript expressions in templates: beyond the build-time subset, any expression is accepted as code that runs in the browser: calls, arrow-function handlers that close over list items, list methods. Names follow the script (a state() is read with .get()), only props can be assigned, emit() in a template declares its event, and a runtime expression can be a prop default. The HTML output reports these as browser-only, as it does runtime-only script values.

1.3.0 — 2026-11-06#

Added#

  • Server rendering for apps. @mnx/compiler has render(path, { props, slots }) (HTML plus the scoped CSS it needs) and renderToString(), throwing a CompileError with diagnostics. Compiled modules now load on a server: without a DOM, define() returns a stand-in that carries the element's mnx description, so adapters and framework SSR can import components. @mnx/runtime/server renders an element class (renderToString(Element, { props, attributes, slots })), and the plugin's server builds register each component's renderer, with its sources embedded.
  • Astro integration (@mnx/unplugin/astro): .mnx components in Astro pages, server-rendered, static by default and hydrated with client:* directives. Props go to the component, other attributes to the host, children to slots.
  • Slot content as server HTML. Slots can be HTML a server already rendered, kept as written: braces are text, and comments (hydration markers), <script>, unquoted and inline-handler attributes stay. Request slotSource: "html", CLI --slots-html; render() uses it by default. Slotted elements are still marked for scoped styles.
  • Angular: MnxModel from @mnx/runtime/angular, a standalone directive that makes an mnx element a form control (ngModel, formControl, formControlName) through its <prop> + <prop>change pair, with touched and disabled states. Published as partial declarations, so the Angular linker compiles it for AOT builds.
  • Svelte, Solid and Lit: the plugin detects Solid, Preact and Svelte projects and gives their files the element itself; --framework svelte|solid typings (svelte/elements, Solid's prop:/on:). Tested in real apps, with Lit as a host too.
  • mnix request: one JSON request on stdin, the response on stdout (what the WebAssembly build exposes). @mnx/compiler uses it when mnx.wasm is missing and $MNX_COMPILER names a native mnix.
  • The plugin is tested building with Rollup, webpack and esbuild as well as Vite.

Fixed#

  • Light-DOM slots keep a framework's markers with its content (a comment goes with the content after it, whitespace with the content before it), so Lit's parts and Svelte's anchors stay in one slot. Markers and whitespace alone don't fill a slot.
  • The plugin found .mnx imports in <script lang="ts"> too when watching a component's dependencies.

1.2.0 — 2026-11-06#

Added#

  • @mnx/compiler: the compiler as WebAssembly (mnx-wasm, a C-ABI shim over the new handle_request: a JSON request with every source in, a JSON response with output and diagnostics out). Same output as the CLI, checked by a parity test in CI. @mnx/unplugin uses it when no CLI is configured, so apps need no Rust toolchain.
  • @mnx/language-server: diagnostics as you type, completion (directives, imported components, props, events, props in expressions), hover docs and go to definition, over LSP.
  • VS Code extension (editors/vscode): TextMate grammar with embedded JavaScript/TypeScript/CSS/SCSS, language configuration, and the language server.
  • --emit html-data: VS Code HTML custom data for mnx elements in .html files.
  • mnix check --stdin: checks unsaved text as if it were at the given path.

1.1.0 — 2026-11-06#

Added#

  • mnix check: every error and warning in the given files, without writing output; exit status 1 on errors; --format json for editors and CI.
  • Scoped <style>: light-DOM styles use native @scope and stop at slotted content, marked data-mnx-slotted="<component>"; shadow components adopt a shared sheet, with a <style> in their declarative shadow root for server rendering. Styles sit in the components cascade layer with Tailwind's layer order declared, so utilities and page CSS override them (layer="…" / layer="none" to change that). :host works in both modes. --emit css for the page; with @mnx/unplugin, <style> (including lang="scss") goes through Vite's CSS pipeline, so Tailwind's @apply and @reference work. adoptStyles() brings app-wide CSS into shadow roots.
  • Prop defaults computed in the browser: a default that uses runtime-only script values (or the browser's globals) is computed per element after the script runs, unless the prop was given. The HTML output asks for it via --props or the parent.
  • <script lang="ts">: TypeScript component scripts, erasable syntax only, with types removed in place so positions are kept. Annotated bindings type the props they default, emit<T>() types event details, and the script's types are exported from the generated typings.

Fixed#

  • The JavaScript output now checks how child components are used, as the HTML output does: unknown props (with suggestions), literal values of the wrong type, missing required props, and listeners for near misses of a child's events.
  • A script binding that reads a browser global (window, document, Math, …) is runtime-only instead of an "used before it is declared" error.

1.0.0 — 2026-11-06#

The first stable release: the .mnx format is frozen until 2.0, and both outputs support everything in it. Covers the compiler crate and CLI (mnix), @mnx/runtime and @mnx/unplugin. Licensed under ISC.

Format#

  • Single-file components. An optional <script>, then a host tag that declares the custom element and its props: title={title} takes its default from the script, label="Hi" is a string default, a bare name is required. shadow opts into shadow DOM; form-associated makes the element a form control. A comment above the component is its description.
  • {expr} in text and attributes, in a JavaScript subset with JavaScript's semantics (?. ?? ? :, strict ==, truthiness). Every name is checked in every branch, with "did you mean" suggestions.
  • Directives: mnx-if / mnx-else, mnx-each (with index and key), mnx-slot (named, with fallbacks).
  • Templates may have any number of top-level nodes: the host is the root.
  • Components using components: import './badge.mnx' in the script; props are type-checked at the call site.
  • Events inferred from emit("name", detail), named like the platform's events (lowercase, no separators), with @fires documentation checked against the code.

Outputs#

  • HTML (--emit html, the default): static, deterministic, escaped markup with the markers the runtime needs to hydrate it; child components rendered inline (declarative shadow DOM for shadow components). --props and --slots supply values.
  • JavaScript (--emit js): a custom element on @mnx/runtime. Signal-backed props and typed attributes; template parts that bind to server markup without re-rendering (after a shape check); regions for mnx-if / mnx-each, with keyed rows moved by moveBefore(); light-DOM slots that stay live under frameworks managing the element's children; native <slot> in shadow components; pause on detach.
  • Custom Elements Manifest (--emit manifest, schema 2.1.0) and TypeScript declarations (--emit dts, optionally --framework react|vue).
  • Warnings for props that shadow built-in element properties (hidden, title, …).

Runtime (@mnx/runtime)#

  • The TC39 Signals API (the browser's own when present), differential-tested against the proposal's reference polyfill; batched effects with ownership.
  • Hooks: state, computed, effect, watch, onMount, onUnmount, id, props, host, emit; context on the Web Components Community Group Context Protocol (createContext, provide, inject); form controls on ElementInternals (formValue, validity, onFormReset, onFormRestore, onFormDisabled).
  • Adapters: @mnx/runtime/react (React 18 and 19) and @mnx/runtime/vue (Vue 3), with two-way binding from <prop> + <prop>change pairs.
  • Type declarations for every entry point.

Build plugin (@mnx/unplugin)#

  • Compiles .mnx imports in Vite, Rollup, webpack, esbuild and Rspack. The importing file decides what it gets: a React component, a Vue component, or the element class. Typings are written next to each component.

Changed from 0.2#

  • The component: / prop / --- header, {{ … }} and the mnix- directives are replaced; see docs/migrating-from-0.2.md. The compiler rejects each old form with a hint.
  • The minimum Rust version is 1.97 (required by the oxc JavaScript parser).

0.2.0 — 2026-09-30#

  • Compile-time mnix-if / mnix-else, mnix-each over string lists, and default and named slots with fallbacks; --slots input.

0.1.0#

  • Static compiler: component header with typed props, one-root templates, escaped interpolation, URL safety, source diagnostics, atomic --output.

Edit this page on GitHub · Zubra 6.0.4