Skip to content

Latest commit

 

History

History
676 lines (529 loc) · 56.2 KB

protocol.md

File metadata and controls

676 lines (529 loc) · 56.2 KB

Protocol

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.

Transport

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.

Handshake

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.

Requests, responses and events

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.

Foreground methods

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.storage in the manifest, else CONFIGURATION_REQUIRED. In storage.commit, checks are { collection, key, expectedRevision } (null expects no document), puts are { collection, key, value } and deletes are { collection, key }. A failed check is CONFLICT; a value over limits.storedDocumentMaxBytes is DOCUMENT_TOO_LARGE.
  • Storage and service requests answer QUOTA_EXCEEDED while limits.pendingRequestsMax of them are open.
  • The context.* methods answer NOT_FOUND for an id that is not a context of the manifest.
  • context.navigate needs an http or https URL with a host and no user name or password, else INVALID_ARGUMENT. A URL outside the manifest's origins loads too, and shows as the website, because no page agent runs there.
  • After a back event, back.handled with handled: false steps back in the revealed context's history, or leaves the applet when there is none. With no answer within limits.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.

Context methods

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.result and page.progress about a call that is not this document's, or that has already ended, are accepted and ignored. page.result with ok: false and no error ends the call with INVALID_ARGUMENT. The page agent checks a value before it answers: a value that is not JSON data (a BigInt, a cycle) answers INVALID_ARGUMENT, and one over limits.pageMaxBytes answers PAGE_TOO_LARGE.
  • page.progress marks the call dispatched, and navigating when that is the state. The host forwards it to the foreground as the event page.progress.
  • page.emit answers PAGE_TOO_LARGE for a snapshot whose data is over limits.pageMaxBytes, and PATCH_TOO_LARGE for a patch over limits.patchMaxBytes or with more than limits.patchRecordsMax upserts. The host adds context and generation and forwards it as the event page.emit.
  • page.input carries 1 to 64 real input events for one of the document's open calls (see Trusted input).

Events

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 operations

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.

Action results

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.

Steps

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.

Commands

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.

Call lifecycle

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:

  1. The page answers with page.result. The host answers the foreground's request with the value or the error.
  2. 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.
  3. 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).
  4. 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.

Watches

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 } } } } }

Streams and views

  • seq starts at 1 for each watch and increases by one per message. A patch applies only when its seq is one more than the last applied message of the same view. On a gap, the client asks for watch.resync.
  • view is { generation, n, url }. n counts 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 seq it has already applied.

States

open ─▶ snapshot ─▶ patch* ─▶ snapshot (new view, resync, refused patch)
  │                      │
  └── URL fails `when` ──┴─▶ status { idle: true } ─▶ (URL matches again) ─▶ snapshot
  • A watch with when reads only while the page URL matches one of its guards. When the URL stops matching, it sends one status { idle: true } and stops reading. When it matches again, the next message is a snapshot.
  • status is a PageStatus: loading, ready, error, auth or unsupported. The page agent sends only ready and error; the other values are for clients.
  • A read that throws makes the watch error: the snapshot has status: "error" and error. The next successful read sends status: "ready" in a snapshot.
  • A read whose value is not JSON data (a BigInt, a cycle) fails watch.open with INVALID_ARGUMENT. When that happens later, the watch reports status: "error" with INVALID_ARGUMENT.
  • Changes are batched: the agent sends a batch after limits.publishQuietMs without changes, and at least every limits.publishMaxDelayMs.
  • The agent splits a change into patches of at most limits.patchRecordsMax upserts and limits.patchMaxBytes. Only the last patch carries remove, order and complete, 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.pageMaxBytes drops a quarter of a virtualized list's records farthest from those on screen until it fits. Otherwise the watch reports status: "error" with PAGE_TOO_LARGE.
  • truncated: true means the list has more items than limit (or the agent's maximum, five times limits.patchRecordsMax) allows.
  • In a virtualized list, records whose elements left the DOM stay in the view's list with present: false added 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.
  • complete is 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.

Locators

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, text or record. name needs role; exact needs text. Unknown keys are invalid.
  • within, has and frame nest at most 4 levels.
  • A css selector, and a read field's at, may not test the value attribute, in any case, with a namespace, or written with CSS escapes. Such a selector is INVALID_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. has and strict apply before nth.
  • An invalid locator is INVALID_ARGUMENT with the path of the bad field, such as target.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

Read specifications

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 key reads one value: no all or fields, and take is text, ownText, url, value, number or { attr }. An empty key is INVALID_ARGUMENT. Two items with one key are CONFLICT.
  • limit is a positive integer. The agent caps every list at five times limits.patchRecordsMax; past it the value has truncated: 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 }

