This is the specification of the messages between a document and the Genesis host. A document is the applet's UI (the role foreground) or a website page in one of the applet's contexts (the role context), where the page agent runs. Everything an applet does with Genesis goes through these messages: the SDK client and the page agent are one implementation of them, and a client in another language can drive the same pages by sending the same JSON.
packages/core/src/protocol.ts (TypeScript) and crates/contracts (Rust) are the two implementations of this specification. They must agree with it and with each other. When one of them changes the wire format, this file changes in the same commit.
For how an applet uses page control through the SDK, read page control. For the SDK's functions, read the SDK reference.
Messages are JSON text, one object per message. In the UI and in every website page, in WebView or GeckoView, the shell installs a bridge object as window.__genesisBridge, with postMessage(text) and a message event that carries the host's text. The SDK's webViewTransport() wraps it. Any other transport gives connect({ transport }) an object with send(text), onMessage(listener) (which returns a function that removes the listener) and close().
In a context page, the page agent captures __genesisBridge at document start, before any website script runs, and deletes it from the page, so website scripts cannot send messages as the agent.
The host ignores text that does not parse as a document message. It answers a request larger than limits.messageMaxBytes with MESSAGE_TOO_LARGE.
A document starts by sending hello. The host answers with bound, or with refused when the document speaks another protocol version.
{ "type": "hello", "protocol": 2, "url": "https://news.ycombinator.com/" }| Field | Meaning |
|---|---|
protocol |
The protocol version the document speaks, COMPAT.protocol. The host reads a missing value as 0. |
url |
The document's URL. |
{
"type": "bound",
"protocol": 2,
"compat": { "manifestSchema": 6, "bundleFormat": 3, "protocol": 2, "adapterApi": 1, "sessionState": 1, "importEnvelope": 1, "credentialEnvelope": 1, "cookieEnvelope": 1, "packagesIndex": 1 },
"documentId": "d7",
"appletId": "hn-reader",
"revision": 3,
"contextId": "primary",
"role": "context",
"generation": 2,
"manifest": { "schemaVersion": 6, "id": "hn-reader", "...": "..." },
"limits": { "rpcDeadlineMs": 10000, "...": "..." },
"session": null
}| Field | Meaning |
|---|---|
protocol |
The host's protocol version. |
compat |
Every compatibility number of this Genesis (see Versions). |
documentId |
This document's id. Every later request names it. |
appletId, revision |
The active applet and its installed revision. |
contextId |
The context this document runs in, or null for the foreground. |
role |
foreground or context. |
generation |
0 for the foreground. In a context it increases each time a new document binds there. |
manifest |
The applet's manifest. |
limits |
The limits below. |
session |
The foreground's last session.save ({ version, state }) when Genesis recreated the applet after retiring it in the background, otherwise null. Always null for a context. |
The values in the examples are illustrations. Read limits from bound, never from this file.
{ "type": "refused", "error": { "code": "PROTOCOL_MISMATCH", "message": "The page speaks protocol 1; this Genesis speaks 2" } }No bound follows refused. When a context document is refused, the foreground also receives context.gone with the code PROTOCOL_MISMATCH.
A hello from a context page whose context is not in the manifest gets no answer. A new document in a view replaces the view's previous document: the old one receives retired, and its open page calls end (see Call lifecycle).
When a foreground document binds, the host sends reset to every bound context document, because the new foreground knows none of the old one's calls and watches. It then sends the new foreground context.bound for each of those documents.
A document sends requests; the host answers each with one response. The host also sends events, which have no answer.
{ "type": "request", "documentId": "d4", "requestId": 12, "method": "storage.get", "params": { "collection": "saved", "key": "42" } }{ "type": "response", "documentId": "d4", "requestId": 12, "result": { "document": null, "namespaceRevision": 7 } }{ "type": "response", "documentId": "d4", "requestId": 13, "error": { "code": "NOT_FOUND", "message": "Unknown context feed" } }{ "type": "event", "documentId": "d4", "name": "context.navigated", "data": { "id": "primary", "url": "https://news.ycombinator.com/newest", "generation": 3, "index": 1, "size": 2, "canGoBack": true, "canGoForward": false, "sameDocument": false, "reload": false } }| Rule | Detail |
|---|---|
| Request ids | A number the document chooses, unique among its open requests. The response carries the same requestId. |
| Document id | A request whose documentId is not the view's current document is ignored, so a retired document gets no answers. |
| Params | null params are read as {}. Params that do not match the method's shape answer INVALID_ARGUMENT. |
| Response | Has result on success and error on failure, never both. |
| Roles | A method of the other role answers INVALID_ARGUMENT ("not available to this document"). A name that is no method answers UNKNOWN_METHOD. |
| No applet | A request while no applet is active answers RETIRED. |
An error is an ErrorBody:
{ "code": "CONTEXT_REPLACED", "message": "The page changed before the call finished", "details": { "dispatched": true, "navigating": true, "completedSteps": 1 } }details appears on failed page calls and says how far the call got: dispatched (input left the page agent), navigating (the input started a navigation), completedSteps, and reason, a short word such as hidden, covered or cross-origin-frame.
Params and results use the field names shown.
| Method | Params | Result |
|---|---|---|
ui.ready |
{} |
{}. The first call shows the foreground. |
storage.get |
{ collection, key } |
{ document, namespaceRevision }. document is { key, value, revision, updatedAtMs } or null. |
storage.list |
{ collection, afterKey?, limit? } |
{ entries, nextAfterKey, namespaceRevision }. limit defaults to 100. nextAfterKey is null on the last page. |
storage.commit |
{ checks, puts, deletes } |
{ namespaceRevision } |
services.request |
{ serviceId, path, method, body? } |
{ status, body }. An HTTP error status is a result, not an error. |
context.navigate |
{ id, url, mode? } |
{}. mode is push (default) or replace. |
context.back |
{ id, steps? } |
{}. steps defaults to 1. |
context.forward |
{ id } |
{} |
context.reload |
{ id } |
{} |
context.reveal |
{ id } |
{}. Shows the context's website above the foreground. |
context.cover |
{} |
{}. Covers the revealed website with the foreground again. |
session.save |
{ version, state } |
{}. version must equal COMPAT.sessionState. |
back.handled |
{ handled } |
{}. The answer to a back event. |
back.leave |
{} |
{}. Leaves the applet. |
page.call |
{ context, generation, op, args, timeoutMs? } |
The operation's value (see Page operations). |
page.cancel |
{ context, callId? } |
{} |
watch.subscribe |
{ context, id, spec, when?, persist? } |
{} at once. The host opens the watch in every page of the context that binds while the subscription lasts (see Watches). |
watch.unsubscribe |
{ context, id } |
{}. Ends the subscription and closes the page's watch. |
store.forget |
{ context? } |
{}. Forgets the watch values the host kept, in memory and on the phone, of one context or every context. |
debug.log |
{ entries } |
{}. Writes events to the applet's debug log (see Debug log). |
context.grant |
{ id, grant } |
{ granted: true, expiresInMs }. Lets a hidden context's page use one website feature once (see Grants). |
context.hold |
{ id, level } |
{}. Keeps a covered context's page going while the foreground needs it (see Activity). |
files.pick |
{ accept?, multiple? } |
{ files: [{ id, name, type, size }] }, empty when the user cancels (see User actions). |
files.release |
{ ids } |
{}. Lets go of picked files. |
downloads.save |
{ context, url, filename? } |
{ started: true } |
share.open |
{ title?, text?, url? } |
{ shown: true } |
links.openExternal |
{ url } |
{ opened: true }; NOT_FOUND when no app takes it. |
notifications.enable |
{} |
{ enabled } |
Rules the host applies:
- Storage needs
capabilities.storagein the manifest, elseCONFIGURATION_REQUIRED. Instorage.commit,checksare{ collection, key, expectedRevision }(null expects no document),putsare{ collection, key, value }anddeletesare{ collection, key }. A failed check isCONFLICT; a value overlimits.storedDocumentMaxBytesisDOCUMENT_TOO_LARGE. - Storage and service requests answer
QUOTA_EXCEEDEDwhilelimits.pendingRequestsMaxof them are open. - The
context.*methods answerNOT_FOUNDfor an id that is not a context of the manifest. context.navigateneeds anhttporhttpsURL with a host and no user name or password, elseINVALID_ARGUMENT. A URL outside the manifest's origins loads too, and shows as the website, because no page agent runs there.- After a
backevent,back.handledwithhandled: falsesteps back in the revealed context's history, or leaves the applet when there is none. With no answer withinlimits.backAnswerMs, the host steps back in the first context, in manifest order, that has history, or leaves. A second Back while the host waits is ignored.
Only a context document sends these. All but page.share and debug.log are about calls the host gave it.
| Method | Params | Result |
|---|---|---|
page.result |
{ callId, ok, value?, error? } |
{}. Answers one call. |
page.progress |
{ callId, state, completedSteps? } |
{}. state is dispatched or navigating. |
page.emit |
{ stream, kind, seq, view, url, data } |
{}. One message of a watch stream. |
page.input |
{ callId, events } |
{} once the shell dispatched the events. |
page.files |
{ callId, ids } |
{ count } once the shell posted the files to the page (see User actions). |
page.share |
{ title?, text?, url?, active } |
{ shown: true }. The website's own navigator.share (see User actions). |
debug.log |
{ entries } |
{}. The page agent's events for the applet's debug log. |
page.resultandpage.progressabout a call that is not this document's, or that has already ended, are accepted and ignored.page.resultwithok: falseand noerrorends the call withINVALID_ARGUMENT. The page agent checks a value before it answers: a value that is not JSON data (a BigInt, a cycle) answersINVALID_ARGUMENT, and one overlimits.pageMaxBytesanswersPAGE_TOO_LARGE.page.progressmarks the calldispatched, andnavigatingwhen that is the state. The host forwards it to the foreground as the eventpage.progress.page.emitanswersPAGE_TOO_LARGEfor a snapshot whosedatais overlimits.pageMaxBytes, andPATCH_TOO_LARGEfor a patch overlimits.patchMaxBytesor with more thanlimits.patchRecordsMaxupserts. The host addscontextandgenerationand forwards it as the eventpage.emit.page.inputcarries 1 to 64 real input events for one of the document's open calls (see Trusted input).
Events the foreground receives:
| Event | Data |
|---|---|
resumed |
{}. The applet came back to the foreground. |
suspended |
{}. The applet is going to the background. |
storage.changed |
{ changes, namespaceRevision }. changes lists { collection, key }. |
context.navigated |
{ id, url, generation, index, size, canGoBack, canGoForward, sameDocument, reload }. Sent for every committed navigation. index and size describe the context's back-forward list. |
context.started |
{ id, url }. A navigation started. |
context.bound |
{ id, generation, url }. A page agent in the context accepts calls. |
context.gone |
{ id, code, message }. The context's document is gone without a replacement, for example NOT_READY when a page on a declared origin did not bind within limits.documentReadyMs. |
user.viewWebsite |
{ id }. The user chose View website in the Genesis menu. id is the revealed context, or null when none is revealed (the foreground then picks its active context). |
user.done |
{ id }. The user tapped Done on the website bar. id is the revealed context or null. |
user.showContext |
{ id }. A link opened the applet in this context; show it. |
context.grantEnded |
{ id, grant, used }. A grant from context.grant was used, or ended unused (see Grants). |
back |
{}. The user pressed Back; answer with back.handled or back.leave. |
retired |
{}. The document will get no more answers. |
page.emit |
{ context, generation, stream, kind, seq, view, url, data, cached?, at? } |
page.progress |
{ context, callId, state, completedSteps? } |
Events a context document receives:
| Event | Data |
|---|---|
call |
{ callId, op, args, deadlineMs }. Run one page operation and answer with page.result. |
cancel |
{ callId? }. Cancel that call, or every call when callId is absent. |
reset |
{}. A new foreground bound: close every watch and cancel every call. |
retired |
{}. Stop: the document is replaced or the applet is closing. |
{ "type": "event", "documentId": "d7", "name": "call", "data": { "callId": "c14", "op": "read", "args": { "spec": { "one": { "css": "#hnmain" }, "fields": { "title": { "at": "title", "take": "text" } } } }, "deadlineMs": 10000 } }page.call asks the page agent in a context to run one operation. generation names the document the call is for, from context.bound. The value of the call is the operation's value; a failure is an error response.
| Operation | Args | Value |
|---|---|---|
info |
{} |
{ url, title, readyState, view, scroll: { x, y, maxX, maxY }, viewport: { width, height } } |
read |
{ spec } |
The read's value (see Read specifications). |
inspect |
{ target } |
{ count, first? }. first is { tag, text, visible, enabled, checked?, focused, rect }, with text cut to 200 characters. A target not on the page is { count: 0 }. |
watch.open |
{ id, spec, when? } |
{}. Starts a watch stream named id. |
watch.close |
{ id } |
{} |
watch.resync |
{ id?, kept? } |
{}. Sends a fresh snapshot of that watch, or of every watch. kept needs id and is the { key, data } records, in order, that the client kept of this history entry from an earlier document; a virtualized list reads again and continues from them when one of the rows on the page is among them. Other watches ignore it. |
wait |
{ for, timeoutMs } |
{} once the condition holds; DEADLINE when it does not in time. |
click |
{ target, gesture?, count?, ...options } |
ActionResult. gesture is click (default), tap or mouse; count is 1 or 2. |
longPress |
{ target, ms?, ...options } |
ActionResult |
hover |
{ target, ...options } |
ActionResult |
unhover |
{ ...options } |
ActionResult |
focus, blur |
{ target, ...options } |
ActionResult |
fill |
{ target, value, ...options } |
ActionResult |
type |
{ target, text, ...options } |
ActionResult |
press |
{ key, modifiers?, target?, ...options } |
ActionResult |
select |
{ target, values?, labels?, ...options } |
ActionResult |
check |
{ target, checked, ...options } |
ActionResult |
attachFiles |
{ target, files, via?, ...options } |
ActionResult. files holds 1 to 16 ids from files.pick. via is input (default: the target is an <input type="file">), drop or paste. Needs limits.userActions. |
scroll |
{ to, target? } |
{ x, y, maxX, maxY, atEnd }. to is start, end, intoView (needs target), { x?, y? } or { by: { x?, y? } }. |
submit |
{ target, ...options } |
ActionResult |
run |
{ steps, until?, navigates?, deadlineMs? } |
ActionResult |
invoke |
{ command, args?, target? } |
The command's value, or an ActionResult |
options are the input options: timeoutMs (how long to wait for the target to be actionable, default 0), force (skip the actionability check), input (synthetic, the default, or trusted) and until (evidence). Page control describes what each input does in the page.
{ "type": "request", "documentId": "d4", "requestId": 20, "method": "page.call", "params": { "context": "primary", "generation": 2, "op": "click", "args": { "target": { "record": { "watch": "stories", "key": "41234567" }, "css": ".votearrow" }, "timeoutMs": 2000, "until": { "target": { "record": { "watch": "stories", "key": "41234567" }, "css": ".votearrow" }, "state": "hidden" } }, "timeoutMs": 8000 } }{ "type": "response", "documentId": "d4", "requestId": 20, "result": { "outcome": "observed", "completedSteps": 1, "partial": false } }Read operations (info, read, inspect, watch.*, wait) run as soon as they arrive. Input operations, run and invoke run one at a time, in arrival order. One that waited in that order while an earlier input changed the view (a same-document navigation) dispatches nothing and answers failed with PRECONDITION_FAILED, since the client chose it for the view it saw; scroll is exempt. An operation name the agent does not know answers UNKNOWN_OPERATION.
Inputs, run and invoke with steps never fail with an error response for a problem in the page. They answer an ActionResult:
| Field | Meaning |
|---|---|
outcome |
observed: the input ran and its evidence held (or it had no evidence). failed: nothing took effect. unknown: input reached the page, but whether it took effect is not known. cancelled: the call was cancelled before any input. |
code, message |
Why, when the outcome is not observed, or why an unknown stayed unknown. |
reason |
A short word for NOT_ACTIONABLE and similar codes: detached, hidden, disabled, covered, not-a-text-field, not-editable, not-a-select, not-a-file-input, type-not-accepted, editor-needs-trusted-input, or state-unchanged (with DEADLINE). |
completedSteps |
Steps that finished. |
partial |
Some steps finished and the outcome is not observed. |
noop |
The wanted state already held, so no input was sent. |
exhausted |
Reserved for a load-more action that found the end of a list. The page agent does not set it. |
Invalid input arguments answer { outcome: "failed", code: "INVALID_ARGUMENT" }. scroll is the exception among inputs: it answers ScrollPosition, and invalid arguments or a missing target are an error response.
run takes a list of steps. A step is an input operation written as { "op": "<name>", ...args }, a wait { "op": "wait", "for": <condition>, "timeoutMs": n }, or a navigation { "op": "navigate", "url": "..." }. navigate goes only to an https URL on one of the manifest's origins, and a relative URL resolves against the page; any other URL answers failed with INVALID_ARGUMENT. navigate and submit may only be the last step. The agent runs the steps inside the page with no round trip between them. deadlineMs, counted from the call's arrival, shortens the call's own deadline; it must be a finite number above 0.
{ "op": "run", "args": { "steps": [
{ "op": "fill", "target": { "css": "textarea[name=text]" }, "value": "Nice write-up." },
{ "op": "submit", "target": { "css": "form[action=comment]" } }
] } }A wait condition is { target, state }, { url: UrlGuard } or { read: ReadSpec }. Evidence (until) is { target, state } or { read }. state is attached, visible, hidden or detached. A read condition holds when its value is truthy, and a list read when it has at least one record.
invoke runs a command of the applet's page module. The value depends on what the command returns:
| The command returns | The call answers |
|---|---|
| A JSON value | That value (null for undefined). |
{ satisfied: true } |
{ outcome: "observed", noop: true } |
{ steps, until?, navigates?, deadlineMs? } |
The steps run as run would run them; the value is an ActionResult. |
| A promise | INVALID_STEPS |
| It throws | INVALID_STEPS |
A command name the module does not have answers NOT_FOUND.
foreground host context page agent
page.call ─────▶ checks, starts the clock
call ───────────────────▶ runs the operation
◀───── page.progress ◀───────── page.progress (dispatched | navigating)
response ◀───── answers the request ◀─── page.result
The host checks a page.call in this order:
| Check | Error |
|---|---|
| The context exists | NOT_FOUND |
| The context has a bound document | NOT_READY |
generation is not older than the bound document's |
CONTEXT_REPLACED |
generation is not newer (the next document has not bound) |
NOT_READY |
Fewer than limits.pendingRequestsMax calls are open in the context |
QUOTA_EXCEEDED |
| For an input operation, the context's input budget has a token | RATE_LIMITED |
Input operations (click, longPress, fill, type, press, select, check, submit, attachFiles, run and invoke) spend the context's input budget: limits.inputBurst calls at once, then one more every limits.inputRefillMs. Reads, watches, wait, scroll, hover, unhover, focus, blur and navigation spend nothing. An empty budget answers RATE_LIMITED with details { dispatched: false, retryAfterMs }; nothing reached the page, so the client reports the input as failed. Do not retry it on a timer: the next input should come from the user's next tap.
The call's budget is min(timeoutMs or limits.rpcDeadlineMs, limits.actionTimeoutMs). The host sends it to the page as deadlineMs.
A call ends in one of four ways:
- The page answers with
page.result. The host answers the foreground's request with the value or the error. - The document is replaced (a cross-document navigation, a reload, the page leaving the context) before it answers. The host ends the call with
CONTEXT_REPLACED. - The budget runs out. The host ends the call with
DEADLINE. The budget does not count the time a JavaScript dialog of the context is open (see Website dialogs). - The foreground document that asked is retired. The call is dropped with no answer.
In cases 2 and 3 the error's details hold dispatched, navigating and completedSteps as the last page.progress reported them. This is how a client tells a call that never touched the page (dispatched false: safe to send again) from an input that may have taken effect (dispatched true: never send again without checking the page). A call with navigating true started a navigation, and the client judges the effect on the destination page.
The page agent reports dispatched before the first step that has an effect. When the steps navigate (the last step is navigate or submit, or navigates is true), it reports navigating instead and waits for the host to record it before the effect runs. A pagehide during an effect also reports navigating.
page.cancel sends cancel to the context only while one of the asking document's matching calls has not dispatched. The agent answers a cancelled call that has not started its input with { outcome: "cancelled" }; a call that has already sent input runs to its end.
reset cancels every call and closes every watch. retired stops the agent without answering its calls; the host ends them as above. After a pageshow from the back-forward cache, the agent sends hello again and binds as a new document.
A watch is a stream of page.emit messages that keeps the client's copy of a read up to date. The page agent observes the DOM, re-reads what changed, and sends the difference.
The foreground does not open watches in pages itself. It sends watch.subscribe once, and the host opens the watch (watch.open) in each page of the context that binds, until watch.unsubscribe, a new foreground document or the applet's retirement. The same id with another spec or when answers CONFLICT, and an open that fails reaches the foreground as a status emit with status: "error".
The host keeps each subscribed watch's last value. When a page binds, the host first sends that value as a snapshot with cached: true and at (epoch milliseconds when it last changed), then the page's own messages follow. A cached snapshot carries no stream position. With persist: true the host also keeps the value on the phone for up to 7 days, for the next start of the applet; it erases kept values with store.forget and when the user clears the website's data.
A website often renders after the page's first read. A snapshot that read nothing, a list without items or a null value, replaces a kept value with data only after the page has stayed empty for limits.documentReadyMs. Until then the host keeps and sends the kept value, and the client shows it, marked stale. The client shows the empty read sooner when the watch goes idle or fails, or the page changes. The host never sends an empty value as a cached snapshot. The client holds any other stale data the same way while the page's read is empty: the copy of a history entry after Back, and the last data while the page loads again. A cached snapshot can arrive after the page's first snapshot when that one read nothing; the client shows it and holds it the same way. After a snapshot with data, the host sends no cached snapshot.
| Kind | Data | When |
|---|---|---|
snapshot |
{ status, value?, order?, records?, error?, truncated?, complete? } |
The first message, after a new view, after a resync, and whenever a patch cannot carry the change. |
patch |
{ upsert?, remove?, order?, complete? } |
A list changed. upsert maps keys to records. |
status |
{ idle?, status?, error? } |
The agent sends { idle: true } when the URL stops matching the watch's when guards. |
{ "type": "request", "documentId": "d7", "requestId": 31, "method": "page.emit", "params": { "stream": "stories", "kind": "patch", "seq": 5, "view": { "generation": 2, "n": 0, "url": "https://news.ycombinator.com/" }, "url": "https://news.ycombinator.com/", "data": { "upsert": { "41234567": { "title": "Show HN: A tiny text editor", "points": 129 } } } } }{ "type": "event", "documentId": "d4", "name": "page.emit", "data": { "context": "primary", "generation": 2, "stream": "stories", "kind": "snapshot", "seq": 1, "view": { "generation": 2, "n": 0, "url": "https://news.ycombinator.com/" }, "url": "https://news.ycombinator.com/", "data": { "status": "ready", "order": ["41234567"], "records": { "41234567": { "title": "Show HN: A tiny text editor", "points": 128 } } } } }seqstarts at 1 for each watch and increases by one per message. A patch applies only when itsseqis one more than the last applied message of the same view. On a gap, the client asks forwatch.resync.viewis{ generation, n, url }.ncounts the same-document navigations that changed the page's entry key (path and query), so a single-page website's route change starts a new view. On a new view every watch sends a snapshot once the DOM settles. Records belong to one view.- Messages of an older generation or view are stale. A client drops a patch from another view and a message with a
seqit has already applied.
open ─▶ snapshot ─▶ patch* ─▶ snapshot (new view, resync, refused patch)
│ │
└── URL fails `when` ──┴─▶ status { idle: true } ─▶ (URL matches again) ─▶ snapshot
- A watch with
whenreads only while the page URL matches one of its guards. When the URL stops matching, it sends onestatus { idle: true }and stops reading. When it matches again, the next message is a snapshot. statusis aPageStatus:loading,ready,error,authorunsupported. The page agent sends onlyreadyanderror; the other values are for clients.- A read that throws makes the watch
error: the snapshot hasstatus: "error"anderror. The next successful read sendsstatus: "ready"in a snapshot. - A read whose value is not JSON data (a BigInt, a cycle) fails
watch.openwithINVALID_ARGUMENT. When that happens later, the watch reportsstatus: "error"withINVALID_ARGUMENT. - Changes are batched: the agent sends a batch after
limits.publishQuietMswithout changes, and at least everylimits.publishMaxDelayMs. - The agent splits a change into patches of at most
limits.patchRecordsMaxupserts andlimits.patchMaxBytes. Only the last patch carriesremove,orderandcomplete, so the client gets the new order only after every record it names. A patch the host refuses makes the next message a snapshot. - A snapshot over
limits.pageMaxBytesdrops a quarter of a virtualized list's records farthest from those on screen until it fits. Otherwise the watch reportsstatus: "error"withPAGE_TOO_LARGE. truncated: truemeans the list has more items thanlimit(or the agent's maximum, five timeslimits.patchRecordsMax) allows.- In a
virtualizedlist, records whose elements left the DOM stay in the view's list withpresent: falseadded to their data. The agent keeps the list of a view it leaves or whose watch closes (the last 8), and a watch that reads that view again in the same document continues from it once the page shows one of its records. completeis present for a page module list reader that names a "more" selector, and false while the "more" element is on the page.
The page agent keeps at most limits.watchesMax watches per document; one more answers QUOTA_EXCEEDED. A watch id is 1 to 64 letters, digits, _, ., : or -, starting with a letter or digit. Opening an id that is already open answers CONFLICT. watch.resync of an id that is not open answers NOT_FOUND. Watches end with the document: on pagehide, reset and retired.
A locator is a JSON object that finds elements in the page when the operation runs.
| Key | Type | Meaning |
|---|---|---|
css |
string | Elements matching the selector. |
role |
string | Elements with that ARIA role, from the role attribute or the tag's implicit role. |
name |
string | With role: the accessible name contains this text. |
text |
string | The deepest elements whose text contains this text. The text leaves out the content of script, style, noscript and template elements. With css or role, filters their matches. |
exact |
boolean | With text: the text must be equal, not contained. |
record |
{ watch, key } |
The element of one record of an open list watch. With css, role or text, searches inside it. It cannot be combined with within or frame. |
within |
locator | Searches inside the first match of this locator. |
has |
locator | Keeps elements that contain a match of this locator. |
nth |
integer | Keeps the match at this index; a negative index counts from the end. |
frame |
locator | Enters the same-origin iframe this locator matches. |
pierce |
boolean | Also searches open shadow roots. |
strict |
boolean | More than one match is AMBIGUOUS_TARGET. |
Rules:
- A locator needs one of
css,role,textorrecord.nameneedsrole;exactneedstext. Unknown keys are invalid. within,hasandframenest at most 4 levels.- A
cssselector, and a read field'sat, may not test thevalueattribute, in any case, with a namespace, or written with CSS escapes. Such a selector isINVALID_ARGUMENT, because a selector like[value^=a]would reveal a protected value one character at a time. - Text comparisons collapse white space, trim and ignore case.
- Matches are in document order.
hasandstrictapply beforenth. - An invalid locator is
INVALID_ARGUMENTwith the path of the bad field, such astarget.within.nth: must be an integer.
| Failure | Code |
|---|---|
| Nothing matches | NOT_FOUND |
A record key is not on the page |
TARGET_NOT_FOUND |
| No list watch with that id is open | NOT_FOUND |
within or frame finds nothing |
NOT_FOUND |
| A cross-origin frame | NOT_FOUND, reason cross-origin-frame |
| A strict locator matches more than one element | AMBIGUOUS_TARGET |
| An invalid CSS selector | INVALID_ARGUMENT |
A read specification (ReadSpec) says what to read. It is one of three shapes:
| Shape | Value |
|---|---|
{ one, fields, measure? } |
The fields of the first element one matches, or null when none does. measure: true reads again when the element changes size. |
{ list, key, fields, within?, virtualized?, limit? } |
{ order, records, truncated?, complete? }: every element list matches (inside within when given), keyed by the key field. |
A watch of the first two shapes whose fields take value or checked reads again on input and change events, because form values change without DOM mutations.
| { reader, args? } | The value of the page module's reader with that name. An unknown reader is NOT_FOUND. |
fields maps names to fields. A field is { at?, take?, all?, fields?, max? }:
| Key | Meaning |
|---|---|
at |
A CSS selector inside the element. Without it the field reads the element itself. With no match the field is null. |
take |
What to read (below). |
fields |
Nested fields of the element at finds. A field has exactly one of take and fields. |
all |
Reads every match of at into an array. |
max |
The longest text kept, 1 to 2000 characters (the default is 2000). |
| Take | Value |
|---|---|
text |
The rendered text with white space collapsed. |
ownText |
The element's own text nodes, without its children's text. |
number |
The first number in the text, without thousands separators, or null. |
url |
href or src as an absolute URL. |
value |
A form control's value. |
checked |
A checkbox, radio, or aria-checked, aria-pressed or aria-selected state; null when the element has none. |
visible |
Whether the element has a box and is not hidden by style. |
rect |
{ x, y, width, height } in CSS pixels. |
exists |
Whether at matches. |
count |
How many elements at matches. |
{ attr: name } |
The attribute's value, or null. |
Rules:
- Fields nest at most 4 levels.
- A list's
keyreads one value: noallorfields, andtakeistext,ownText,url,value,numberor{ attr }. An empty key isINVALID_ARGUMENT. Two items with one key areCONFLICT. limitis a positive integer. The agent caps every list at five timeslimits.patchRecordsMax; past it the value hastruncated: true.- A read never returns the value of a protected field (see Protected fields).
- A reader must return its value synchronously; a promise is
ASYNC_READ.
{ "list": { "css": "tr.athing" }, "key": { "take": { "attr": "id" } }, "fields": { "title": { "at": ".titleline > a", "take": "text" }, "link": { "at": ".titleline > a", "take": "url" } }, "limit": 30 }A URL guard is { pattern, query? }. pattern uses the route syntax: it starts with /, :name matches one path segment, a trailing * matches the rest, and it has at most 256 characters. query lists query keys that must be present. A guard matches the path of any origin. when and expect take a non-empty array of guards; a URL matches when one guard does.
The agent never reads or writes the value of a password field, a hidden input, or a field whose autocomplete is current-password, new-password, one-time-code or starts with cc-. A read of value, or of the value attribute, gives null. fill, type and select on one, and press with such a target, are PROTECTED_FIELD. A selector may not test the value attribute (see Locators). A trusted press refuses a protected field even without a target, because the key goes to the focused element.
click, hover, unhover, type and press accept input: "trusted". The agent finds the target and its point (for an element in a same-origin frame, measured through every containing frame onto the top page), and sends page.input with the events for the shell to dispatch as real Android input to the hidden context's page, in whichever engine runs it. The events reach the page as trusted DOM events.
| Event | Shape | Dispatch |
|---|---|---|
tap |
{ type, x, y } |
A touch down and up 50 ms apart. |
hover |
{ type, x, y } |
A mouse hover enter (the first time) and move. |
hoverExit |
{ type } |
The mouse moves out of the view, then exits. |
key |
{ type, key, modifiers? } |
Key down and up. key is a DOM key name. |
text |
{ type, text } |
The key events that type the text. |
{ "type": "request", "documentId": "d7", "requestId": 40, "method": "page.input", "params": { "callId": "c22", "events": [{ "type": "tap", "x": 187.5, "y": 412 }] } }xandyare CSS pixels of the visual viewport at scale 1: the element's client position minusvisualViewport.offsetLeftandoffsetTop, timesvisualViewport.scale. The shell multiplies them by the display density.- Named keys are
Enter,Tab,Escape,Backspace,Delete," "(space),ArrowUp,ArrowDown,ArrowLeft,ArrowRight,Home,End,PageUpandPageDown; any other key is one character. Modifiers areShift,Control,AltandMeta.ControlandMetawork only with named keys. - The shell converts every event first and dispatches nothing when one cannot be converted: an unknown event, key or modifier, a point outside the view, text that cannot be typed as keys, or a key that would reach the clipboard (
ControlorMetawith a one-character key, orShift+Delete). That answersINPUT_UNAVAILABLE. - One
page.inputtypes at most 2000 characters across itstextevents; more isINVALID_ARGUMENT. The page agent refuses a trustedtypeof a longer text the same way, before it sends anything. page.inputanswersINPUT_UNAVAILABLEwhenlimits.trustedInputis not true, and when the context is revealed: the user is looking at the website then, and applet input there would count as the user's own gesture. It answersCONTEXT_REPLACEDwhen another document has already started loading in the context,NOT_FOUNDwhencallIdis not an open call of the asking document, andDEADLINEwhen the call's budget runs out first.- A trusted
clickis one touch tap:gestureother thantap, orcountother than 1, isINVALID_ARGUMENT. Any other operation withinput: "trusted"isINVALID_ARGUMENT. - A trusted tap or key gives the page user activation. A trusted hover does not.
- For 5 seconds after the last trusted input to a context's page, that page may not open a window or hand a link to another app, even once it is revealed and the user taps it. The page's user activation can outlast the input, so the shell does not count any gesture as the user's in that time. The one exception is a live
windoworhandoffgrant (see Grants): it lets one such request through.
A page's alert, confirm, prompt and beforeunload dialogs block the page until they are answered. On a revealed context, its popup and the foreground, they are WebView's own dialogs. On a hidden context, the shell shows Genesis's own dialog at once, over the applet UI and titled with the page's origin; the website stays hidden and the foreground receives no message. The user's answer goes straight to the page.
- The dialog shows the site's exact message, a field for a prompt, OK, and Cancel for every kind but
alert. Android Back cancels it. - When the page navigates or goes away while the dialog is open, the dialog is cancelled.
- While a dialog is open, the context's page calls do not use up their budget: when the dialog ends, the host adds the time it was open to each of their deadlines. The page agent keeps its own clock for waits and evidence, so an effect that appears only later after a long dialog can still end as
unknownwithDEADLINE.
files.pick, downloads.save, share.open, links.openExternal and notifications.enable are things only the user may start. The host passes each to the shell, which carries it out only after a tap on the applet UI in the last 3 seconds, once per tap. Without one it does nothing and answers USER_ACTION_REQUIRED; the foreground then asks the user to tap again. A tap on the website, the website bar or a popup does not count, and neither does trusted input. The host's deadline for these methods is 10 minutes, because the user may stay in a picker or a permission prompt; the client waits as long.
{ "type": "request", "documentId": "d3", "requestId": 51, "method": "files.pick", "params": { "accept": ["image/*", "video/*"], "multiple": true } }{ "type": "response", "documentId": "d3", "requestId": 51, "result": { "files": [{ "id": "9f0c2e6a41d8b7735c1e0a9d2f4b6c18", "name": "beach.jpg", "type": "image/jpeg", "size": 482113 }] } }files.pick:acceptholds up to 16 MIME types (image/*) or.extsuffixes; anything else isINVALID_ARGUMENT. Image and video types open Android's photo picker, others the document picker. At most 16 files of 64 MiB each; a larger file is left out. Anidis 32 hex characters and stays valid untilfiles.release, until the applet is retired or its window closes, or for 30 minutes. The foreground shows a picked file athttps://appassets.androidplatform.net/genesis-files/<id>, for example as an<img>or<video>source; only the foreground can load it. The file stays with Genesis: never put anidin storage, because it means nothing after it expires.downloads.save:urlishttps, or adata:URL up to 2 MiB, with no user name or password, elseINVALID_ARGUMENT. The https download carries the cookies and User-Agent ofcontext(NOT_FOUNDwhen it is not a running context of the manifest).filenameis 1 to 128 characters without/. The file goes to Downloads.share.openneeds at least one field.titleis at most 200 characters,text4000, andurlishttporhttps. The answer means the share sheet showed, not that the user shared.links.openExternaltakesmailto,tel,sms,smsto,geo,intentandhttps. Anhttpslink opens only in an app that claims it, never in a browser; on Android 10 and earlier, and when no app claims it, the answer isNOT_FOUND.notifications.enableneedscapabilities.notifications, elseCONFIGURATION_REQUIRED. It turns on the applet's notifications as the Applet info switch does, asking Android first on Android 13 and later.enabledis false when the user or Android refused.page.shareis the page agent'snavigator.sharefor a website that has none in the WebView. It takes the same fields and limits asshare.open. It works only while the context is revealed, and only whenactiveis true, because the user tapped the website itself: otherwise it answersUSER_ACTION_REQUIRED. A tap on the applet UI does not count, and it needslimits.userActions.page.filescarries picked files to the page for the page agent'sattachFilesoperation. It needs an open call of the asking document (NOT_FOUND), a context that is not already loading another document (CONTEXT_REPLACED), and ids the applet still holds (FILE_UNAVAILABLE). The shell posts the bytes straight to the page, not through the host.limits.userActionsis true when the host takes these methods andattachFiles. It is absent in an older Genesis.
A hidden context's page cannot show UI of its own: it may not go fullscreen, download a file, open a window, hand a link to another app or ask for the location. context.grant lets it do one of these once, right after the user's tap on the applet UI:
{ "type": "request", "documentId": "d3", "requestId": 52, "method": "context.grant", "params": { "id": "main", "grant": "fullscreen" } }{ "type": "response", "documentId": "d3", "requestId": 52, "result": { "granted": true, "expiresInMs": 5000 } }grantisfullscreen,download,window,handofforlocation.context.grantis a user action: without a fresh tap on the applet UI it answersUSER_ACTION_REQUIREDand grants nothing (see User actions). An unknownidisNOT_FOUND.- A revealed context needs no grant, because the user taps the website itself: the answer is
{ granted: true, expiresInMs: 0 }at once, and nocontext.grantEndedfollows. - The page has 5 seconds to use the grant, once. Then the foreground drives the page to the feature, usually with a trusted click (
await ctx.allow("fullscreen"), thenclickwithinput: "trusted"). fullscreenshows the page's fullscreen view over everything; the context stays hidden, and Back or the page's own exit returns to the applet.downloadsaves anhttp,httpsordata:download to Downloads, and ablob:one on a declared origin, where the page agent reads it. Ablob:ordata:file takes thedownloadname of the link the user clicked, when the page agent saw the click.windowopens the page's popup in a sheet over the applet; closing it returns to the applet.handofflets one link open in another app.locationshows Genesis's location prompt for the page's origin over the applet.- A
windoworhandoffgrant overrides the 5-second block after trusted input (see Trusted input) for that one request. - One grant per context: a new grant replaces an unused one. The grant ends when it is used, after 5 seconds, and when the page navigates, the context is revealed or covered, a popup opens or the view goes away. Each end sends
context.grantEnded { id, grant, used }. limits.grantsis true when the host takescontext.grant. It is absent in an older Genesis.
A covered context's page does not draw, so the host runs it at one of three levels: awake (full speed), running (scripts, timers and media, no drawing) and resting (timers and drawing paused). The page is awake while it loads, during a page.call, an input or a navigation and for a few seconds after, during a grant, and while it is revealed. Otherwise it rests, unless the foreground holds it with context.hold:
{ "type": "request", "documentId": "d3", "requestId": 53, "method": "context.hold", "params": { "id": "main", "level": "running" } }{ "type": "response", "documentId": "d3", "requestId": 53, "result": {} }levelisrunning,awakeornull.runninglasts until the foreground changes it.awakeis full speed for at most 30 seconds, then the hold counts asrunning.nullreleases the hold. An unknownidisNOT_FOUND.- One hold per context: each
context.holdreplaces the one before. The client counts its callers and sends the highest level any of them asks for. - A hold on a context that has not started starts it. Contexts start one after another, and a
page.callor navigation that names a context starts it at once. - A new foreground document starts with no holds.
- Requests and events are the same at every level. A watch on a resting page delivers its changes up to about a second late.
limits.activityis true when the host rests covered pages and takescontext.hold. It is absent in an older Genesis, where a covered page always runs andcontext.holdanswersUNKNOWN_METHOD.
The user can turn an applet's debug log on in its info screen, under Troubleshooting. It turns off on its own after 7 days. While it is on, bound.limits.debugLog is true and every document sends its events in batches with debug.log:
{ "type": "request", "documentId": "d4", "requestId": 61, "method": "debug.log", "params": { "entries": [{ "t": 1795000000000, "ev": "frame.long", "d": { "ms": 84 } }] } }- An entry is
{ t, ev, d? }: epoch milliseconds, an event name of at most 64 characters, and fields of names, counts, durations and error codes. Strings are cut to 300 characters. Never put page text, stored data, typed text, cookies or query strings in an entry. - One call writes at most 200 entries and 16 KiB; the rest are counted, not written.
- The host and the shell add their own events, such as page calls, emits and
service.resultwith each service request's duration and status. The host writes everything to JSON lines in the app's files directory, and the user shares the file from the same screen. - With the log off,
debug.logis accepted and ignored.
| Code | Meaning |
|---|---|
RETIRED |
The applet or document is no longer active. |
CONFLICT |
A storage check failed, a watch id is already open, or two list items have the same key. |
NOT_FOUND |
An unknown context, call, watch, reader, command, option, or a locator that matches nothing. |
DOCUMENT_TOO_LARGE |
A stored value is over limits.storedDocumentMaxBytes. |
STORAGE_FAILURE |
Storage could not complete the request. |
ORIGIN_NOT_DECLARED |
Reserved. Nothing returns it now. |
MESSAGE_TOO_LARGE |
A request is over limits.messageMaxBytes. |
PAGE_TOO_LARGE |
A watch snapshot, or a page call's value, is over limits.pageMaxBytes. |
PATCH_TOO_LARGE |
A watch patch is over limits.patchMaxBytes or limits.patchRecordsMax. |
DEADLINE |
A request, call, wait or evidence ran out of time. |
INVALID_STEPS |
A page module command threw, returned a promise, or returned invalid steps. |
SERVICE_UNREACHABLE |
A backend service could not be reached. |
SERVICE_FAILURE |
A backend service request failed. |
AUTHENTICATION_FAILED |
A backend service refused the credentials. |
CERTIFICATE_FAILED |
A backend service's certificate did not verify. |
CONFIGURATION_REQUIRED |
The manifest does not declare what the method needs, or a service has no credentials. |
NOT_READY |
The context has no bound document yet, or a page did not load in time. |
UNKNOWN_METHOD |
No such method. |
INVALID_ARGUMENT |
Params, args, a locator or a read specification are invalid, or a method of the other role was called. |
QUOTA_EXCEEDED |
Too many pending requests, open calls or watches. |
PROTOCOL_MISMATCH |
The document and the host speak different protocol versions, or the page agent's operation set differs from this Genesis's. |
APPLET_INCOMPATIBLE |
The applet was built for another manifest schema or bundle format. |
ENVELOPE_INVALID |
An import file's envelope is invalid. |
CONTEXT_REPLACED |
The document a call was for has been replaced. |
TARGET_NOT_FOUND |
A record's element is not on the page. |
PRECONDITION_FAILED |
A queued input did not run because an earlier input changed the view first. |
ASYNC_READ |
A reader returned a promise. |
AUTH_REQUIRED |
Reserved. Nothing returns it now; the router reports a signed-out page as a route status instead. |
REJECTED |
The website refused the input: the destination matched expect.notUrl. |
NOT_ACTIONABLE |
The target cannot take input; reason says why. |
AMBIGUOUS_TARGET |
A strict locator matched more than one element. |
PROTECTED_FIELD |
The input would write into a protected field. |
INPUT_UNAVAILABLE |
Trusted input is not available, or the shell could not dispatch it. |
UNKNOWN_OPERATION |
The page agent has no such operation. |
USER_ACTION_REQUIRED |
The action needs a fresh tap on the applet UI, and there was none or it was already used. Nothing happened. |
FILE_UNAVAILABLE |
A file id is unknown, expired or released, or its file can no longer be read. |
RATE_LIMITED |
The context's input budget is empty. Nothing reached the page; details.retryAfterMs says when one more input is allowed. |
packages/core/src/errors.ts and crates/contracts list the same codes.
bound.limits carries the limits the host and the page agent enforce.
| Limit | What it bounds |
|---|---|
rpcDeadlineMs |
The default budget of a request or page call. |
messageMaxBytes |
One request's size. |
pageMaxBytes |
One watch snapshot's data. |
patchMaxBytes |
One watch patch's data. |
patchRecordsMax |
Upserts in one patch; five times it caps a list read. |
storedDocumentMaxBytes |
One stored value. |
pendingRequestsMax |
Open storage and service requests, and open page calls per context. |
documentReadyMs |
How long a context page on a declared origin has to bind after it commits. |
navigationJoinMs |
Sent in bound; neither the host nor the SDK uses it now. |
publishQuietMs |
The quiet time before the agent sends a batch of watch changes. |
publishMaxDelayMs |
The longest the agent holds watch changes. |
actionTimeoutMs |
The most a page call's budget can be, whatever timeoutMs asks for. |
backAnswerMs |
How long the host waits for an answer to back. |
historyEntriesMax |
History entries per watch whose last copy the client keeps. |
watchesMax |
Open watches per context document. |
trustedInput |
True when the shell can send real input to a hidden context. Absent in an older Genesis. |
userActions |
True when the foreground can pick files, save, share, open links in apps and turn on notifications, and attach picked files with attachFiles. Absent in an older Genesis. |
grants |
True when the foreground can let a hidden page use one website feature once with context.grant. Absent in an older Genesis. |
activity |
True when the host rests a covered context's page while it is unused and takes context.hold. Absent in an older Genesis. |
inputBurst, inputRefillMs |
A context's input budget: input page calls at once (20), and milliseconds for one to come back (1000). Absent in an older Genesis, which has no budget. |
debugLog |
True while the user has the applet's debug log on: the document sends its events with debug.log. Absent or false otherwise. |
bound.compat carries every compatibility number of the running Genesis. packages/core/src/compat.ts defines them as COMPAT, and crates/contracts has the same values. tools/check-packages.mjs checks that the two agree.
| Name | Covers |
|---|---|
manifestSchema |
The shape of applet.json. |
bundleFormat |
bundle.json and the bundle's files. |
protocol |
The messages in this file: envelope, handshake, methods and events. |
adapterApi |
The page agent's operations, locators, read specifications and watch stream. |
sessionState |
The session.save payload. |
importEnvelope |
The import file around a bundle. |
credentialEnvelope |
The service credential import file. |
cookieEnvelope |
The development cookie import file of debug builds. |
packagesIndex |
genesis.packages.json. |
The current values are those in compat.ts. What each mismatch does today:
- A
hellowith anotherprotocolgetsrefusedwithPROTOCOL_MISMATCH. - The SDK's
connectrejects withPROTOCOL_MISMATCHwhencompat.protocolorcompat.sessionStatediffers from the SDK's own. - A page agent whose
adapterApidiffers fromcompat.adapterApianswers every call withPROTOCOL_MISMATCH. session.savewith anotherversionanswersINVALID_ARGUMENT.
Only the Genesis developer changes these numbers. A change that alters a message, an operation, a locator or read key, or an error code's meaning in a way an existing client or page agent would misread needs a new number, and this file changes with it.