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

@adea-ai/app-framework

v0.45.0

Published

Reusable application framework for Adea and Cortana. It provides the shared application shell and appearance surfaces, an Electrobun desktop host and service bridge, application generation, packaging, updater, and release tools. Each consuming app supplie

Readme

App framework

Reusable application framework for Adea and Cortana. It provides the shared application shell and appearance surfaces, an Electrobun desktop host and service bridge, application generation, packaging, updater, and release tools. Each consuming app supplies its identity, navigation, views, services, and application-specific security policy. The framework docs cover that ownership split, the acceptance gates and the update design.

Contents

Serving the client

serveClient(request, { root, deniedPaths, transformHtml, streamAssets }) serves a local SPA, rejects paths that escape its root, and lets the app exclude asset trees and inject its bootstrap into HTML. It does not authenticate bridge requests or start an HTTP server; the host application owns both. HEAD responses contain no body and report the representation's byte length. HTML transforms still run for HEAD requests so their resulting length can be reported.

A missing path falls back to index.html unless it names a built asset: a .js, .mjs, .css, .map, .woff2 or .wasm file, or any path under /assets or under a prefix listed in assetPrefixes (for example ['/start-assets']). Those answer 404, so a stale chunk after an update fails as a missing module instead of a MIME error on HTML.

