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/connection asks one origin-bound permission for fetching content and automatic app updates. Existing stored yes answers remain valid, and hosts set AppPlatform.content_allowed only 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_catalog asks the node with its oldest_host_api and 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_api and module_api besides the newest ten, and every archived release stays on the node.

  • A node app may also publish NAME.wasm, the WebAssembly module Ziran lowers from NAME.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 with format=wasm.

  • The node-app publisher accepts an exact reverse-domain id such as xyz.waozi.wurm when a publisher pin lists it in node_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, and inbe.<name> apps publish as before. The node's receiver passes its pins to node_app_id to 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. AppEntryPackageRoute appends the entry's /api/v2/packages/<package_id>/<sha256>.zx route. Hosts without this support refuse a catalog that sets it.

  • Preserve the surrounding game theme when nested controls finish drawing.

  • apps/connection provides 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_catalog loads 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. Ziran 972dc244c4ae67e87b6089869dff5abc9d36c1f8 writes 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.a runs real app/1 and node/2 guests; add --browser-runtime /path/to/wasm/libziran.a for 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.a serves a real HTTP failure, then decodes the recovered art's pixels without a display.

  • python3 tests/audio_host_test.py /path/to/libziran.a exercises real hosted guests with dummy/no-provider hosts and Kryon's desktop mixer on SDL's private dummy device. Run tests/native_fixture.py, tests/consumer_test.py and tests/tree_test.sh with the same resolved compiler/runtime graph too.

S
Description
Shared app catalog, cards and controls for launching and hosting apps.
Readme
758 KiB
0 Stars 1 Watchers 0 Forks
No results found.
Languages
Ziran 79.6%
Python 19.4%
Shell 0.6%
C 0.4%