feat(truapi): Pocket modality RFC and protocol spec - #609
Draft
valentinfernandez1 wants to merge 2 commits into
Draft
feat(truapi): Pocket modality RFC and protocol spec#609valentinfernandez1 wants to merge 2 commits into
valentinfernandez1 wants to merge 2 commits into
Conversation
valentinfernandez1
marked this pull request as draft
September 4, 2026 16:02
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Tracking issue: #563
What this defines
Pocket is a collection of product-backed cards owned by the host. Each card shows a product's key information at a glance and opens the product when tapped.
The host renders each collapsed card natively from a
CustomRendererNodetree that the product's worker streams. Tapping a card opens the product's Widget executable in a WebView.A product cannot add a card on its own. The user adds one by following a Pocket deeplink and approving a host dialog that shows the card as it will look. Both the user and the owning product can remove a card. Humanity, Balance and Scarcity are privileged cards. They are always present and nobody can remove them.
Chat and Pocket share the product's single Worker executable. Its lifetime is a reference count: one reference per active chat, one per visible card. The host terminates the worker when the count reaches zero. When the worker starts, its entry module runs under a bounded time and memory budget.
The RFC also defines the deeplink format and where card definitions are published:
polkadot://<product>.<tld>/-/pocket/add?card=<id>offers to add a card, and/-/pocket/open?card=<id>expands one. The first path segment-is reserved for host-handled targets.pocket.cardslist. Each entry names the card and points at a static preview tree inside the product archive, so the approval dialog runs no product code.Protocol surface
pocket.list_subscribepocket.remove_cardpocket.action_subscribepocket.card_renderThe
Pockettrait is available to the Worker execution only. Every payload travels in aV1envelope. Acard_renderitem encodes byte for byte like a chat custom-message render item, so a host that decodes one decodes the other.The renderer tree types (
CustomRendererNode, its props, modifiers and tokens) live intruapi::v01::rendererand are re-exported throughtruapi::latest. Chat uses them from there. Their wire encoding is unchanged.Scope
This PR contains the RFC and the crate-level spec only.
truapi-serverimplements the trait with the default bodies. A host without a Pocket surface answersremove_cardwithUnavailable, ends the two subscriptions with an empty Interrupt frame, and never openscard_render.ProductRuntimeControl::render_pocket_cardis the entry point a host calls to open a face stream.Pocket behaviour in the runtime, the platform trait, the native bindings and the CLI is tracked by the "Implementation, rust-core" task in #563.