Skip to content

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 17 Nov 02:14
· 166 commits to master since this release

Skathi 0.3.0 brings the window API to macOS and Linux, gives Svelte apps the same window and pop-out support as Vue apps, and adds position: sticky. The CLI now warns about CSS the engine does not support and, under sk dev, about renders that waste work. The Rust crates are on crates.io for the first time, with a new skathi crate for embedding the engine in your own executable.

bun create skathi my-app

Documentation: skathi.land

Highlights

  • The window API on every platform. appWindow verbs (maximize, restore, center, show/hide, setBounds, always on top, startDragging) and its state reads now work on macOS and Linux. app-region and --window-control work on macOS. See the Window API reference and the window guides.
  • Svelte matches Vue. @skathi-native/runtime/svelte exports everything a Svelte app needs, including a Svelte <SkWindow> for pop-out windows. appWindow reads are reactive in templates, $derived and $effect.
  • position: sticky, both axes and nested scrollers, with no relayout or JavaScript on scroll.
  • CSS checks. sk check, sk build, sk publish and sk dev report properties, values, selectors and at-rules the engine does not support, with file and line (SK4001–SK4005).
  • Performance advisories under sk dev. The runtime warns when an update re-renders far more than it changes, and the devtools Performance tab shows the same hint on the recorded frame. Production builds contain none of this code.
  • TypeScript 6 in the CLI and in new apps.
  • Rust crates on crates.io: the skathi facade crate, the sk-* crates, skathi-gpui-*, redjs and skathi-taffy.
  • Reference docs and guides on skathi.land: searchable CSS, web platform, Window API, App API and sk.config.json references, and new guides.

New features

Windows, macOS and Linux

  • appWindow on macOS and Linux: maximize, unmaximize, restore, center, show, hide, setBounds, alwaysOnTop, startDragging and the state reads. maximize() never toggles on any platform.
  • Under Wayland, the compositor does not let an app place, hide or keep its window on top. These calls print an advisory instead (a size still applies).
  • app-region and --window-control work on macOS. On macOS and Linux, a custom close button goes through close-requested, beforeunload and pagehide, as it does on Windows.
  • singleInstance and the raise on a second launch work on macOS.
  • window.maximizable, minimizable and resizable in sk.config.json apply on every platform.
  • appWindow receives resize, focus and blur events.
  • defineWindow accepts theme.
  • <SkWindow>: backdrop, titleBarHeight and activate can be changed after the window opens. Changing a creation-time prop prints an advisory. A pop-out without x/y opens on the main window's monitor; one with x/y opens on the monitor at that position. Pop-outs created hidden can be shown on macOS and Linux.
  • Guides: Windows, Custom title bars, Pop-out windows, Closing and running in the background.

Svelte

  • @skathi-native/runtime/svelte re-exports the app* APIs, appWindow, defineWindow and getCurrentWindow, and adds a Svelte <SkWindow> built on the same core as the Vue component. The app* APIs can also be imported from @skathi-native/runtime in either framework.
  • appWindow reads are reactive in Svelte templates, $derived and $effect.
  • sk dev compiles .svelte files shipped inside npm packages, for example component libraries.

CSS

  • position: sticky: insets on all four sides in px, %, rem and calc(), both axes, nested scroll containers. Geometry reads (getBoundingClientRect, offsetTop, elementFromPoint, hit tests, IntersectionObserver) report the stuck position, including right after scrollTop is set. A sticky box is a stacking context at its z-index. getComputedStyle().position returns "sticky".
  • @keyframes and element.animate() animate --shading, as the docs said they did. It is still excluded from transition: all.
  • The CSS reference is now a searchable catalog with a page per property, value and selector. Each page shows per-platform support, the release the entry arrived in, examples, edge cases and workarounds.

Runtime and DOM

  • An object :style that re-renders with the same values no longer calls the host. A changed one is one host call per element, which writes only the declarations that differ and produces one MutationObserver record. See the upgrade notes for how this interacts with direct el.style writes.
  • Types for APIs the engine already had: AnalyserNode decibel range and float/byte reads, AudioBufferSourceNode loop fields and start(when, offset, duration), navigator.mediaSession with MediaMetadata (Windows and macOS), and import.meta.hot in env.d.ts.

CLI and tooling

  • CSS checks. sk check reads <style> blocks in Vue and Svelte files, static style attributes, imported CSS with its @imports, and index.html. It warns with file and line:

    • SK4001: a property the engine does not support
    • SK4002: a value or function it does not apply
    • SK4003: a selector that can never match
    • SK4004: an at-rule whose rules are dropped
    • SK4005: one summary per dependency package (--no-deps skips dependencies)

    Nothing inside @supports, var() values or CSS-wide keywords is reported. sk build and sk publish print the same warnings for the CSS they bundle and never fail on them. sk dev checks at startup and then checks each file you edit, printing each warning once per session. check.allow in sk.config.json applies to all of them.

  • Two new templates from skathi-templates: player, a music player in Svelte 5 with shader effects, and weather, a Vue weather app whose sky and rain are shaders. Use sk create --template player|weather or pick one in bun create skathi. An installed CLI downloads the template from the commit the release pinned, so the npm package does not carry the demo media.

  • A template's own icon.png replaces the Skathi icon in the created app.

  • sk create writes "typescript": "^6".