@adea-ai/app-framework/bounded-body reads request and response bodies with a byte bound: readBoundedBytes, readBoundedText and readBoundedJson(source, limit, { signal, allowEmpty }). A Content-Length above the bound is refused before any byte is read, the streamed bytes are bounded whatever the claim says, and an abort (a request's own signal by default) settles a stalled read at once. A refusal is a BoundedBodyError whose reason (too-large, aborted, invalid, missing) boundedBodyStatus maps to 413, 408 or 400.

Responses are buffered snapshots by default. Set streamAssets: true for an immutable asset root, or streamClientAssets: true on startDesktopHost; streamed bodies are not snapshots and read errors can surface after response headers are sent. A streamed body opens its file on the first read, not when the response is created, and closes it at end of file, on cancellation, on a read error, and when the host stops (server.stop(true) cancels open bodies; a retained-lease host drains them before releasing its lease). A client that stops reading without closing the connection is bounded by the server's idle timeout (idleTimeoutSeconds, default 10 s), which cancels the body and closes the file, so open asset files never exceed open asset connections. The host also admits at most maxOpenClientAssetFiles (default 32) open asset files; later readers wait in order without a descriptor, and a waiting reader that is cancelled leaves the queue. Streamed read buffers are therefore bounded by that limit times one 64 KiB read chunk, and a response that is never read holds neither a descriptor nor a slot. serveClient callers get the same bound by passing a shared openFileLimit from createClientAssetFileLimit. The opened file is compared with the path's earlier stat (device, inode, size and times) and a mismatch fails the stream instead of serving other bytes; containment is still checked by path, so streaming assumes nobody swaps symlinks inside the root while it is served.

serveClient is one of the framework's desktop building blocks. Source adapted from adea-ai/adea at commit 6155d18941acbb14d9099bc2a33a50ee9683a068, apps/desktop/shell/src/client-assets.ts (Apache-2.0).

Update state and release versions

toUpdateState maps native update snapshots to the published UI update-dialog contract. Applications retain ownership of updater trust, confirmation, and whether release notes are shown.

release-version validates the stable and pre-release update channels (readUpdateChannel also reads a retired dev value as pre-release) and orders update versions by semver on every channel. It was adapted from apps/desktop/shell/src/updates.ts in adea-ai/adea at commit 6155d18941acbb14d9099bc2a33a50ee9683a068 (Apache-2.0). Shared release, platform packaging, and signed-update modules are documented below; application credentials and product-specific release policy stay with each consumer.

Release qualification checks attested platform installer evidence and asset sizes and SHA-256 digests against the release, and checks the exact producing workflow run and installer jobs. Both validation functions must succeed before promotion; inputs must come from the authenticated release provider and the application's trusted release configuration. These functions do not fetch or verify release signatures, create artifacts, publish releases, or promote them.

Installer and command qualification (adea-release-step qualify) runs on a disposable runner: a GitHub-hosted Actions runner in the release-assets workflow, or a GitLab CI job in the tag pipeline for the release, whose executor creates a fresh container or VM per job and which sets FRAMEWORK_DISPOSABLE_RUNNER=true. Never set that variable on a shell executor. On GitLab the job needs a clean, full-history checkout of the tagged commit with origin/main fetched, a per-job absolute TMPDIR, and payloads downloaded outside the checkout; receipts name the tagged commit as source and workflow commit and CI_PIPELINE_ID as the run, attempt 1.

Package entry points

Import a subpath; the package has no root export. Entries marked solid also export TypeScript source under the solid condition, which a Vite consumer with vite-plugin-solid compiles itself. Entries marked source only export TypeScript source alone, and the rest resolve to dist. The package ships only the source those entries reach, plus the Electrobun patches in src/native; a test checks the file list against the exports.

Importing a module only declares things, so the package sets "sideEffects": false and a bundler drops every module whose exports go unused. In Cortana's web build, that takes 4.9 KB off the initial JavaScript and 24 KB off the whole graph. A test fails if a library module gains a top-level statement.

| Area | Subpaths (@adea-ai/app-framework/<subpath>) | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Application and shell | application, app-shell, app-utilities, media-query, poll, app-settings, app-help, app-about, update-surface (all solid), service-registry, application-menu, application-command-client | | Appearance | appearance-host, appearance-preferences, appearance-surface, custom-theme-library, window-surface (all solid) | | Desktop host | desktop-host, desktop-gateway, desktop-client, desktop-detection, desktop-stream, channel-handshake, channel-proof, loopback-policy, bounded-body, open-url-channel, client-asset-manifest, client-assets (source only), client-dev-proxy | | Native windows and OS | renderer-profile, secure-window, partitioned-window, window-options (source only), native-utilities, native-secret-store, app-bundle, sidecar, sidecar-services, desktop-build-hook, desktop-build, electrobun-types (ambient types only) | | Native installers | windows-extractor-build, installer-archive, window-surface-store | | Updates | desktop-updater, update-manager, update-inherited-launch-lease, packaged-launch-admission, packaged-update-startup, update-resume, channel-update-manager, update-channel-store, update-discovery, update-download, update-extraction, signed-release, release-feed, update-adapter (solid), release-version (solid), update-state (source only), update-helper.js (bundled helper) | | Release tooling | release-config, release-cut, release-steps, release-staging, release-artifact, release-assets-plan, release-descriptor-staging, release-publication, release-publish-command, release-promotion, retained-release-build, github-release-publisher, github-release-qualification, github-release-promotion, macos-dmg | | Installer qualification | installer-layout, installer-identity, installer-extraction, installed-payload, installer-observation, installer-qualification-command, installer-renderer-evidence | | Developer app | developer-app | | CI | toolchain-identity |

Commands (package bin entries):

| Command | Purpose | | --------------------------------- | --------------------------------------------------------------------------------------------------- | | create-adea-app | Generate an application from the starter template. | | adea-update-app-framework | Move an app's framework tarball, lockfile and workflow pins to a published release together. | | adea-cut-release | Cut a daily release from trusted main. | | adea-developer-app | Run the developer app from the checkout, or install its launcher (run / install). | | adea-plan-release-assets | Validate a dispatched release-assets run and resolve its source and version. | | adea-release-step | Run a per-platform step: select-retained, stage-build, inspect, qualify, qualify-upgrade. | | adea-sign-release | Sign one staged archive's release identity. | | adea-sign-release-descriptors | Sign channel descriptors for payloads every receipt qualified. | | adea-publish-release | Publish the current trusted release-assets attempt. | | adea-finalize-release | Publish a qualified Release Please draft as a prerelease. | | adea-verify-macos-signing | On a Mac, check every nested Mach-O in an app is signed alike and the seal verifies. | | adea-promote-release | Promote the newest qualified daily to stable after the soak. | | adea-desktop-release | In a GitLab release tag pipeline, build, sign and publish this runner's platform, then promote. | | adea-build-windows-installer | Build a stable Windows x64 installer whose extractor carries the shortcut patch. | | adea-cef-helper | Print the CEF helper cache key, or build the helper. | | adea-patch-windows-runtime | Apply the checksum-guarded Windows runtime correction. | | adea-patch-electrobun-shortcuts | Apply the shipped Windows shortcut patch to an Electrobun checkout. | | adea-toolchain-identity | Fail a cached task when the Node/Bun toolchain differs from its key. |

Shared application shell

ApplicationShell composes the published @adea-ai/ui rail, toolbar, contextual sidebar, resize handle, skip link and tooltip provider. The host supplies the app name, mark, destination IDs and icons, active destination, navigation callback and view content. Optional slots provide workspace and history controls, search, toolbar actions, rail footer and status content. The host controls sidebar state and persisted width; the shell restores focus after the narrow-screen sidebar closes and handles the advertised search chord. The sidebar's content, header and footer re-render only when the host passes a different function, so define them once rather than inline in the sidebar object: then resizing or toggling the sidebar keeps its content and state. The narrow-screen drawer loads the first time the window is narrow, so a wide window never loads its dialog code. Without a host drawer, the contextual sidebar uses its shared mobile sheet at 48rem and below. With a host drawer, narrowQuery controls when the shell replaces the desktop sidebar with it.

The sidebar's Ctrl/Meta+B shortcut yields to text inputs, textareas and editable content visible in the event path. An editor inside a closed shadow root can stop propagation of that chord to keep it from reaching the shell; the shell cannot inspect the closed root's focused element.

Consumers must import @adea-ai/ui/globals.css and configure Tailwind to scan the UI and framework package source. tests/consumer shows a buildable packed consumer. Run bun run test, bun run typecheck and bun run test:packed (the last requires Playwright Chromium, installed with bunx playwright install chromium). The packed test builds an isolated consumer and exercises keyboard navigation, resizing and narrow-screen focus; it does not establish the native Electrobun or release requirements.

createServiceRegistry registers application service handlers with explicit input parsing and per-call authorization. A registration can be retired without removing a later replacement; if it is retired while authorization is pending, the handler will not start. Retirement does not cancel work already started. A host can pass a synchronous channel and scope recheck to dispatch; the check runs immediately before the handler starts, after asynchronous authorization. Long-running services must perform their own checks at later mutation boundaries. A handler that throws ServiceError(code, message) returns { ok: false, code: 'service_error', error: { code, message } } so the caller can show the message; any other thrown value becomes a bare service_failed. The registry is an in-process boundary, not an authentication mechanism: only a transport that has independently verified the caller may supply its principal. Host code remains responsible for capability and resource authorization, bounded transport payloads, and safe result serialization.

ApplicationThemeProvider uses the shared theme provider with a required application-specific storage key. ApplicationUtilities, mounted in the shell footer, supplies the account menu and lazily loaded About, Appearance, and Updates dialogs. The app supplies identity, optional native link and clipboard adapters, and an updater and channel adapter when available. The default appearance panel applies changes through the shared provider. A host may supply its own appearance surface; Adea's existing preview, cancellation, imported theme library and V2 preference behavior are available through the appearance provider and editor described below.

app-utilities and the lean poll entry export createPoll({ intervalMs, run, visibleOnly, immediate, enabled, onError }), a polling loop owned by the current reactive scope. Ticks never overlap; the interval runs from one tick settling to the next starting. A hidden document holds no timer and runs at once when shown if a tick is due. enabled is a reactive switch, and disposal clears the timer and aborts the tick in flight through the AbortSignal passed to run. For "latest answer wins" actions use createLatestAction from @adea-ai/ui. createMediaQuery is also its own media-query entry. Code that needs only these primitives should import the lean entries, which carry no shell, menu or dialog code.

ApplicationSettings is the shared settings dialog: grouped section navigation that becomes a horizontal strip on narrow windows, beside the selected panel. Pass utilities.settings.sections (validated by defineSettingsSections); the framework adds its Appearance section first and opens the dialog from the account menu's Settings item, the platform settings chord (⌘, or Ctrl+,) and #settings/<section> deep links. Each app owns its sections' content and persistence. utilities.help supplies the shared Help Center with the app's links and shortcuts; the framework appends the chords it binds itself. The commands callback returns functions that open Settings, Appearance, About, Help and Updates so native menus and app-owned triggers reuse the same surfaces. Apps that already supply onSettings or onHelp keep their own surfaces.

utilities.accountMenu adjusts the account menu without replacing it: label (default Application settings), avatarSrc (a profile photo drawn on the trigger in place of the user glyph), busy for an in-flight sign-in or sign-out, onIntent (hover or focus, for prefetching), settingsShortcut and settingsKeyshortcuts for the Settings row, appearance: false to hide the Appearance item, and updates: 'always' to keep Updates visible and enabled on every runtime (without an updater it opens the dialog's desktop-only explanation). onUpdates replaces the shared updates dialog with an app-owned one. utilities.settings.appearance places the framework Appearance section ({ position: 'start' | 'end' | index, group, label }) or omits it with false, in which case openAppearance opens the standalone Appearance dialog. defaultSection names the section opened when none is requested. open, section, onOpenChange and onSectionChange let an app-owned store drive and observe the dialog; omit them for the default local state.

identity.platform is the label About shows. Shortcut hints use identity.shortcutPlatform ('mac' or 'other'); when it is omitted, a platform label naming an Apple OS means mac and any other label (desktop, web) defers to the browser's platform.

The shared surfaces are also exported standalone for apps that keep their own menu, each as its own module to load with lazy(): app-about (ApplicationAbout), app-help and update-surface (ApplicationUpdateSurface). The update surface accepts a channel as { read, persist } or as a service with { channel, setChannel }, optional channelLabels and channelDescriptions, and onUpdateState to mirror every updater snapshot into a pending-update badge without a second checker. update-adapter holds the dependency-free helpers for boot code: desktopUpdateAdapter bridges the framework's desktop_update_* services, mirrorUpdateState wraps an adapter, updateChannelStore normalizes either channel shape and browserUpdateAdapter describes a build without an installer. update-surface exports only the surface; import these helpers from update-adapter.

Modules that hold shared state (window-surface, custom-theme-library, appearance-preferences) are exported with the same solid source condition as the components that import them, so a Vite consumer loads one copy of each; a test enforces this for every solid export.

application-menu builds the native application, Edit, View, Window and Help menus for macOS and Windows (Electrobun has no Linux application menu; the same surfaces stay in the window's account menu). Pass the result to Electrobun's ApplicationMenu.setApplicationMenu and route application-menu-clicked events through createApplicationMenuHandler. Help links must be HTTPS and open in the system browser; app-owned sections deliver their actions to the app.

For hosts that need macOS native roles without framework actions, pass macOS: { about: 'native', help: false } and leave settings and updates unset. The resulting application, Edit, View and Window menus retain system key equivalents. A host can separately enable Settings and choose settingsAccelerator: false or an app-owned settingsAction under macOS; these settings options apply only when settings: true. Route an app-owned action through the handler's action callback. To disable the native menu entirely, the host should skip installation. Help links cannot be supplied when the macOS Help menu is disabled. These presentation options do not change Windows menus. Native menu callbacks may require the app adapter to defer UI work until after the callback returns. createApplicationCommandBroadcaster registers the shell.commands desktop stream, and connectApplicationCommands in the window opens About, Settings, Help and Updates through ApplicationUtilities commands. Commands carry only a name over the authenticated channel. The generated app wires both sides. The command connection does not renew credentials or retry after a disconnect. When the app's authorization policy permits a new channel, its owner can explicitly reconnect and then attach the menu stream:

const disconnect = await connectApplicationCommands(client, commands)
// Later, after the app decides its current authorization permits reconnecting:
try {
  const session = await client.reconnectForStreams()
  await disconnect.resubscribe(session)
} catch {
  // The app handles a failed reconnect or attachment according to its own policy.
}
// On teardown:
disconnect()

The token works only with its originating client and current unexpired channel; resubscription never obtains a bootstrap. Concurrent resubscription attempts are rejected, and disposal closes a late result. The owner handles errors and chooses whether to retry. Messages delivered before an initial or replacement stream is admitted are dropped, not queued or replayed. An initial stream setup still uses normal channel acquisition. Server revocation is not locally observable until a request or transport event reveals it. The generated app and ordinary reconnect() do not use this opt-in API and do not automatically recover from expiry or a transient close.

Application definition and loopback policy

defineApplication validates an app's identity, storage key, unique view IDs, initial view, labels and render functions. Application mounts those views in the shared shell and utilities, with local navigation by default or a supplied router. Optional theme-provider configuration, footer and toolbar slots let a host preserve its own preference store and integrations. The packed-consumer fixture demonstrates this API. create-adea-app generates a desktop-capable application, and the framework provides the Electrobun host and release tools; each consumer still configures its own identity, services, credentials, and release policy.

createLoopbackPolicy and the request-metadata predicates screen foreign Host, Origin and browser fetch-site values before privileged requests reach a native transport. These headers can be forged by a local process and are not credentials: they must not be used alone to disclose bootstrap secrets or invoke services. The Electrobun host authenticates its native window channel before dispatching privileged services; service authorization and resource policy remain application-owned.

Appearance

appearance-preferences exposes Adea's V2 appearance codec, persistence, and first-paint script. The codec stores the appearance document and quarantines unreadable or newer records before replacing them. Pass createAppearancePersistence() as the shared theme provider's persistence option and put appearanceThemeScript() in the document head before rendering. The appearance provider and editor below include imported-theme management and reversible preview settings. See NOTICE for donor attribution.

custom-theme-library retains imported theme records and their existing storage format, including the separate recovery key and the original color-contrast validation. The appearance host combines the published built-in catalogue with the imported variants. The appearance editor handles theme import and editing. Its persisted import and removal operations hold a read/write transaction in a shared origin-wide IndexedDB database while they update the readable version-1 library record. They also use Web Locks when available. The IndexedDB transaction coordinates separate WebViews even when their Web Lock managers are not shared; durable operations fail closed when IndexedDB is unavailable. These locks cannot coordinate older builds that write the storage key through the removed synchronous setCustomThemes, removeCustomTheme or importCustomTheme APIs. Use the asynchronous mutation APIs, mutateCustomThemeLibrary and removeCustomThemeAtomically. Older already-loaded builds can still write the version-1 key without the lock and are not coordinated by this build.

An unreadable library never blocks these operations. Its exact bytes are captured in CUSTOM_THEME_LIBRARY_RECOVERY_KEY (a different earlier capture moves to the one CUSTOM_THEME_LIBRARY_PREVIOUS_RECOVERY_KEY slot), the readable themes are kept, and the committed result carries recovered: 'corrupt_json' | 'unsupported_record'; show CUSTOM_THEME_LIBRARY_RECOVERED for it. Only storage refusing that capture fails the operation, with recovery_unavailable.

appearance-host supplies the V2 appearance provider and context, including imported variants, draft previews, native translucency capability, and a first-paint script component. Supply Application's themeProvider to its ThemeProvider when preserving that contract; the default provider remains available for apps using their own storage key. The appearance editor can be provided to the utilities surface.

appearance-surface exports the shared appearance editor and its popover, including reversible previews, theme-file import, and font and surface settings. Theme-file imports accept JSON files up to 1 MiB and reject larger files before reading them. Use it with the V2 appearance provider; pass AppearancePanel as the utilities appearance slot. Desktop hosts can register a native surface mirror through window-surface. The host remains responsible for implementing the native window operation.

Desktop bridge and host

channel-proof verifies the existing signed invoke proof over a channel, credential, timestamp, nonce and exact body. It checks the host's current channel lookup on every call and rejects replays and forged proofs. This is not a channel handshake or authorization: the native host must securely deliver credentials, bound request bodies before buffering, revoke channels, and recheck authorization and channel lifetime after asynchronous work. The legacy proof does not bind an HTTP method or path: routes sharing that proof context must share one replay verifier and enforce their own request routing. The host must preserve the exact UTF-8 body bytes used to produce the proof. A nonce is held only for the 30 s timestamp window in which it could be replayed, up to maxNonces (default 16,384, about 540 requests a second). A full cache refuses with capacity, which the gateway answers as 429 so the caller keeps its channel.

channel-handshake creates expiring, single-use bootstrap capabilities and channel credentials and supports revocation. The host must deliver bootstrap secrets through the trusted native window, not a loopback HTTP response, and revoke channels when that window is replaced or closed. This in-process API does not implement the native window, transport, streaming, or authorization.

desktop-gateway connects the channel handshake, signed invoke proof, and service registry using bounded UTF-8 JSON requests. It screens loopback origin metadata, but authenticates with the channel credentials rather than headers. The gateway bounds concurrent requests and body-read time. Invoke bodies are limited to 256 KiB unless a service registers a larger maxBodyBytes (at most 16 MiB); that limit applies to that service alone. Native bootstrap delivery, streaming, window lifecycle, and application-specific authorization remain host work. Service-work deadlines are opt-in with dispatchTimeoutMs; when omitted, service dispatch has no deadline. When configured, an expired deadline returns HTTP 504 and aborts the AbortSignal passed to service authorize and run callbacks. Set it on createDesktopGateway or startDesktopHost. A caller abort also aborts that signal; since the caller may already be disconnected, the host must not rely on delivering a response for that cancellation. Abort is cooperative: JavaScript cannot stop a synchronous or signal-ignoring callback, and a timeout or disconnect does not prove its side effects stopped. The gateway keeps the concurrency slot until the dispatch settles, and retries after an ambiguous timeout can duplicate effects.

renderer-profile selects the desktop renderer consistently for both the Electrobun build and window. createRendererProfile() selects the operating system webview and sets bundleCEF: false on macOS, Windows and Linux; pass 'cef' to opt into bundling Chromium. Merge the per-platform build fragments with the app's signing and packaging options, and pass the profile's renderer to createWindowOptions. Native-renderer dependencies and installed artifact contents still need platform-specific packaging verification.

The internal window-bootstrap module is an experimental native-window proof and preload. Its secret must never be served as an unauthenticated HTTP response or logged. It requires a native renderer that protects the preload source from untrusted frames and prevents untrusted main-frame navigation before script injection. Packaged native probes exercise these boundaries on macOS, Windows and Linux; installed-app and product-specific qualification remain separate requirements.

desktop-host and desktop-client are the in-progress native host and signed service client. The host creates a blank window with Electrobun's bridge sandbox enabled, installs its navigation rules, and only then loads the loopback client. The client obtains a window-bound bootstrap, signs service calls and supports explicit reconnect; it does not replay a failed call. Disposing the client or explicitly reconnecting aborts in-flight invoke requests; server work observes cooperative cancellation, so side effects may already have occurred when the call rejects. Set portFile to a path in an existing, app-owned data directory to preserve the loopback origin and its browser preferences across restarts. First publication requires hard-link support in that directory; unsupported filesystems fail closed. A malformed record or occupied port also fails closed; the host never silently selects a new origin. App-owned routes serve same-origin requests after the host refuses any non-loopback Origin; a route that declares websocket handlers may accept a socket by calling context.upgrade(data) from handle. Client documents get frame-src 'none' unless frameSources names exact https or loopback origins (at most 8) the app may embed. Electrobun 2.0.5 configures CEF with Chromium's operating-system sandbox disabled; the bridge sandbox and web-security flags do not provide that OS process isolation. A packaged native probe exercises both renderer profiles with bun run build && bun scripts/test-native-window.ts and bun scripts/test-native-window.ts --cef. Hosted probes have exercised both renderers on all three platforms for 2.0.1, including persistence across restarts. Electrobun 2.0.5 still requires hosted platform qualification. Streaming, additional native services, installed-app qualification, and Adea compatibility remain open.

Electrobun's BrowserView accepts a browser-data partition, but its BrowserWindow (2.0.1 through 2.0.5) does not forward one to the view it creates. constructPartitionedWindow() from partitioned-window constructs a window on stock Electrobun with its view in the requested partition, for example persist:<profile> for a separate persistent profile:

import { BrowserView, BrowserWindow } from 'electrobun/bun'
import { constructPartitionedWindow } from '@adea-ai/app-framework/partitioned-window'

const window = constructPartitionedWindow({
  BrowserView,
  partition: `persist:${profileId}`,
  construct: () => new BrowserWindow({ title: 'Example', url: null }),
})

It applies the partition only during that synchronous construction and fails closed, closing the window, unless the window's single view reports the requested partition. Without a partition it is a plain constructor call, and it can wrap the construct callback given to desktop-host.

Releases

adea-desktop-release daily|stable is the provider-neutral desktop release driver for GitLab release tag pipelines (and any checkout of a tagged main commit). It uses the local release mode, so provenance comes from git (the tag commit on origin/main, the version file at that commit), not from a CI provider. A daily cut must equal CI_COMMIT_TAG. It builds the runner's own platform, signs the descriptors with DESKTOP_UPDATE_SIGNING_KEY_B64 (decoded only into the signing process's environment), uploads the staged tree to an S3-compatible bucket with the aws CLI in plan order (immutable files are never overwritten, the channel pointers go last), verifies the feed and links every file on the GitLab release with the job token. stable promotes the newest qualified daily after the soak. Apps add their own files through the optional release:preflight and release:extend-plan package scripts. An app that releases only this way can leave releaseWorkflows out of release-config.json; the GitHub-hosted release commands then refuse to run.

Generating an app

The create-adea-app command generates a new application from an identity, framework package specifier and renderer choice. The starter provides the shared shell, appearance, one view and one desktop service. The generated GitLab validation job accepts optional comma-separated --gitlab-runner-tags; without them it requires an untagged Docker runner. Its .gitlab/desktop-release.yml publishes desktop releases from release tag pipelines with adea-desktop-release (below) on the runner named by --gitlab-release-runner-tags, and stays off until the project sets DESKTOP_RELEASE_ENABLED=true. The framework package specifier must refer to a distributable package available to the new project. Its GitHub Actions release workflows call this framework release's reusable workflows on the shared schedule (pinned to the release tag; run bunx adea-update-app-framework to pin the commit) and stay off until the repository sets DESKTOP_RELEASES_ENABLED=true with a release signing key. Native application services and product-specific authorization must still be added before distribution. Generation writes into a private staging directory next to the destination and publishes it with one no-replace rename, so a failed or concurrent run never leaves a partial destination and a retry can proceed. It refuses a destination parent that another user owns, that other users can write to, or that is group-writable by a group not provably private to the user (sticky parents are accepted). On Linux a group counts as private when /etc/passwd and /etc/group show no other account in it; elsewhere a group-writable parent is refused. Cleanup removes the staging directory only while it is still the one the run created. A run killed mid-generation can leave a .framework-app-* directory beside the destination; it never blocks a retry and is safe to delete. On Windows the parent check is skipped: its ACLs are not visible to Node, so generation assumes the destination parent (normally under the user profile) does not let other accounts rename or delete its entries. Run bun run test:generated for an isolated packed-consumer web build and browser check; bun scripts/test-generated.ts --desktop additionally builds the native bundle for the current platform.

Signed releases and artifacts

signed-release provides a separate version 2 Ed25519 descriptor that binds application, repository, channel, version, source and workflow commits, run, platform, architecture, asset URL, size and digest. The verifier requires a matching application-owned trust policy and key ID before checking artifact bytes, including through a bounded streaming hash. Daily artifacts correspond to the existing opt-in pre-release channel; stable promotion requires a newly signed stable descriptor. This API does not publish, discover, install or roll back releases. Callers must set download deadlines, enforce version policy and protect signing keys.

release-artifact hashes a staged archive and signs its complete release identity. The adea-sign-release command accepts an identity JSON file and archive path, reads ADEA_RELEASE_SIGNING_KEY as a PKCS#8 PEM private key, and writes the signed descriptor to standard output. Keep the staged archive immutable between hashing, qualification and upload; the signer detects size and metadata changes while reading but cannot prevent later replacement. Provide the key through the CI secret store and restrict signing to trusted release jobs. The command does not publish the artifact.

Electrobun and CEF hardening

The CEF profile suppresses Electrobun's insecure web-security and remote-debug defaults. The pinned Electrobun 2.0.5 Windows system-webview implementation hardcodes --disable-web-security; its chromiumFlags configuration does not control WebView2. The desktop-build-hook applies the checksum-guarded runtime correction before packaging; the packaged Windows system-webview probe exercises cross-origin isolation, navigation, service calls and restart persistence.

Electrobun 2.0.5's CEF renderer helper installs __electrobunEventBridge, __electrobunHostBridge, __electrobunBunBridge and __electrobunInternalBridge in every frame, and their messages reach the browser process as if the app's main frame sent them, so a cross-origin iframe could drive Electrobun's internal RPC. electrobun-cef-main-frame-bridges.patch installs them in the main frame only. The desktop-build-hook replaces every bundled CEF helper with that build before Electrobun signs the bundle, so the helper is signed with the app; bundles without CEF are untouched. It accepts only the pinned stock helper bytes and fails closed on anything else, and on any CEF target other than macOS arm64, Linux x64 or Windows x64. The patched helper is built once per pinned source, patch and CEF version: the hook fetches the three helper sources at the pinned commit, applies the digest-pinned patch, downloads the digest-pinned CEF minimal distribution, and compiles the helper as Electrobun's own build does (CMake and Xcode on macOS, CMake and g++ on Linux, CMake and Visual Studio C++ on Windows). The result is cached under ADEA_CEF_HELPER_CACHE when set, otherwise the user cache directory; adea-cef-helper key prints the cache key for CI and adea-cef-helper build fills the cache ahead of a build. Each completed entry records its key, size and SHA-256, which are checked before reuse and after a concurrent build. A missing or corrupt record or helper stops the build: remove that key's directory from the cache root and retry to rebuild it. The record detects accidental corruption; it does not authenticate a cache that an attacker can modify. The packaged native probe loads a cross-site frame in an unsandboxed CEF window and requires all four bridges in the main frame and none in the subframe.

Helper hashing and replacement use fixed-size buffers. Keep the cache and build tree private and stable while the hook runs: path checks cannot make multiple file replacements atomic. If a replacement fails, the build stops before signing; rebuild the output tree before retrying because earlier helpers may already have been replaced.

Publication

release-publication validates installer receipts and signed discovery descriptors against the exact staged payloads before publication. It refuses asset replacement, rechecks source and workflow provenance, uploads the qualification receipt before discovery assets, and verifies provider-reported digests. github-release-publisher provides the GitHub adapter using gh and a trusted release-job token. The caller must protect the staged files from concurrent changes, configure trusted keys and run the installer and completed workflow qualification checks before promotion. This does not create releases, configure schedules, install artifacts or promote stable releases.

Windows (experimental)

The experimental Windows SDK lane checks out Electrobun 2.0.5 at its exact source commit, verifies the native wrapper source digest, removes the upstream WebView2 arguments that disable browser security, and builds a replacement from source. Its packaged probe confirms service access, cross-origin isolation, window lifecycle and navigation. The checksum-guarded pre-packaging hook applies the equivalent correction to the pinned distributed runtime.

For the pinned unsigned Electrobun 2.0.5 Windows x64 wrapper, the experimental adea-patch-windows-runtime command provides a deterministic alternative to rebuilding the SDK. It verifies the exact upstream DLL hash, PE architecture, unsigned status, argument bytes and patched output hash, then writes a new file without overwriting the original. Apply it before any application code signing. The packaged Windows probe exercises the hook before it is used by generated apps.

Electrobun 2.0.5's Windows installer creates its Desktop and Start Menu shortcuts through PowerShell and waits without a bound. The experimental adea-patch-electrobun-shortcuts <checkout> command applies the shipped electrobun-windows-shortcut-com.patch to a checkout of the exact 2.0.5 source commit. It verifies the patch, input and output digests and replaces that step with Windows Shell Link COM in an isolated extractor helper process. Each shortcut waits at most 30 seconds; on timeout only the helper is terminated and the installation fails. COM and file-write failures also fail it, and neither shortcut is skipped. The Windows SDK lane applies it, builds the extractor and runs its native shortcut tests. Apps that ship the patched extractor build it from that source and point HUTCH_ELECTROBUN_DEVKIT_ROOT at a copy of the pinned devkit that contains it.

Promotion

release-promotion implements the daily-to-stable selection policy with a configurable soak (96 hours by default), a hold switch and qualification of every candidate. It delegates release listing, exact-run qualification and idempotent stable updates to a trusted provider. The GitHub provider verifies the immutable receipt, installer jobs and exact successful workflow attempt, then rechecks qualification before updating the stable release. It does not schedule promotion. Stable and daily signed discovery assets must have distinct immutable names so promotion never replaces daily bytes.

adea-promote-release runs that policy in a main-branch GitHub Actions scheduled or manually dispatched workflow. Its configuration names the required macOS ARM64, Windows x64 and Linux x64 installer assets, separate daily and stable discovery assets, and the soak duration. It rechecks the exact qualified attempt immediately before the stable update. The caller must grant a narrowly scoped GH_TOKEN and provide the configuration and release-assets workflow; no schedule is installed by this command.

For example, a promotion configuration can name the app's actual assets:

{
  "appName": "Example",
  "soakHours": 96,
  "platforms": {
    "macos-arm64": ["Example-{tag}-macos-arm64.dmg"],
    "windows-x64": ["Example-{tag}-windows-x64-Setup.zip"],
    "linux-x64": ["Example-{tag}-linux-x64-Setup.tar.gz"]
  },
  "releaseAssets": ["daily.json", "stable.json"],
  "dailyDiscoveryAssets": ["daily.json"],
  "stableDiscoveryAssets": ["stable.json"]
}

Each discovery file must be a separately signed descriptor, and the release qualification must include every named asset. Use STABLE_PROMOTION_HELD=true to hold promotion. A caller workflow must supply GH_TOKEN and invoke adea-promote-release path/to/config.json from trusted main.

installer-layout checks portable application names, hosted-runner context, expected installer and payload paths, packaged renderer selection and CEF security flags. It does not extract or execute an installer; callers must validate archive link targets and entry types, test the installed application, and collect the native renderer evidence before qualifying a release.

Cutting a release

adea-cut-release daily path/to/config.json checks the Release Please daily of the source version and repairs or dispatches its build from a trusted main GitHub Actions workflow. The configuration also supplies appName and releaseWorkflows, the caller workflow files whose runs carry release provenance:

"releaseWorkflows": {
  "control": ".github/workflows/release.yml",
  "assets": ".github/workflows/release-assets.yml"
}

Both are required, must differ and must name a .yml or .yaml file directly under .github/workflows/. Cuts run only from the control workflow; the assets workflow is dispatched for each tag, and planning, retained-build reuse, publication, qualification, promotion and finalization accept only its runs. The caller must serialize release cuts and give the assets workflow a run name of framework-release-assets:<tag>; uncertain qualification or build state blocks dispatch. No release is cut outside the trusted workflow. Release Please owns the version. versionSource names the manifest it bumps, for example { "kind": "source-manifest", "path": "apps/desktop/package.json" }, and every release carries that version:

  • A daily (and later stable) release is the Release Please release v<version>. The framework resolves the tag's exact commit and requires the manifest at that commit to match the tag before building, publishing or qualifying it.
  • There are no dev releases. Development runs the developer app from the checkout (see "Developer app"). Release tooling accepts only vX.Y.Z tags. Existing -dev.N versions still parse and sort below the release they lead to, so an old dev install can still read the feed. dev is no longer an update channel: a saved dev channel file and a dev argument to parseUpdateChannel (sent by older channel pickers) read as pre-release, and nothing writes dev again. Old ledger entries for dev builds are read and ignored.

Calendar-tagged releases (v2026.10.31-dev.1525) from before Release Please sort above every version and are never chosen as an upgrade source; their installations reinstall once. An unchanged version reuses the same daily tag, which is why the daily cadence can be any interval. Promotion orders qualified dailies by semver and will not move stable below an already published stable version. Older stable releases without qualification evidence serve only as a downgrade fence. Serialize release cuts and promotions; this check cannot atomically fence a concurrent external change to the release list. Channel descriptors and payloads must still pass signature and digest checks.

Release Please drafts are staged privately; a separate finalize workflow rechecks the exact successful installer attempt before publishing a prerelease. A run started with the workflow token never triggers workflow_run, so the assets workflow starts it: pass finalize-workflow: <your finalize file> to desktop-release-assets.yml and grant that caller job actions: write. A daily run then dispatches the finalize workflow with its own run ID and attempt, and finalization waits for that run to complete before qualifying it. If that finalization job fails, dispatch the finalize workflow from main with the tag, successful release-assets run ID and attempt number. Its own file name is not configured: finalization trusts only the qualified assets run. The retry rechecks the same qualification before changing release visibility.

Developer app

Development needs no release build and no dev channel: each app has one persistent developer app that runs straight from the developer's checkout. With GitButler the checkout is every applied branch merged together, so the window always shows the combined state of all parallel work, and agents can drive it to test. Public apps publish only daily and stable.

An app describes it in developer-app.json next to its Electrobun project (paths resolve from the file's folder):

{
  "name": "Example",
  "identifier": "dev.example.app",
  "shellDirectory": ".",
  "watch": ["src"],
  "ui": { "directory": "../web", "command": ["bun", "run", "dev"], "port": 5179, "warm": ["/"] },
  "shellEnv": { "EXAMPLE_SHELL_PORT": "4799" },
  "prepare": [["bun", "scripts/stage.ts"]],
  "icon": "resources/developer-icon.png"
}
  • adea-developer-app run runs any prepare commands, then starts the UI dev server and electrobun dev together, with ADEA_DEVELOPER_APP=1 and ADEA_CLIENT_DEV_URL set, so the shell build overlaps the dev server's startup and first compile (warm paths are fetched as soon as it answers). Until it answers, the window shows a page that reloads itself every second. Shell source edits (watch) restart the shell.
  • While it runs it keeps the checkout a live dev environment (followWorkspace): every few minutes but pull brings in the latest main, keeping the in-progress branches applied. A branch that would conflict is unapplied first (GitButler keeps it to apply again once rebased) and announced in a notification. A lockfile change reinstalls and restarts the app (the runner exits with 75 and the launcher starts it again).
  • adea-developer-app install adds " (Dev).app" to /Applications (ADEA_DEVELOPER_APP_DIR overrides): a launcher that runs run from the checkout in a login shell and logs to ~/Library/Logs/<Name> (Dev).log. Pass -- <command> to launch a different command from the checkout root instead.
  • In electrobun.config.ts, use developerAppIdentity(app) when isDeveloperApp(): it names the app " (Dev)" with identifier <identifier>.live, builds into build.noindex (out of Spotlight) and uses the staged icon. The framework build hook (desktop-build-hook) renames the macOS bundle to match.
  • A shell on desktop-host passes clientDevOrigin: process.env.ADEA_CLIENT_DEV_URL; the host then proxies client requests to the dev server instead of serving the built client. A shell with its own server uses client-dev-proxy directly. Both refuse anything but a bare loopback http origin.
  • runDeveloperApp and installDeveloperAppLauncher (developer-app) are the same steps as a library, for an app whose run needs more than the config file says.

Release feed and local release mode

Apps publish to and update from an HTTPS release feed, named in the release configuration as "releaseFeed": { "base": "https://adea.dev/releases/", "app": "adea" }: an https origin and path prefix ending in / (no credentials, port, query or fragment) and the app's key prefix. Keys are relative to base:

  • <app>/<tag>/<asset>: immutable payloads and signed channel descriptors, whose asset URL is exactly <base><app>/<tag>/<asset>;
  • <app>/<tag>/release.json: { tag, channel, publishedAt, assets: [{ name, size, sha256 }] };
  • <app>/index.json: the ledger { schema: 1, app, releases: [{ tag, kind, version, sourceSha, publishedAt }] }, newest first and at most 500 entries; stable entries add promotedAt;
  • <app>/channels/<daily|stable>.json: a copy of the newest release.json on that channel (feeds from before dev releases were removed may also hold dev.json).

The updater reads the channel pointer, downloads the listed descriptor from the same release, checks its bytes against release.json, verifies its signature and identity, and then the payload's size and digest. Requests carry no credentials and follow at most five redirects that stay under <base><app>/.

Without GitHub Actions the release CLIs run with --local from a clean checkout of a commit on the fetched origin/main: version state comes from the feed's ledger, read anonymously, and the commit itself stands in for the workflow run. Nothing is uploaded; publishing steps write a tree mirroring the feed's keys and upload-plan.json, ordered assets, release.json, index.json, channel pointers. When the ledger is missing or empty, bootstrap checks all three channel pointers and refuses to proceed if any exists or cannot be read. All three returning 404 does not prove that the feed has no orphaned artifacts or concurrent writers; a nonempty ledger can also be stale. Promotion rechecks the ledger and selected release inventory after qualification and refuses to stage when a re-read differs or the ledger is unavailable. These point-in-time checks are not transactions. Serialize feed writers from the first read through the final upload and restage if the feed changes; transport cancellation is not a hard deadline. The publisher also refuses to stage when the selected release manifest and its ledger entry are unmatched or disagree on channel or publication time. Interrupted publication or promotion, and older releases evicted from the bounded ledger, require explicit reconciliation; automatic repair is not implemented. These plans are snapshots, not conditional writes or transactions. Serialize all writers for an app's feed from the initial read through the last upload, including promotion and platform additions. If the feed changes before a plan is applied, discard that plan and stage a fresh one; uploading stale plans can replace a newer release inventory or channel pointer.

  • adea-cut-release --local daily <config> <sha> prints the tag and dispatched when this machine's platform still has to be built.
  • adea-release-step stage-build <platform> <dir> (with RELEASE_TAG) stages the build; installer qualification needs a hosted runner and is skipped.
  • adea-sign-release-descriptors --local <dir> <config> with RELEASE_TAG, SOURCE_SHA, RELEASE_RUN_ID and the signing key signs this platform's descriptors.
  • adea-publish-release --local <dir> <config> <out> merges this platform into the feed's release and stages the upload.
  • adea-promote-release --local <config> <out> promotes a qualified daily after the soak and stages release.json, index.json and the stable pointer. A daily qualifies when it publishes every platform in stablePlatforms (release-config.json; macOS only by default, add windows-x64 and linux-x64 to require them). A stable promoted without a supported platform records it as missingPlatforms in release.json. A daily short of a required platform is unqualified with reasons.
  • adea-finalize-release --local <config> <tag> verifies a published release from the feed and lists its verified and missing platforms.

Local finalization and promotion stream each required update archive and compare its bytes with the signed descriptor, once per distinct payload. This can transfer large archives. Payloads over the desktop updater's 1 GiB limit are rejected; the per-payload request uses a ten-minute abort signal and depends on transport cooperation. A fetch or body read that never settles can still stall verification. This point-in-time check does not fence later feed changes.

Updating the framework pin

An application references the framework in three places: the exact npm version in each package.json, the matching bun.lock entry, and the commit SHA on each reusable-workflow uses:. Move them together from the repository root:

bunx adea-update-app-framework          # the latest npm version
bunx adea-update-app-framework 0.24.0   # a specific version

The command takes only a version npm serves from registry.npmjs.org whose tarball matches its sha512 integrity, contains the version it claims and names its source commit in dist/framework-source.json. Every package.json must already pin an exact version. It rewrites those versions, pins every framework workflow to the source commit (@<sha> # v<version>), regenerates bun.lock with bun install (keeping comments such as release-please's version marker), checks the lock names exactly that version and integrity, and then requires bun install --frozen-lockfile to pass without changing the verified lock. Only direct entries in the four top-level dependency sections are rewritten; unrelated properties retain their original bytes. Ambiguous duplicate dependency keys and manifests nested more than 256 levels are rejected before any writes. The command replaces regular files using same-directory temporary files and preserves their permission bits. Replacement changes the file identity and does not preserve ownership, ACLs, extended attributes, or hard links; it refuses symlinked files. On failure, rollback preserves unexpected contents and reports affected paths instead of overwriting them. A lock in the Git worktree prevents two copies of this command from updating it simultaneously. Other editors and installs do not honor that lock, and the checks and writes are not atomic with respect to them, so stop those before running it. If a process is interrupted and leaves the lock behind, verify no updater is still running before removing the empty directory printed by git rev-parse --git-path adea-framework-update.lock. Keep the framework out of dependency bots so they cannot move one of the three on its own.

Task cache toolchain identity

toolchain-identity keys an app's cached vp tasks on the Node and Bun binaries and the platform. vite.config.ts writes expectedId() into each cached command, and an uncached first task runs node node_modules/@adea-ai/app-framework/dist/cli/toolchain-identity-cli.js --expect <id> (the adea-toolchain-identity bin) with the PATH the tasks get, failing the invocation before any cache read when the toolchain differs. The id carries versions, byte hashes, platform and libc, never paths, so the same toolchain at another path keeps its cache entries. runtimeExecutable resolves the binary a launcher really runs.

Reusable release workflows

Applications can call the framework's workflow_call workflows instead of copying the release jobs. Name the caller files in releaseWorkflows, keep the triggers and run name the CLIs verify, and pin the framework ref to a full commit SHA:

# .github/workflows/release-assets.yml (releaseWorkflows.assets)
name: Desktop release assets
run-name: framework-release-assets:${{ inputs.tag }}
on:
  workflow_dispatch:
    inputs:
      tag: { required: true, type: string }
permissions: {}
jobs:
  assets:
    uses: adea-ai/app-framework/.github/workflows/desktop-release-assets.yml@<sha>
    permissions: { contents: write, actions: read }
    with:
      tag: ${{ inputs.tag }}
      app-directory: apps/desktop
      platforms: '["macos-arm64","windows-x64","linux-x64"]'
      renderer: native
    secrets:
      ADEA_RELEASE_SIGNING_KEY: ${{ secrets.ADEA_RELEASE_SIGNING_KEY }}

desktop-release-assets.yml plans the tag, builds or reuses each platform payload, executes and qualifies the installer on its native runner, then signs the channel descriptors and publishes the tested bytes. It takes tag, an optional expected channel (dev or daily), app-directory, release-config, platforms, renderer (native or cef, exported as ADEA_APP_RENDERER for the app's qualification script), install-command, bun-version and release-signing-key-id. Apps that compile native sidecars set node-version, a prepare-command that installs their toolchain (for example rustup toolchain install) and a longer build-timeout-minutes; these only run when the build job builds a fresh payload rather than reusing a retained one.

# .github/workflows/release.yml (releaseWorkflows.control)
name: Desktop release
on:
  push: { branches: [main] }
  schedule: [{ cron: '23 12 * * *' }] # daily cadence; '23 */4 * * *' runs every 4 hours
  workflow_dispatch:
    inputs:
      operation: { type: choice, options: [daily, stable], required: true }
permissions: {}
concurrency:
  group: desktop-release-control-${{ github.repository }}
  cancel-in-progress: false
jobs:
  release:
    uses: adea-ai/app-framework/.github/workflows/desktop-release-control.yml@<sha>
    permissions: { contents: write, actions: write }
    with:
      app-directory: apps/desktop

desktop-release-control.yml owns the release schedule every framework app shares, so callers pass only app-directory (and release-config, install-command or bun-version when they differ from the defaults). Each scheduled run builds the newest Release Please version as a daily (doing nothing new when it is already built) and then promotes the newest qualified daily once soakHours (96 by default) have passed since the last stable, so stable moves about every four days. The caller's cron is the daily cadence: nothing assumes one run per day, so it can run every few hours. A manual dispatch runs one operation: daily or stable. CI_BILLING_PAUSED=true skips the push and schedule cuts; STABLE_PROMOTION_HELD=true holds promotion. To replace a bad stable without the soak, set the protected variable STABLE_SOAK_BYPASS_TAG=<tag> to one pending daily (newer than stable): the next promotion promotes exactly that tag if it qualifies, refuses a tag that is not a pending daily, and still yields to a hold. Clear it after the release. Keep the caller's push, schedule and workflow_dispatch triggers; only the cron expression is the app's choice. Generated apps include a Release Please workflow and config. desktop-release-finalize.yml runs release:finalize from the caller's finalize workflow, which the assets run dispatches (see above). The app's package.json must define the same build:release and release:* scripts the generated template provides.

Build hook a