Repository navigation
v0.3.0
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-appDocumentation: skathi.land
Highlights
- The window API on every platform.
appWindowverbs (maximize, restore, center, show/hide,setBounds, always on top,startDragging) and its state reads now work on macOS and Linux.app-regionand--window-controlwork on macOS. See the Window API reference and the window guides. - Svelte matches Vue.
@skathi-native/runtime/svelteexports everything a Svelte app needs, including a Svelte<SkWindow>for pop-out windows.appWindowreads are reactive in templates,$derivedand$effect. position: sticky, both axes and nested scrollers, with no relayout or JavaScript on scroll.- CSS checks.
sk check,sk build,sk publishandsk devreport 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
skathifacade crate, thesk-*crates,skathi-gpui-*,redjsandskathi-taffy. - Reference docs and guides on skathi.land: searchable CSS, web platform, Window API, App API and
sk.config.jsonreferences, and new guides.
New features
Windows, macOS and Linux
appWindowon macOS and Linux:maximize,unmaximize,restore,center,show,hide,setBounds,alwaysOnTop,startDraggingand 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-regionand--window-controlwork on macOS. On macOS and Linux, a custom close button goes throughclose-requested,beforeunloadandpagehide, as it does on Windows.singleInstanceand the raise on a second launch work on macOS.window.maximizable,minimizableandresizableinsk.config.jsonapply on every platform.appWindowreceivesresize,focusandblurevents.defineWindowacceptstheme.<SkWindow>:backdrop,titleBarHeightandactivatecan be changed after the window opens. Changing a creation-time prop prints an advisory. A pop-out withoutx/yopens on the main window's monitor; one withx/yopens 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/sveltere-exports theapp*APIs,appWindow,defineWindowandgetCurrentWindow, and adds a Svelte<SkWindow>built on the same core as the Vue component. Theapp*APIs can also be imported from@skathi-native/runtimein either framework.appWindowreads are reactive in Svelte templates,$derivedand$effect.sk devcompiles.sveltefiles shipped inside npm packages, for example component libraries.
CSS
position: sticky: insets on all four sides in px, %, rem andcalc(), both axes, nested scroll containers. Geometry reads (getBoundingClientRect,offsetTop,elementFromPoint, hit tests,IntersectionObserver) report the stuck position, including right afterscrollTopis set. A sticky box is a stacking context at itsz-index.getComputedStyle().positionreturns"sticky".@keyframesandelement.animate()animate--shading, as the docs said they did. It is still excluded fromtransition: 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
:stylethat 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 oneMutationObserverrecord. See the upgrade notes for how this interacts with directel.stylewrites. - Types for APIs the engine already had:
AnalyserNodedecibel range and float/byte reads,AudioBufferSourceNodeloop fields andstart(when, offset, duration),navigator.mediaSessionwithMediaMetadata(Windows and macOS), andimport.meta.hotinenv.d.ts.
CLI and tooling
-
CSS checks.
sk checkreads<style>blocks in Vue and Svelte files, staticstyleattributes, imported CSS with its@imports, andindex.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-depsskips dependencies)
Nothing inside
@supports,var()values or CSS-wide keywords is reported.sk buildandsk publishprint the same warnings for the CSS they bundle and never fail on them.sk devchecks at startup and then checks each file you edit, printing each warning once per session.check.allowinsk.config.jsonapplies to all of them. -
Two new templates from skathi-templates:
player, a music player in Svelte 5 with shader effects, andweather, a Vue weather app whose sky and rain are shaders. Usesk create --template player|weatheror pick one inbun 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.pngreplaces the Skathi icon in the created app. -
sk createwrites"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.tsrun from an app folder defaults to that app'sdist/.sk-dev. When there is no handshake, it tells you to runsk dev.
Documentation
- New references: Window API, App APIs (tray, hotkeys, storage, shell, permissions, capture, locale, launch,
appHost,appDevtools),sk.config.json(generated from the schema), and a searchable web platform reference. Each has a page per entry and per-platform support. - New guides: the four window guides, AOT compilation, Best practices, Devtools, Testing and Performance advisories. The Quick start covers Vue and Svelte.
- Code samples are type-checked against the runtime, and samples with both variants have a Vue/Svelte switch. Every page has a Markdown copy, and the site serves llms.txt.
Embedding (Rust)
- New
skathicrate: the single dependency for embedding Skathi in your own executable. It re-exports the embedding API (Builder,Handle,HostContextand the rest), tray, hotkeys andrun_exe. It mirrorssk-app's features, withprodon by default. Throughlinksmetadata it reports the linker arguments and Windows resources your executable must carry (DEP_SKATHI_LINK_ARGS,DEP_SKATHI_WINDOWS_RESOURCES). Build the payload withsk build --payload-onlyorsk publish --payload-only. See docs.rs/skathi. redjsbuilds 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-delayortransition-delaystarts the animation part-way through. Before, it was clamped to0s, so staggered animations ran in phase. :focus,:focus-visibleand:focus-withinon an ancestor (.slider:focus .thumb) apply. Before, these rules were dropped with an advisory.--shadingfades 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 devpicks up the first shader of an app that started with none, without a restart.
Windows
center()converts CSS px using the window's scale.setBoundsclamps to the monitor the new rectangle is on, so a window can move to another monitor.matchMediain aresizehandler sees the new size.pagehidefires exactly once on every close and quit path.- The fallback title bar follows
titleandtitleBarHeight. Default caption glyph colours follow light and dark mode. - A main-window
minWidthorminHeightapplies on its own, without the other. removeEventListener("close-requested")is counted.el.click()on a--window-controlelement performs its action.<SkWindow>:@showfires for a pop-out that opens visible, and@closefires whenv-ifunmounts 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 sendssource: "open-url"on Windows."reopen", which was never sent, is removed from the type.- Linux permissions tell the truth:
appPermissions.platformis"Linux", the microphone readsgranted(the desktop does not gate it), the camera and screen captureunsupported, and no Allow/Block prompt is shown. - Types for what the engine has: the full
URLinterface withURL.canParse(),URLSearchParams, and theconsolemethods (infoanddebugare 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 devresolves relative URLs from the app root recorded inmanifest.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.0range does not match 0.3.0. Set@skathi-native/runtimeand@skathi-native/clito^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 checkuses. New apps get"typescript": "^6"; for existing apps:- Remove
baseUrlfrom yourtsconfig.json. It is deprecated in TS 6 (TS5101).pathsresolve relative to the config file. noUncheckedSideEffectImportsis on by default, soimport "./app.css"needs a declaration. The runtime now ships one, through@skathi-native/runtime/tsconfig.app.json. If your tsconfig extends that file but overridesfiles, adddeclare module "*.css" {}yourself.esModuleInteropis always on; you can remove it.
- Remove
:styleand directel.stylewrites. A re-render whose:stylevalues are unchanged no longer touches the element. A directel.stylewrite to a property the:stylealso 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()andresizeBy()set the outer window size, as in browsers.- Negative delays are honoured.
animation-delayandtransition-delaybelow zero start part-way through. A transition whose duration plus delay is ≤ 0 does not run.getComputedStylereports the signed value. - Ancestor
:focusrules now match. Rules like.field:focus-within .labelthat used to be dropped now apply, which can change how your app looks. - Content effects are stacking contexts. An element whose
--shadingeffect reads its own content ([SkContent]) now contains thez-indexof its positioned descendants, as an element with afilterdoes. [SkAnimated]contract. The host now integrates speed over time and writesphase / timeinto the speed slot. Use the[SkAnimated]parameter only as the factor ininput.time * speed, as every built-in effect does andsk.slangnow 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-skathifollows the release. The publishedcreate-skathi0.2.0 pinned CLI 0.2.0. From 0.3.0 on, it is released with each tag, sobun create skathicreates apps on the current version.- Corrected schema descriptions; behaviour is unchanged.
window.frame: falseonly prints an advisory and does not hide the title bar; usetitleBarStyle: "hidden".titleBarStyle: "hiddenInset"is treated as"hidden"on every OS, with an advisory.titleBarFallbackdraws a strip until the app paints its firstapp-region: dragarea. - 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 invendor/zed. Its packages areskathi-gpui-*, and taffy isskathi-taffy; the library names (gpui,taffy) are unchanged. Update any[patch]entries. The engine pin moved tovendor/redjs/redjs/pins.txt. On Windows,redjsrequires+crt-static. @skathi-native/test(run from a checkout; not on npm).toHaveComputedStylenow compares against the app'sgetComputedStyle(). The old engine style-dump matcher is nowtoHaveEngineStyle.
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:
appShellcalls (openExternal,openPath,showItemInFolder,trashItem) reject withENOSYS. - macOS: the bundle declares the
"protocols"schemes, but a link that opens the app is not delivered toappLaunch, sosource: "open-url"is sent on Windows only. <dialog>: only theopenattribute works;show(),showModal(),close()andreturnValueare missing.appLaunch.registerProtocol()is Windows-only. On macOS and Linux, it throwsNotSupportedError, andunregisterProtocol()returnsfalse. 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; thesk-*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-gpuiand theskathi-gpui-*crates;redjs,redjs-macros,redjs-webgpu;skathi-taffy0.15.0. - Prebuilt hosts for Windows x64, macOS arm64 and Linux x64, plus
sk-aotfor Windows x64, are attached below.sk buildandsk devdownload 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