Devtools

  • Performance advisories. Under sk dev, a [skathi perf] line is printed once per cause, and a hint is added to the recorded frame in the Performance tab:
    • wasted-render: a Vue update re-rendered 500+ elements and under 5% changed. Names the reactive values and the input event that triggered it.
    • long-list: a list of 50+ items re-rendered while under 25% of it was visible in its scroll container.
    • host-writes: 1000+ style, class, attribute and text writes in one frame, with the top three components.
  • A screenshot of an unknown window id is an error, instead of a capture of the first visible window.
  • devtools/ctl.ts run from an app folder defaults to that app's dist/.sk-dev. When there is no handshake, it tells you to run sk dev.

Documentation

Embedding (Rust)

  • New skathi crate: the single dependency for embedding Skathi in your own executable. It re-exports the embedding API (Builder, Handle, HostContext and the rest), tray, hotkeys and run_exe. It mirrors sk-app's features, with prod on by default. Through links metadata it reports the linker arguments and Windows resources your executable must carry (DEP_SKATHI_LINK_ARGS, DEP_SKATHI_WINDOWS_RESOURCES). Build the payload with sk build --payload-only or sk publish --payload-only. See docs.rs/skathi.
  • redjs builds from crates.io without a checkout or setup step. It downloads the pinned JavaScriptCore prebuilt into a shared cache (REDJS_CACHE_DIR, otherwise your user cache directory) and checks its hash.

Fixes

CSS and effects

  • A negative animation-delay or transition-delay starts the animation part-way through. Before, it was clamped to 0s, so staggered animations ran in phase.
  • :focus, :focus-visible and :focus-within on an ancestor (.slider:focus .thumb) apply. Before, these rules were dropped with an advisory.
  • --shading fades in from, and out to, an element with no effect, instead of snapping.
  • Changing or transitioning an [SkAnimated] speed no longer makes the animation jump. The motion continues from where it is.
  • Absolutely positioned, fixed and z-indexed descendants are part of a content effect's ([SkContent]) input. Before, they were painted after the effect captured its content.
  • sk dev picks up the first shader of an app that started with none, without a restart.

Windows

  • center() converts CSS px using the window's scale.
  • setBounds clamps to the monitor the new rectangle is on, so a window can move to another monitor.
  • matchMedia in a resize handler sees the new size.
  • pagehide fires exactly once on every close and quit path.
  • The fallback title bar follows title and titleBarHeight. Default caption glyph colours follow light and dark mode.
  • A main-window minWidth or minHeight applies on its own, without the other.
  • removeEventListener("close-requested") is counted.
  • el.click() on a --window-control element performs its action.
  • <SkWindow>: @show fires for a pop-out that opens visible, and @close fires when v-if unmounts it.

Svelte and runtime

  • A Svelte app with an <input> or <a> mounts. Before, mounting failed. A detached <input type=file> or <a download> clicked from script still opens the picker or saves the file.
  • A later mount() from @skathi-native/runtime/svelte, for example into a pop-out, no longer replaces the app's teardown. A reload unmounts everything, newest first.
  • appLaunch: a second launch started for a link to a registered scheme sends source: "open-url" on Windows. "reopen", which was never sent, is removed from the type.
  • Linux permissions tell the truth: appPermissions.platform is "Linux", the microphone reads granted (the desktop does not gate it), the camera and screen capture unsupported, and no Allow/Block prompt is shown.
  • Types for what the engine has: the full URL interface with URL.canParse(), URLSearchParams, and the console methods (info and debug are no longer optional).
  • The first Element.animate() call no longer prints a misleading [skathi compat] note about motion/framer-motion.
  • A dev host started without sk dev resolves relative URLs from the app root recorded in manifest.json, so it works for apps outside the directory the host was built in.

