Skip to content
Blackboard Framework

v2.0.4

Released 2026-10-18. Changes since v2.0.2, including updates to the paired Hutch toolchain since 0.27.1 and Cottontail runtime since 0.7.1.

Runtime defaults and migration

Section titled “Runtime defaults and migration”
  • Native Zig builds and the Zig WGPU template now use Zig 0.17.0. Updated the core, launcher, installer, SDK, and Kitchen Zig sources for the new compiler APIs and array initialization syntax. Windows launchers and installers retain GUI startup through the C runtime, and native update readers use the compiler’s corrected file-handle behavior. Projects with an explicit build.zig.version pin must select 0.17.0 for the updated Zig SDK.
  • Bundled archive and update tools now use Zig 0.17.0: zig-asar 0.2.8, zig-zstd 0.1.9, and zig-bsdiff 0.1.26. Archive and patch formats remain compatible with existing releases, and macOS 14 remains supported.
  • Bun is now the default JavaScript/TypeScript main process and the runtime used by Kitchen Sink. The Cottontail UI templates are ui-wgpu, ui-color-picker, and ui-launcher.
  • Cottontail remains supported as an experimental opt-in runtime. Select build.mainProcess: "cottontail" and configure build.cottontail to retain it. To use Bun, select "bun" and move the entrypoint and shared bundler options into build.bun. Cottontail-only capability and bytecode options do not apply to Bun. Older configs that omit mainProcess and provide only cottontail or main now report a migration error instead of silently changing runtimes.
  • The paired Hutch release defaults scripts, tests, shell tasks, and build hooks to Bun. HUTCH_RUNTIME=cottontail remains an explicit override; a Cottontail version pragma alone does not select the script runner. Internal config loading and bundling still use Hutch’s paired Cottontail.
  • This release pairs Hutch 0.28.1 with build-time Cottontail 0.7.2; packaged apps use Bun 1.4.0 by default or the devkit’s Cottontail 0.7.2 when explicitly selected. The script runner and app runtime are independent selections. See the migration guide.

Platforms and runtime improvements

Section titled “Platforms and runtime improvements”
  • Added native Windows ARM64 devkits, WebView2 and CEF artifacts, npm bootstrap support, and Zig, Rust, and Go main-process builds. The pinned Cottontail runtime supports JavaScriptCore’s Baseline, DFG, and FTL JIT tiers and WebAssembly on ARM64. Odin remains unsupported on Windows ARM64. Existing x64 installations require an explicit ARM64 installation to switch architectures.
  • Updated the optional Cottontail runtime with reduced long-lived memory retention, smaller worker bootstraps, reuse of bundled builtin modules, and improved reclamation of native allocator memory on Linux.
  • Fixed a Cottontail import-resolution crash caused by growing its directory cache while recursive resolution still used an earlier entry. Cache entries now retain stable addresses, including during Vite template builds.
  • Fixed edge and corner resizing for frameless Linux GTK windows with titleBarStyle: "hidden", without adding a system titlebar.
  • Fixed macOS WKWebView file navigation, copied inline HTML before asynchronous loading, and synchronized page-zoom reads with pending initialization and zoom changes. macOS CEF evaluation now checks browser readiness on the UI thread instead of dereferencing a not-yet-created browser, and Linux CEF retains navigation requested during asynchronous browser creation.
  • Fixed Windows WebView2 child-window ownership when restoring hidden or zero-sized panes, and corrected the visibility boolean ABI used by Core.
  • Linux display and cursor queries now wait for GTK initialization and execute on its UI thread. Linux window classes no longer repeat the channel suffix.
  • Fixed native text-bitmap pixel copying under Bun. GPU templates now handle surface readiness more reliably; the Rust graphics template reserves a larger Windows stack to avoid startup crashes.

Hutch and Cottontail

