Apps
Shared application launchers and verified portable app hosting for Ziran and Kryon applications.
apps/launcher exports AppLauncherScreen: search with a clear action,
list/grid controls, favorite grouping and scrolling. The caller retains an
AppLauncherState, supplies titles and favorite flags, and implements the
AppLauncherCards callback for the filtered catalog indices. The result
includes layout bounds for native drag/drop and guide overlays. Hosts persist
view preferences and own their account, routing, storage and installation
effects.
The callback mounts the portable screen in ui/apps.zi through
apps/controller. It provides cards, working action menus, Properties,
update/rollback confirmations and all UI translations. Catalog actions are an
explicit capability list: a host only offers actions it can handle. Every
openable app also has an Open command in its menu.
Hosts customize the same cards through the catalog's presentation object.
Set hide_sizes: true for a simple launcher that shows app names and icons
without package sizes, in either list or grid mode. The native host exposes
the same option as AppPresentation.hide_sizes. The default keeps sizes
visible for apps not yet on the device. Installed apps never show a download
size; download progress remains visible in either presentation.
AppPresentation.cover_logo_width caps carousel logos in logical pixels;
cover_logo_top positions them below a host toolbar. Zero keeps the standard
carousel layout. The controller accepts the same presentation fields.
AppPresentation.cover_grid selects a console carousel with one centred cover,
neighboring artwork at both sides, small cover markers, and keyboard, swipe and
wheel selection. Both orientations use the same carousel on a drawn scenic
pattern, never a game's artwork behind its cover. Landscape screens
use landscape covers; portrait screens use portrait covers. Names remain in
accessibility and the full-art launch page, with no visible home title or captions.
Clicking a neighbouring cover selects it; activating the selected cover opens it.
Enter/Space opens the selected game.
image_class applies the host's standard Image styles, including rounded
corners. Cover-grid activation starts missing downloads immediately on the cover, with a
progress bar while the shelf stays available. Installation finishes in the
background; another activation opens the installed game through its title.
The shared controller owns scrolling, menus and installation;
hosts supply the same verified cover assets already used by the carousel.
Collections may declare "presentation": {"mode": "covers"} in their signed
catalog so every supported host presents the same dark cover library.
Each child's optional bytes value supplies its exact initial download size.
For console collections, the shared host composes AppGameHome above the
guest in its own opaque strip and AppHostHome saves each departing game or
editor before returning to the root collection. F1 and controller View/Select
use the same route. This also applies to nested hosts such as Inner Breeze;
standalone games do not gain a collection navigation control.
A cover with action: "title" uses the shared artwork title and Play control.
Console shelves show that title before opening the game; standalone cover
collections already display it. Play opens the game directly. Games that draw
their own title retain action: "play". Activating a missing console game downloads it in place before its title can open.
A carousel cover with action: "buy" shows a localized Buy button and sends
install directly to the host. The host owns the price confirmation, purchase
and entitlement checks. This action grants no access to a bundle and requires
the card's explicit install capability.
A card for an app not on the device shows a download symbol. It opens a
dialog with the package size and what the app may reach, and the dialog's
Download is the person's consent; it then follows the download to Open, or
to Try again when it failed. Hosts describe this per card with
permissions (account, friends, audio, media), progress (percent
while downloading) and download_failed.
A collection may declare children it does not pack, such as Arcade's games,
which are downloaded one by one. AppPlatform.download gives such a card's
state, AppPlatform.fetch installs or removes it without opening it, and
AppPlatform.bundle returns its downloaded bytes, which the host checks
against the catalog digest before every open.
Providers may bound their resident cache without deleting verified downloads.
AppDownload.cached means the exact digest remains verified on disk. Such a
package stays installed on the shelf; only preparation of a requested open
calls fetch to restore its bytes, including its declared dependencies. Report
downloading while that restore waits, and keep ordinary missing packages
behind their existing download consent.
Keep returned bundle bytes immutable while AppHostBorrowsBundle(host, bytes)
returns true. Call it on the owning thread between host calls, after rendering
has consumed queued paint and AppHostCollect has run. It includes live and
dormant nodes, frontends, separate art, leased/resource dependencies, retired
runtimes and unfinished or canceled preparation inputs. It compares actual
source storage, including overlapping packed slices, never hashes or selected
navigation. Check every host sharing the allocation and any provider-owned
borrows before eviction. Keeping all bytes until AppHostStop remains valid.
An add-on declares its sibling dependencies in the same signed catalog.
Installation lists every missing package and its total size, and skips
dependencies already on the device. Read-only resources links reuse explicit
asset paths from those verified packages. Missing dependencies, cycles,
altered payloads and paths outside the declared app namespaces are rejected.
An add-on that reuses its base's code imports the base's modules like any
other Ziran code; the linker builds the reachable code into the add-on's own
.zx. There are no shared code bundles. The add-on's dependencies are then
only for resource links and shared records. Dependencies are verified on the
preparation worker, before guest code runs. When the base is already running,
the add-on leases that exact verified bundle instead of opening a second copy,
so the base's bytes are counted once toward the collection's memory limit.
Each instance keeps its own mutable state. Catalogs that still name the
retired shared_code key are rejected.
A base app may export a few flat saved-record names in shared_records.
Only a direct, verified dependent in that signed catalog may read them through
apps.records with {"operation":"get","app":"BASE_ID","record":"NAME"}.
The reply contains status (done, missing, rejected or unavailable)
and text for a successful read. The host keeps the current account and
authority, applies its ordinary storage policy and bounds replies to 64 KiB.
This grants no writes, no undeclared records and no access through a mere
dependency declaration.
A portable node/2 app may request kryon/frame_snapshot and call
CaptureFrameInput during its frame. Apps forwards that exact hosted capability
to Kryon's widget-host boundary, which returns only the snapshot published for
the active frame session; inactive and foreign-session calls fail closed.
Portable node/2 and app/1 games built with KRYON_HOSTED_UI may import
kryon/notification_schedule. Apps forwards its bounded reminder calls through
Kryon's shared scheduler only from the identified, active game frame. The native
namespace is hosted:<verified AppNode.identity.id>:<local tag>; guest arguments
cannot choose another game's identity. Collection controllers have no reminder
authority. The host explicitly grants kryon.notification.schedule through
AppPlatform.allows; revocation still permits that game's own cancellation.
Reminder packages require host interface 42 (APPS_NOTIFICATION_HOST_API in
apps/protocol) in their catalog and signed release metadata. Native consumers
advertise at least 42 only after adopting this dispatch and their grant/focus
callbacks. Earlier hosts reject those packages during compatibility validation;
new hosts bind denied reminder capabilities and return false at call time.
Set AppPlatform.focused(context, node) from actual native foreground and
selected-game state. Apps also verifies that node is active and running. Without
the callback, or while a different page/game is selected, opened calls return
false and cannot suppress a game's daily reminder. Guests cannot use this
capability to request Android notification permission; the outer app owns its
permission UI. build-queue -- python3 tests/notification_host_test.py /path/to/libziran.a
exercises real source/saved portable guests with a recording native provider.
Portable node/2 and app/1 apps can use kryon/Media's MediaAudio for packed
asset effects and looping music. Apps recognizes the actual
media_audio.MediaAudioHost capability, including its package-qualified name,
through Kryon's existing widget dispatcher. Every operation requires the
platform's existing AppSoundHost audio permission for that verified node;
widget access or permission for legacy Media/video services grants no asset
audio. Denied calls return Denied with no capability bits or playback
position. Legacy Media services retain their existing dispatch and permission
policy.
The native consumer installs its provider once on its owning thread with
MediaAudioUseDesktop() from kryon/media_audio_desktop. Without a provider,
authorized calls return Unsupported; device/browser results retain Kryon's
Unavailable/Suspended semantics. Apps supplies each actual HostedApp.audio
owner and AppHostAudioRead to WidgetHostAudioCall, using the active node's
verified bundle and explicit catalog resource links. Paths cannot name host
files or network URLs; Kryon bounds each asset to 8 MiB and each owner to 16
independent voices.
The packed borrow lasts until AppHostCollect; providers own decoded/copied
bytes before later reuse. Nodes sharing an outer Session keep separate voices
and readers. The permission gate applies to the full MediaAudio capability,
including per-voice Pause/Resume, Status, and bounded PCM operations
supported by the installed provider. Capability bits 16/32/64 advertise asset
pause/resume, asset-music position, and PCM pause/resume. Status returns
has_position: bool and position_seconds: float64; only an available provider
playhead sets has_position. Paused music freezes its position. PCM has no
position or drained counter; paused streams retain their bounded copied blocks
and report writable = false. Guests retain scheduling and synthesis policy.
WidgetHostEnd only ends dispatch; music survives frames. Node retirement
revokes audio immediately, before renderer/preparation storage is collected.
HostedAppClose and successful HostedAppRestart also release voices; failed
restart preserves the working instance. Account replacement uses the existing
save/AppHostStop/AppHostStart lifecycle. If a native consumer changes an
account, resource policy, or audio authority in place, it must first call
AppHostAudioReset(host) on the owning thread, while owner storage is still
alive. That hook resets all live instances/controllers and revokes a decoder
already in flight; Apps cannot infer changes hidden inside platform context.
Each run also revokes voices when AppSoundHost permission is withdrawn.
Portable node/2 and app/1 guests may request the zero-argument bool capabilities
app_context:DocumentStorageReadyHost and app_context:DocumentFlushHost.
The platform must explicitly allow each named capability and provide
AppPlatform.documents(context, node) -> *AppFiles, returning only that verified
node's existing authorized private namespace (or null). Apps never derives a
path, chooses an account, initializes browser storage, or grants a permission.
Calls from an inactive instance and denied calls return false; malformed or
foreign-module calls are rejected. No guest argument can select another node.
Readiness uses Kryon's AppFilesReady; a successful write alone does not
acknowledge browser persistence. Flush uses AppFilesFlush, waits for any
previous snapshot and then a fresh acknowledged snapshot, with Kryon's
15-second browser deadline. Later writes remain pending. Browser storage must
already be hydrated on the shared /kryon-apps mount; staging paths outside
that mount cannot claim durability. Native writes sync bytes and parent
directories. A failed flush neither reloads memory nor retries implicitly.
The provider owns the AppFiles and must keep it alive on the owning thread
until the yielding call returns. Call AppFilesClose before changing its
namespace, account, or authority; never overwrite live root/lock fields. Apps
rechecks namespace generation, account epoch, active instance, permission and
provider after acknowledgement. A revoked transaction returns false even if
its backing transaction later completes. The running VM cannot be reentered,
and collection retains a busy retired runtime until its call returns.
Inbe and Werkzeug use this same exported launcher and portable controller. App-specific title/account bars and navigation docks remain with their hosts. Build the controller with the host's compiler and Kryon graph, review its digest, and pin those exact bytes in the host. A mismatched controller must fail validation; never substitute another screen silently.
scripts/build-ui.py builds the standalone package controller. The native
fixture exercises real card/menu/dialog behavior (--controller-only runs
that controller suite independently); the external-consumer test
verifies public package imports and launcher search/grouping.
Unreleased
-
Forward portable games' offline reminders under each verified game's identity, and mark a game opened only while that game is selected and in the foreground. Reminder packages require a host with interface 42.
-
Align the shared controller with Profile apps using the fixed Android renderer packages.
-
apps/connectionasks one origin-bound permission for fetching content and automatic app updates. Existing stored yes answers remain valid, and hosts setAppPlatform.content_allowedonly after that consent. Installed children with a valid newer release then queue an update automatically; declined or unanswered consent exposes and queues no update. -
Releases reach only hosts that can run them. The publisher refuses a payload whose ZX header revision differs from the ledger's
zx_revision(top level or per app).apps/remote_catalogasks the node with itsoldest_host_apiand ZX revision (zx=28), so it is offered only collections of that revision. The node's history keeps the newest release of every payload format, ZX revision,host_apiandmodule_apibesides the newest ten, and every archived release stays on the node. -
A node app may also publish
NAME.wasm, the WebAssembly module Ziran lowers fromNAME.zx, beside it. It is signed as the same release with that module as its artifact (release-SEQUENCE.wasm.json), uploaded and checked by the node's receiver with the release, and served to web hosts that ask withformat=wasm. -
The node-app publisher accepts an exact reverse-domain id such as
xyz.waozi.wurmwhen a publisher pin lists it innode_app_ids. The ledger name must be the id's last part, and only the pin that lists the id may sign it. Ids that no pin lists are refused, andinbe.<name>apps publish as before. The node's receiver passes its pins tonode_app_idto accept them. -
A catalog child may name the node app that serves its bundle with an optional
package_id, which uses the same rules as app ids and defaults to the collection's id.AppEntryPackageRouteappends the entry's/api/v2/packages/<package_id>/<sha256>.zxroute. Hosts without this support refuse a catalog that sets it. -
Preserve the surrounding game theme when nested controls finish drawing.
-
apps/connectionprovides an origin-bound public node connection choice and a shared consent notice. Reading or drawing the notice starts no requests. Hosts keep cached apps usable offline and may revoke transfers at any time. -
apps/remote_catalogloads a signed collection independently of its native host. The host supplies the reviewed publisher key, app identity, API policy and minimum release sequence. Fetching requires an explicit allow call; signatures, compatibility, byte limits, digest and catalog shape are checked before the saved snapshot changes. Hosts stop the former root before collecting its bytes, retain per-app saves, and keep their reviewed controller. -
Align the published dependency graph on Kryon
ee9d204548295e6c6900939ba1120efe44659e79. Consumers must resolve the same Kryon revision for shared Session, Rectangle and Color values. Ziran972dc244c4ae67e87b6089869dff5abc9d36c1f8writes the Apps controller as ZX 26, so hosts built before ZX 27 still open it. -
Host document readiness and acknowledged flush through explicit per-node private AppFiles authority.
python3 tests/document_host_test.py /path/to/libziran.aruns real app/1 and node/2 guests; add--browser-runtime /path/to/wasm/libziran.afor disposable headless IDBFS persistence, hydration failure and revocation. -
Pin published Kryon asset audio and host it through Apps' existing audio permission, verified resources and per-instance lifetime.
-
Retry separate collection art after a refused request, failed transfer or bad copy, one transfer at a time and waiting 1 s, doubling to 60 s, between attempts.
python3 tests/art_host_test.py /path/to/libziran.aserves a real HTTP failure, then decodes the recovered art's pixels without a display. -
python3 tests/audio_host_test.py /path/to/libziran.aexercises real hosted guests with dummy/no-provider hosts and Kryon's desktop mixer on SDL's private dummy device. Runtests/native_fixture.py,tests/consumer_test.pyandtests/tree_test.shwith the same resolved compiler/runtime graph too.