npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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.

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:

  1. the shell calls window.__kalIrohShell.prepareReload(n);
  2. the page runs every save callback and answers ready, or busy with a reason while the user is recording, uploading or sending; it renews busy and turns ready as soon as it can;
  3. the shell reloads the view. A page that does not answer within 5 s, or stops renewing busy for 30 s, is reloaded anyway;
  4. 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-shell

ES 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 own base keeps it, with a warning: its releases then only work under that prefix.
  • A relative publishDir is relative to Vite's root; ~/ is expanded to the home directory; an empty one publishes nothing. The plugin refuses to publish into a directory that holds other files and no current.json naming 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 whose ui-manifest.json names 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 check

To 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 BusyProbe and ReloadAck.

  • List the constants and types of the /vite entry in the README. [Valentin Lab]

    The API table of the /vite entry now also names MANIFEST_FILE, POINTER_FILE, KEPT_RELEASES and 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 escaped localName.

  • [vite] keep a published release frozen when the build output holds symlinks. [Valentin Lab]

    publishRelease copied the build with Node's cpSync, which keeps symlinks and points them back into the build directory (absolute targets), even with dereference. 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, a publishDir inside 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. querySelector then 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 at body in that case.

0.2.0 (2026-10-28)

New

  • Publish the page kit and Vite plugin of kal-iroh-shell as 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 the js/ directory of https://github.com/0k/kal-iroh-shell at commit 16370642e7e31a287bc8210f3848dfefc1ef62ca.

    • Page kit (@0k/kal-iroh-shell, browser, peer vue ^3.3): when the shell asks the page to prepare for a reload, the page runs every save callback, then answers ready, or busy with a reason while the user is in the middle of something (recording, uploading, sending), renewed until it clears and turns ready. 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 peer vite ^5 || ^6 || ^7 || ^8): it is enforce: 'post' and its write hooks are order: '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 own base), so a release works under any path prefix, and gives every successful build a build id and a ui-manifest.json, files that other plugins add while closing the bundle included. Given a non-empty publishDir (relative to Vite's root, a leading ~ expanded to the home directory), it copies the build there as a frozen release, checks the copy against the manifest, and switches current.json to 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's options hook, once per build (every output included; Vite 8 runs buildStart once per output) and for each build() of a reused builder, even when the previous build's closeBundle was skipped because another plugin's threw. SSR builds, library builds (build.lib), builds with build.write: false and 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 a current.json naming 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-protocol refreshes that copy from a kal-iroh-shell checkout.

    Contract:

    • @0k/kal-iroh-shell exports installShellReload, restoreViewState, useShellReloadSave, useShellBusy, onShellReloadSave, registerShellBusy, prepareReload, saveViewState, markBoot, uiSource, uiBuild, BUSY_RENEW_MS, BUSY_CHECK_MS, RESTORE_FOCUS_MS, VIEW_STATE_KEY, the wire names RELOAD_ACK_PATH, BOOT_MARK_PATH, STATUS_PATH, UI_SOURCE_ATTR, UI_BUILD_ATTR, PAGE_GLOBAL, POINTER_FILE, MANIFEST_FILE, and the types BusyProbe and ReloadAck.
    • @0k/kal-iroh-shell/vite exports kalIrohShellRelease, publishRelease, pruneReleases, writeManifest, buildManifest, readPointer, newBuildId, KEPT_RELEASES, MANIFEST_FILE, POINTER_FILE, and the types KalIrohShellReleaseOptions, ManifestEntry, UiManifest and UiPointer.
    • The shell calls window.__kalIrohShell.prepareReload(n), installed by installShellReload; the page answers by POST /__shell/reload-ack: ready, or busy renewed every BUSY_RENEW_MS (10 s) while a busy probe holds; a probe that throws counts as not busy.
    • kalIrohShellRelease is enforce: 'post', hooks writeBundle and closeBundle with order: 'post' and sequential: true, counts the outputs written in each build (the count restarts in the bundler's options hook, once per build, every output included, and for each build() of a reused builder, even when the previous build's closeBundle was skipped), and publishes from closeBundle only when no plugin failed and that count equals the outputs configured at that time (build.rollupOptions.output, or build.rolldownOptions.output on Vite 8), at least one; otherwise it writes no manifest and publishes nothing. SSR builds, library builds, builds with build.write: false and watch builds (vite build --watch) get no manifest and no publish; an empty publishDir publishes nothing.
    • A published release directory is never written again: publishRelease checks 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 no current.json naming a build id; pruning deletes only older releases and .partial-<build-id> copies. Once current.json is switched, a pruning failure never fails publishRelease: it goes to its optional fourth argument warn (console.warn by 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) and test/protocol.test.ts (npm run check); npm run test:vite-matrix runs test/plugin.test.ts and test/release.test.ts against each Vite major of the peer range (5, 6, 7 and 8), each installed in a temporary directory (it needs the network).