@0k/kal-iroh-shell
v0.2.1
Published
Page kit of kal-iroh-shell: the page side of the reload handshake, and the Vite plugin that publishes interface releases.
Maintainers
Readme
@0k/kal-iroh-shell
Page side of kal-iroh-shell: the reload handshake run by the page (save what the user was doing, say when it is busy, restore focus after the reload), and the Vite plugin that publishes interface releases.
What it is
An app built with kal-iroh-shell (a Tauri or GTK program with a WebView) shows the interface its server publishes, and reloads it the moment a new version is published. The Rust shell, inside the app, follows the server's control stream; when a new release appears it asks the page to prepare, and the page answers through this package:
- the shell calls
window.__kalIrohShell.prepareReload(n); - the page runs every save callback and answers
ready, orbusywith a reason while the user is recording, uploading or sending; it renewsbusyand turnsreadyas soon as it can; - the shell reloads the view. A page that does not answer within 5 s,
or stops renewing
busyfor 30 s, is reloaded anyway; - after the reload, the page puts the focus back in the field the user was in.
The Vite plugin turns a successful vite build into a release: it
writes the build's ui-manifest.json and, given a publish directory,
copies the build there as a frozen <build-id>/ release and switches
current.json to it, by renames. A failed build publishes nothing.
Install
npm install @0k/kal-iroh-shellES modules with type declarations. The page kit (@0k/kal-iroh-shell)
runs in the browser and requires vue 3.3 or later. The plugin
(@0k/kal-iroh-shell/vite) runs in Node, from vite.config.ts, and
requires vite 5 to 8.
Usage
Build
// vite.config.ts
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';
import { kalIrohShellRelease } from '@0k/kal-iroh-shell/vite';
export default defineConfig({
plugins: [vue(), kalIrohShellRelease({ publishDir: process.env.MY_APP_PUBLISH_DIR })],
});List the plugin last (it is enforce: 'post'), and give each Vite
config its own instance. vite build --watch never publishes: every
save would push a release to every device. Without publishDir the
build only gets its ui-manifest.json (to be embedded in the app as the
fallback copy).
What the plugin does to the build and to the publish directory:
- It sets
base: './', so a release works under any path prefix. An app that sets its ownbasekeeps it, with a warning: its releases then only work under that prefix. - A relative
publishDiris relative to Vite'sroot;~/is expanded to the home directory; an empty one publishes nothing. The plugin refuses to publish into a directory that holds other files and nocurrent.jsonnaming a build id. - It writes and publishes only once every plugin has finished writing the build, files added while closing the bundle (a service worker) included. A build in which any plugin fails, or any output is not written, publishes nothing. SSR builds, library builds, watch mode and builds that write no files are left alone: no manifest, no publish.
- It keeps the current release and the 5 newest others
(
KEPT_RELEASES), for pages still running them, and deletes older releases and the copies of interrupted publishes, after the switch: a failure there is only a warning. It deletes nothing else: a release is a directory named by a build id whoseui-manifest.jsonnames that build id.
Page
import { installShellReload, restoreViewState, useShellBusy, useShellReloadSave } from '@0k/kal-iroh-shell';
installShellReload(); // before mounting
app.mount('#app');
restoreViewState(); // refocus the field the user was in
// in components / composables:
useShellReloadSave(() => flushDraft());
useShellBusy('microphone on', () => recording.value);API
@0k/kal-iroh-shell (page)
| Export | What it does |
|------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| installShellReload() | installs window.__kalIrohShell, which the shell calls, and saves the focused field before each reload; call it before mounting |
| restoreViewState() | after a reload, puts the focus back in the field the user was in (retried for RESTORE_FOCUS_MS) |
| useShellReloadSave(fn) | in a component (any Vue scope): run fn before a reload, until the scope ends |
| useShellBusy(reason, active) | in a component (any Vue scope): answer busy with reason while active() is true |
| onShellReloadSave(fn) | same as useShellReloadSave outside a component; returns the function that unregisters it |
| registerShellBusy(probe) | same as useShellBusy outside a component: probe() returns a reason or null; returns the function that unregisters it |
| prepareReload(n), saveViewState() | the steps installShellReload wires to the shell's request n; exported for apps without it |
| markBoot(phase), uiSource(), uiBuild() | boot timing marks sent to the shell, and the page's source (remote or embedded) and build id |
| BUSY_RENEW_MS, BUSY_CHECK_MS, RESTORE_FOCUS_MS, VIEW_STATE_KEY | timings of the handshake, and the sessionStorage key of the saved view |
| wire names (RELOAD_ACK_PATH, PAGE_GLOBAL, …) | paths, attributes and file names shared with the Rust shell |
| types BusyProbe, ReloadAck | a busy probe (returns a reason, or null when not busy), and the page's answer to the shell (ready, or busy with a reason) |
@0k/kal-iroh-shell/vite (build)
| Export | What it does |
|--------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| kalIrohShellRelease({ publishDir }) | the Vite plugin |
| publishRelease(dist, publishDir) | publishes a build that holds its manifest; returns its build id |
| writeManifest(dist, id), buildManifest(dist, id) | writes / computes a build's ui-manifest.json |
| pruneReleases(publishDir, keep), readPointer(publishDir), newBuildId() | the steps of a publish, for custom pipelines |
| MANIFEST_FILE, POINTER_FILE | the file names ui-manifest.json (in each release) and current.json (in publishDir) |
| KEPT_RELEASES | the number of releases kept besides the current one (5) |
| types KalIrohShellReleaseOptions, UiManifest, ManifestEntry, UiPointer | the plugin's options, and the shapes of ui-manifest.json and current.json |
Wire names
src/protocol.ts holds the paths, attributes and file names shared with
the Rust crate kal-iroh-shell-protocol. test/protocol.test.ts
compares them with a copy of that crate's src/lib.rs kept in
test/rust-protocol/ (SOURCE names the commit it comes from). After a
change of the Rust protocol, refresh the copy and fix this package until
the test passes:
npm run sync-protocol -- <kal-iroh-shell-checkout>
npm run checkTo try an unreleased change in an app, link the app's dependency to a
checkout of this repository (npm install in the checkout first; it
builds dist/, and npm run build rebuilds it after a change):
cd <app-frontend> && npm link <kal-iroh-shell-js-checkout>License
MIT
Changelog
0.2.1 (2026-10-30)
Changes
List the types of the page entry in the README. [Valentin Lab]
The API table of the page entry now also names
BusyProbeandReloadAck.List the constants and types of the
/viteentry in the README. [Valentin Lab]The API table of the
/viteentry now also namesMANIFEST_FILE,POINTER_FILE,KEPT_RELEASESand the exported types.
Fix
[reload] restore the focus to fields inside SVG content or dotted custom elements. [Valentin Lab]
The saved focus path named each element by its lowercased, unescaped tag name. WebKit matches SVG element names case-sensitively, so a field inside a
<foreignObject>was never found again, and a custom element whose name contains.read as a class selector. The path now uses each element's escapedlocalName.[vite] keep a published release frozen when the build output holds symlinks. [Valentin Lab]
publishReleasecopied the build with Node'scpSync, which keeps symlinks and points them back into the build directory (absolute targets), even withdereference. A published release with a symlinked file then changed whenever the next build rewrote that file, and the check of the copy against the manifest, which reads through the link, did not notice. The copy now writes the content of every file, symlinked ones included. As before, apublishDirinside the build directory is refused, now with an error that says so.[reload] restore the focus to the field the user was in, not an earlier look-alike. [Valentin Lab]
After a reload, the page put the focus back by a path of child positions that started below
<body>when no ancestor of the field had an id.querySelectorthen matched it anywhere in the page, so an earlier field nested the same way (inside a section placed before the field's own container) could get the focus, and the user's typing. The path now starts atbodyin that case.
0.2.0 (2026-10-28)
New
Publish the page kit and Vite plugin of
kal-iroh-shellas an npm package. [Valentin Lab]The page side of
kal-iroh-shell, for apps whose interface is published by a server and hot-reloaded, state saved, on every device: the reload handshake run by the page, and the Vite plugin that publishes interface releases. It comes from thejs/directory ofhttps://github.com/0k/kal-iroh-shellat commit16370642e7e31a287bc8210f3848dfefc1ef62ca.- Page kit (
@0k/kal-iroh-shell, browser, peervue^3.3): when the shell asks the page to prepare for a reload, the page runs every save callback, then answersready, orbusywith a reason while the user is in the middle of something (recording, uploading, sending), renewed until it clears and turnsready. A busy probe that throws counts as not busy. After the reload, the page puts the focus back in the field the user was in. - Vite plugin (
@0k/kal-iroh-shell/vite, Node, optional peervite^5 || ^6 || ^7 || ^8): it isenforce: 'post'and its write hooks areorder: 'post', sequential: true; list it last, and give each Vite config its own instance. It makes asset URLs relative (base: './', unless the app sets its ownbase), so a release works under any path prefix, and gives every successful build a build id and aui-manifest.json, files that other plugins add while closing the bundle included. Given a non-emptypublishDir(relative to Vite'sroot, a leading~expanded to the home directory), it copies the build there as a frozen release, checks the copy against the manifest, and switchescurrent.jsonto it, by renames. A build publishes only when no plugin failed and every configured output was written; otherwise nothing is published. The configured outputs are read when the bundle closes, so outputs that other plugins (@vitejs/plugin-legacy) add after the config is resolved count; a build configured with no output never publishes. The count of written outputs restarts in the bundler'soptionshook, once per build (every output included; Vite 8 runsbuildStartonce per output) and for eachbuild()of a reused builder, even when the previous build'scloseBundlewas skipped because another plugin's threw. SSR builds, library builds (build.lib), builds withbuild.write: falseand watch builds (vite build --watch, where every save would push a release to every device) are left alone: no manifest, no publish. It publishes only into a directory that does not exist yet, is empty (interrupted copies aside), or has acurrent.jsonnaming a build id. After the switch, pruning keeps the current release and the 5 newest others; it deletes older releases and the.partial-<build-id>copies of interrupted publishes, and nothing else (a release is a directory named by a build id whose manifest names that build id). Pruning is best effort: the release is already published, so its failure is only a warning. - Both are compiled ES modules, shipped with their type declarations.
- The wire names shared with the Rust shell are tested against a copy of
the Rust protocol crate's
src/lib.rs;npm run sync-protocolrefreshes that copy from akal-iroh-shellcheckout.
Contract:
@0k/kal-iroh-shellexportsinstallShellReload,restoreViewState,useShellReloadSave,useShellBusy,onShellReloadSave,registerShellBusy,prepareReload,saveViewState,markBoot,uiSource,uiBuild,BUSY_RENEW_MS,BUSY_CHECK_MS,RESTORE_FOCUS_MS,VIEW_STATE_KEY, the wire namesRELOAD_ACK_PATH,BOOT_MARK_PATH,STATUS_PATH,UI_SOURCE_ATTR,UI_BUILD_ATTR,PAGE_GLOBAL,POINTER_FILE,MANIFEST_FILE, and the typesBusyProbeandReloadAck.@0k/kal-iroh-shell/viteexportskalIrohShellRelease,publishRelease,pruneReleases,writeManifest,buildManifest,readPointer,newBuildId,KEPT_RELEASES,MANIFEST_FILE,POINTER_FILE, and the typesKalIrohShellReleaseOptions,ManifestEntry,UiManifestandUiPointer.- The shell calls
window.__kalIrohShell.prepareReload(n), installed byinstallShellReload; the page answers byPOST /__shell/reload-ack:ready, orbusyrenewed everyBUSY_RENEW_MS(10 s) while a busy probe holds; a probe that throws counts as not busy. kalIrohShellReleaseisenforce: 'post', hookswriteBundleandcloseBundlewithorder: 'post'andsequential: true, counts the outputs written in each build (the count restarts in the bundler'soptionshook, once per build, every output included, and for eachbuild()of a reused builder, even when the previous build'scloseBundlewas skipped), and publishes fromcloseBundleonly when no plugin failed and that count equals the outputs configured at that time (build.rollupOptions.output, orbuild.rolldownOptions.outputon Vite 8), at least one; otherwise it writes no manifest and publishes nothing. SSR builds, library builds, builds withbuild.write: falseand watch builds (vite build --watch) get no manifest and no publish; an emptypublishDirpublishes nothing.- A published release directory is never written again:
publishReleasechecks the copy against the manifest before renaming it into place, and fails, publishing nothing, when they differ (another publisher's pruning removed files). Publishing refuses a directory that holds other files and nocurrent.jsonnaming a build id; pruning deletes only older releases and.partial-<build-id>copies. Oncecurrent.jsonis switched, a pruning failure never failspublishRelease: it goes to its optional fourth argumentwarn(console.warnby default; the plugin passes Vite's logger). - Tests:
test/reload.test.ts,test/bootMark.test.ts,test/release.test.ts,test/plugin.test.ts(real builds that fail or succeed, several outputs included) andtest/protocol.test.ts(npm run check);npm run test:vite-matrixrunstest/plugin.test.tsandtest/release.test.tsagainst each Vite major of the peer range (5, 6, 7 and 8), each installed in a temporary directory (it needs the network).
- Page kit (
