@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
- Update state and release versions
- Package entry points
- Shared application shell
- Desktop bridge and host
- Releases
- Publishing the framework
- Native modules
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.Ztags. Existing-dev.Nversions still parse and sort below the release they lead to, so an old dev install can still read the feed.devis no longer an update channel: a saveddevchannel file and adevargument toparseUpdateChannel(sent by older channel pickers) read as pre-release, and nothing writesdevagain. 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 runruns anypreparecommands, then starts the UI dev server andelectrobun devtogether, withADEA_DEVELOPER_APP=1andADEA_CLIENT_DEV_URLset, so the shell build overlaps the dev server's startup and first compile (warmpaths 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 minutesbut pullbrings 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 installadds " (Dev).app" to/Applications(ADEA_DEVELOPER_APP_DIRoverrides): a launcher that runsrunfrom 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, usedeveloperAppIdentity(app)whenisDeveloperApp(): it names the app " (Dev)" with identifier<identifier>.live, builds intobuild.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-hostpassesclientDevOrigin: 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 usesclient-dev-proxydirectly. Both refuse anything but a bare loopback http origin. runDeveloperAppandinstallDeveloperAppLauncher(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 addpromotedAt;<app>/channels/<daily|stable>.json: a copy of the newest release.json on that channel (feeds from before dev releases were removed may also holddev.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 anddispatchedwhen this machine's platform still has to be built.adea-release-step stage-build <platform> <dir>(withRELEASE_TAG) stages the build; installer qualification needs a hosted runner and is skipped.adea-sign-release-descriptors --local <dir> <config>withRELEASE_TAG,SOURCE_SHA,RELEASE_RUN_IDand 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 instablePlatforms(release-config.json; macOS only by default, addwindows-x64andlinux-x64to require them). A stable promoted without a supported platform records it asmissingPlatformsin release.json. A daily short of a required platform isunqualifiedwithreasons.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 versionThe 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/desktopdesktop-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.