Section titled “Hutch and Cottontail”
  • Fixed memory growth in long-running Hutch watch sessions by releasing each filesystem scan’s temporary allocations and reclaiming each build’s state after its app process stops. Regression tests cover repeated scans and rebuilds.
  • Template initialization automatically uses the catalog’s matching Hutch toolchain when needed, allowing stable and beta templates to keep working while Hutch and Electrobun are released independently.
  • Hutch now preserves native Zig compiler caches under the project’s .hutch/cache/zig/<os>-<arch> directory across clean bundle builds.
  • Linux release archives use USTAR so installed updaters can extract them; paths that cannot be represented fail packaging instead of producing an incompatible update.
  • Hutch uses native Zig 0.17.0 compilers on Windows ARM64, including when its JavaScript caller runs under x64 emulation. Older x64-only Hutch releases remain installable on ARM64; switching an existing x64 installation to native ARM64 is explicit.
  • Fixed Linux terminal attribute handling in Hutch’s interactive picker and package-manager output, with PTY round-trip regression coverage.
  • Cottontail now reports Windows ARM64 machine architecture correctly and fixes accepted-socket ownership, holding reads until connection listeners can transfer the handle.

Messaging and updates

Section titled “Messaging and updates”
  • Fixed a Windows WebView2 crash when a view closed before its queued navigation ran. Queued navigation and other dispatched WebView operations retain their target and discard work for a removed view.
  • Windows Core queues and registries now use native Windows locks and condition variables. This avoids a parking handoff failure reproduced under x64 emulation on ARM64 that could leave WebView messages, navigation, and graceful quit or update requests stuck while the window remained interactive.
  • Fixed Cottontail WebView RPC hangs when an idle readiness pipe produced EAGAIN. The notification stream waits for pipe readiness and owns a separate descriptor, so closing it cannot invalidate the native core’s pipe. Stream errors or closure fall back to polling.
  • Improved host-to-WebView burst delivery with byte-limited batches and bounded work per event-loop turn. Removed duplicate fallback records and quadratic queue cleanup. BrowserView.getHostMessageQueueStats() exposes queue depth, serialized byte counts, message age, and peak usage for diagnostics; it does not measure WebView rendering or delivery acknowledgements.
  • Fixed update-archive inspection on Bun so an asynchronous stream cleanup cannot close a file descriptor already reused by another operation. The archive reader now owns and closes its descriptor exactly once.
  • Patch chains delete each consumed patch and superseded intermediate tar after validating the next archive, bounding temporary disk use instead of retaining every hop. The original cached tar is normally preserved for retry; detected disk-full errors remove it before full-download fallback on macOS, Windows, and Linux. The installed application is not removed by this cleanup.
  • Fixed Windows updater relaunch by registering scheduled-task actions with structured arguments and preserving the helper’s temporary-directory paths.

Release validation

Section titled “Release validation”
  • VM and release checks now retain each stage’s output, command, exit status, and runtime details, and print the log location on failure.
  • Nested builds and tests preserve the selected Hutch launcher, so native ARM64 runs cannot silently switch to an x64 hutch on PATH. Rust and Go compiler caches validate the host architecture as well as the version.
  • Kitchen’s Rust, Go, and Zig navigation tests isolate callback evidence by view, event, and URL, preventing delayed callbacks from affecting another test. Deterministic regression tests cover those callback orderings.
  • Added public npm bootstrap and template acceptance across all five release platforms, including Windows ARM64. Template checks initialize, install, build, and launch the public hello-world template, then exercise optional Cottontail capabilities and a WebView RPC round trip in a separate fixture. Stable releases verify that the default production Hutch installer can use the newly published template catalog.
  • Verify exact pinned Hutch, script runtime, and packaged runtime provenance independently of later channel updates. Runtime tests use real Bun while retaining explicit Cottontail compatibility coverage.
  • Fixed Kitchen artifact publication under Bun by using signed single PUTs instead of the stalled multipart upload path, with per-file completion logs and five-minute upload deadlines. The standard release workflow validates the uploader before publishing Kitchen and the matching template catalog.
  • The complete test:vm matrix now gates release publication on macOS ARM64, Linux x64/ARM64, and Windows x64/ARM64. It exercises packaged apps, native main processes, both JavaScript runtimes, RPC, and updater lifecycle behavior.
  • Post-publication desktop smoke tests use the interactive template picker after npm and templates are published (hutch electrobun init --beta for beta releases). They install and interact with Bunny, Zig WGPU, Odin Fluid, Rust Flock, Go Maze, and Cottontail UI; Odin is skipped on Windows ARM64 because its toolchain is unavailable there.
  • Kitchen smoke tests check mask text selection after a double-click, embedded webview positioning while scrolling the host, and the interactive Warren playground. Reports, logs, and screenshots are retained as workflow artifacts.
  • Documented macOS development signing and Keychain identity changes across native rebuilds. See Code signing.