URL guards

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.

Protected fields

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.

Trusted input

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 }] } }
  • x and y are CSS pixels of the visual viewport at scale 1: the element's client position minus visualViewport.offsetLeft and offsetTop, times visualViewport.scale. The shell multiplies them by the display density.
  • Named keys are Enter, Tab, Escape, Backspace, Delete, " " (space), ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp and PageDown; any other key is one character. Modifiers are Shift, Control, Alt and Meta. Control and Meta work 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 (Control or Meta with a one-character key, or Shift+Delete). That answers INPUT_UNAVAILABLE.
  • One page.input types at most 2000 characters across its text events; more is INVALID_ARGUMENT. The page agent refuses a trusted type of a longer text the same way, before it sends anything.
  • page.input answers INPUT_UNAVAILABLE when limits.trustedInput is 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 answers CONTEXT_REPLACED when another document has already started loading in the context, NOT_FOUND when callId is not an open call of the asking document, and DEADLINE when the call's budget runs out first.
  • A trusted click is one touch tap: gesture other than tap, or count other than 1, is INVALID_ARGUMENT. Any other operation with input: "trusted" is INVALID_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 window or handoff grant (see Grants): it lets one such request through.

Website dialogs

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 unknown with DEADLINE.

User actions

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: accept holds up to 16 MIME types (image/*) or .ext suffixes; anything else is INVALID_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. An id is 32 hex characters and stays valid until files.release, until the applet is retired or its window closes, or for 30 minutes. The foreground shows a picked file at https://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 an id in storage, because it means nothing after it expires.
  • downloads.save: url is https, or a data: URL up to 2 MiB, with no user name or password, else INVALID_ARGUMENT. The https download carries the cookies and User-Agent of context (NOT_FOUND when it is not a running context of the manifest). filename is 1 to 128 characters without /. The file goes to Downloads.
  • share.open needs at least one field. title is at most 200 characters, text 4000, and url is http or https. The answer means the share sheet showed, not that the user shared.
  • links.openExternal takes mailto, tel, sms, smsto, geo, intent and https. An https link 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 is NOT_FOUND.
  • notifications.enable needs capabilities.notifications, else CONFIGURATION_REQUIRED. It turns on the applet's notifications as the Applet info switch does, asking Android first on Android 13 and later. enabled is false when the user or Android refused.
  • page.share is the page agent's navigator.share for a website that has none in the WebView. It takes the same fields and limits as share.open. It works only while the context is revealed, and only when active is true, because the user tapped the website itself: otherwise it answers USER_ACTION_REQUIRED. A tap on the applet UI does not count, and it needs limits.userActions.
  • page.files carries picked files to the page for the page agent's attachFiles operation. 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.userActions is true when the host takes these methods and attachFiles. It is absent in an older Genesis.

Grants

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 } }
  • grant is fullscreen, download, window, handoff or location. context.grant is a user action: without a fresh tap on the applet UI it answers USER_ACTION_REQUIRED and grants nothing (see User actions). An unknown id is NOT_FOUND.
  • A revealed context needs no grant, because the user taps the website itself: the answer is { granted: true, expiresInMs: 0 } at once, and no context.grantEnded follows.
  • 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"), then click with input: "trusted").
  • fullscreen shows the page's fullscreen view over everything; the context stays hidden, and Back or the page's own exit returns to the applet. download saves an http, https or data: download to Downloads, and a blob: one on a declared origin, where the page agent reads it. A blob: or data: file takes the download name of the link the user clicked, when the page agent saw the click. window opens the page's popup in a sheet over the applet; closing it returns to the applet. handoff lets one link open in another app. location shows Genesis's location prompt for the page's origin over the applet.
  • A window or handoff grant 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.grants is true when the host takes context.grant. It is absent in an older Genesis.

Activity

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": {} }
  • level is running, awake or null. running lasts until the foreground changes it. awake is full speed for at most 30 seconds, then the hold counts as running. null releases the hold. An unknown id is NOT_FOUND.
  • One hold per context: each context.hold replaces 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.call or 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.activity is true when the host rests covered pages and takes context.hold. It is absent in an older Genesis, where a covered page always runs and context.hold answers UNKNOWN_METHOD.

Debug log

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.result with 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.log is accepted and ignored.

Error codes

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.

Limits

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.

Versions

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 hello with another protocol gets refused with PROTOCOL_MISMATCH.
  • The SDK's connect rejects with PROTOCOL_MISMATCH when compat.protocol or compat.sessionState differs from the SDK's own.
  • A page agent whose adapterApi differs from compat.adapterApi answers every call with PROTOCOL_MISMATCH.
  • session.save with another version answers INVALID_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.