Breaking changes and upgrade notes

  • Bump both packages. A ^0.2.0 range does not match 0.3.0. Set @skathi-native/runtime and @skathi-native/cli to ^0.3.0. The CLI depends on the runtime at exactly its own version.
  • TypeScript 6. The CLI now depends on TypeScript 6, which sk check uses. New apps get "typescript": "^6"; for existing apps:
    • Remove baseUrl from your tsconfig.json. It is deprecated in TS 6 (TS5101). paths resolve relative to the config file.
    • noUncheckedSideEffectImports is on by default, so import "./app.css" needs a declaration. The runtime now ships one, through @skathi-native/runtime/tsconfig.app.json. If your tsconfig extends that file but overrides files, add declare module "*.css" {} yourself.
    • esModuleInterop is always on; you can remove it.
  • :style and direct el.style writes. A re-render whose :style values are unchanged no longer touches the element. A direct el.style write to a property the :style also sets now stays until that binding changes. When it changes, the bound values are written back, as in React. Give each property one owner: the template, or code holding a template ref. See Best practices.
  • resizeTo() and resizeBy() set the outer window size, as in browsers.
  • Negative delays are honoured. animation-delay and transition-delay below zero start part-way through. A transition whose duration plus delay is ≤ 0 does not run. getComputedStyle reports the signed value.
  • Ancestor :focus rules now match. Rules like .field:focus-within .label that used to be dropped now apply, which can change how your app looks.
  • Content effects are stacking contexts. An element whose --shading effect reads its own content ([SkContent]) now contains the z-index of its positioned descendants, as an element with a filter does.
  • [SkAnimated] contract. The host now integrates speed over time and writes phase / time into the speed slot. Use the [SkAnimated] parameter only as the factor in input.time * speed, as every built-in effect does and sk.slang now documents. An effect that uses it for anything else sees a different value after the speed changes.
  • Svelte elements. document.createElement("input") and ("a") return a regular element that is detached until inserted. focus() on a detached element does nothing, as in a browser.
  • create-skathi follows the release. The published create-skathi 0.2.0 pinned CLI 0.2.0. From 0.3.0 on, it is released with each tag, so bun create skathi creates apps on the current version.
  • Corrected schema descriptions; behaviour is unchanged. window.frame: false only prints an advisory and does not hide the title bar; use titleBarStyle: "hidden". titleBarStyle: "hiddenInset" is treated as "hidden" on every OS, with an advisory. titleBarFallback draws a strip until the app paints its first app-region: drag area.
  • Rendering. gpui is updated to Zed v1.30: paths are rasterised as analytic tiles instead of MSAA triangles, and shadows use a different blur approximation. Antialiased edges and shadows can differ slightly from 0.2.
  • Building from source or patching crates. gpui is now vendor/gpui (skathi-gpui) instead of the full Zed fork in vendor/zed. Its packages are skathi-gpui-*, and taffy is skathi-taffy; the library names (gpui, taffy) are unchanged. Update any [patch] entries. The engine pin moved to vendor/redjs/redjs/pins.txt. On Windows, redjs requires +crt-static.
  • @skathi-native/test (run from a checkout; not on npm). toHaveComputedStyle now compares against the app's getComputedStyle(). The old engine style-dump matcher is now toHaveEngineStyle.

Experimental: AOT

sk build --aot and sk publish --aot compile the app's JavaScript to a native image. AOT is still experimental, works on Windows x64 only, and is currently slower than the JIT in Skathi's own benchmark: 584 ms against 437 ms for the first round, and 550 ms against 447 ms for the last. Measure your app with and without SK_APP_ENGINE=jit before relying on it.

In this release, the AOT toolchain moves to JavaScriptCore autobuild-3bc94211 and Bun 237bba51e. On the apps measured, compiles are about 5–7× faster (for example, 14.4 s to 2.0 s for the hello app), and images are 12–24% smaller. The guide is reworked: AOT compilation.

Known issues

  • macOS: appShell calls (openExternal, openPath, showItemInFolder, trashItem) reject with ENOSYS.
  • macOS: the bundle declares the "protocols" schemes, but a link that opens the app is not delivered to appLaunch, so source: "open-url" is sent on Windows only.
  • <dialog>: only the open attribute works; show(), showModal(), close() and returnValue are missing.
  • appLaunch.registerProtocol() is Windows-only. On macOS and Linux, it throws NotSupportedError, and unregisterProtocol() returns false. On Linux, no scheme is registered.
  • Wayland: window position, hide and always-on-top are not available. These calls print an advisory.
  • position: sticky: a transform between the sticky box and its scroll container is not taken into account.

Packages

All at 0.3.0 unless noted.

  • npm: @skathi-native/runtime, @skathi-native/cli, create-skathi.
  • crates.io (first publication): skathi; the sk-* crates (sk-app, sk-clipboard, sk-css, sk-desktop, sk-effects, sk-elements, sk-hotkeys, sk-locale, sk-lottie, sk-payload, sk-permissions, sk-resample, sk-runtime, sk-sticker, sk-storage, sk-thorvg-sys, sk-tree, sk-video, sk-vpx-sys, sk-webview, sk-yuv); skathi-gpui and the skathi-gpui-* crates; redjs, redjs-macros, redjs-webgpu; skathi-taffy 0.15.0.
  • Prebuilt hosts for Windows x64, macOS arm64 and Linux x64, plus sk-aot for Windows x64, are attached below. sk build and sk dev download them automatically.

Internal: the documentation site and its worker, CI that skips documentation-only changes, and an e2e harness that runs on macOS and Linux.

Full Changelog: v0.2.0...v0.3.0