Android form factors: common behaviour¶
Part of Android form factors.
- Matching. The vocabulary is
phone | tablet | foldable | tv | watch | automotive | xr-headset | xr-glasses | unknown(src/models/DeviceMatchCriteria.ts). Bindingfamilytakes the same values exceptunknown(BINDING_DEVICE_FAMILIES,src/utils/provisionDeviceSpecSchemas.ts).formFactorFrom(src/models/formFactor.ts) classifiestv,watchandautomotivefrom the system-image tag first (android-tv,android-wear,android-automotive), then the avdmanager profile id, then geometry. Geometry detects fold/flip by profile name and treats a diagonal >= 7in as a tablet, else a phone, so a TV never matches as a tablet. iOS accepts onlyphoneandtablet. ThestartDeviceformFactor, the broker bindingdeviceFamilyand the device description accept these values;getAndroidhas noformFactorinput. AstartDevicecall withcreateIfMissingcreatestv,watchandautomotiveAVDs. - Watch. A
watchrequest picks only installedandroid-wear-signed,android-wearandandroid-wear-cnimages, in that order, behind API level and host ABI. It creates the AVD withwearos_small_round, orwearos_squarewhenrequires.screenRoundisfalse. With no Wear image installed it fails naming thesdkmanagercommand. Therequires.screenRoundfield also restricts matching, stopped or booted, to a Wear profile whose id names that shape (wearProfileScreenRound), so a square request never reuses a round watch. Creation refuses it outside an Androidwatchrequest. A physical watch has no profile id, so it never satisfiesrequires.screenRound; physical watches stay out of scope. - Automotive. An
automotiverequest picks only installedandroid-automotive-playstore/android-automotiveimages (Play first, behind API level and host ABI, with the CtrlProxy minSdk floor). It creates the AVD withautomotive_1024p_landscape, and with no car image installed it fails with the exactsdkmanagercommand. A repeated request reuses the AVD because those tags classify it asautomotive.requires.vehicle.motion: "supported"restricts matching and creation to non-Playandroid-automotiveimages (isMotionCapableAutomotiveTag). Play car images areuserbuilds whose car service refuses driving-state injection. A booted automotive device’s traits carryvehicle, derived fromro.build.type(thenro.debuggable). Both areunsupportedunlessro.kernel.qemumarks an emulator. AutoMobile reads them only whenro.build.characteristicsannouncesautomotive, with no probe that changes car state. The tag and profile names are still unconfirmed on real images. - Android XR.
xr-headsetclassifies thegoogle-xr,android-xr-v3-playstoreandandroid-xr-preview-playstoretags andxr_headset*profiles.xr-glassesclassifies theai-glassestag andxr_glasses_*/ai_glasses_*profiles. A request for either picks only its own images in that order (behind API level and host ABI). It creates the AVD withxr_headset_deviceorai_glasses_device(the profileavdmanager list devicetagsai-glasses). With none installed it fails naming thesdkmanagerpackage and--channel=3.requires.playStoreon a headset picks only the Play variants; glasses have no known Play image. - XR glasses input. Booted-device traits read
xr(headset) orglassesinro.build.characteristics. The 450×450 ai-glasses emulator reportsnosdcard,watch, soglassesInputalso uses profile/runtime form-factor identity. It injects DPAD_CENTER for tap, DOWN/UP for vertical forward/back and RIGHT/LEFT for horizontal forward/back without read-back. Long press and two-finger gestures stay unsupported.touchnavigationswipes can emit only motion after idle,touchpadmotion does not move focus, and key holds produce no long click. Raw touchpad injection requires adb root, and unpaired glasses system UI swallows it. - XR headset taps. Runtime XR behaviour (
tapOnandtapAnynode clicks, no ghost-tap retry) does not use that form factor: it asks the shared predicate described below. Headset home-space input uses screenshot pixels fortapAt, including normalized, percent and image inputs. Android input and task bounds use display pixels. The API 34 google-xr headset’s 2560×2558 display produces a 2558×2558 composed-eye screenshot. At the default pose the panel projection isshot = (shotWidth/2, 0.552*shotHeight) + (61/64)*(display - taskCentre), with task centre derived from its bounds. ThetapAttool inverts this projection for task-aligned app panels before dispatch and reports the selected task and display point inxrPanel. - XR headset swipes. When the foreground app has an application window extending outside its task bounds, with or without a task-aligned host window, its embedded SpatialPanel cannot receive display touches:
tapAtrefuses display input. TheswipeOntool (including explicit-display and scroll-search routes) uses accessibility scroll-forward/backward on the supplied scrollable container. Without one, it uses the largest visible scroll-action node in a foreground application window. Unique captured exact bounds plus the requested action verify a target without a native selector. CtrlProxy rechecks uniqueness, bounds, visibility and action availability. Refusal or an unacknowledged dispatch never falls back to a display gesture. - XR bounds capabilities. Bounds-only scrolls and checkable click hints require
node_selector_bounds_v2; plain bounds clicks retain the v1 capability requirement. A checkable hint verifiesisCheckable, independently of the changing toggle state. Without a scrollable node, swipes refuse with guidance to usetapOn/tapAnyor keyboard focus keys. XR automatic scroll targeting excludes scrollables explicitly markedvisible-to-user: false, including hidden system UI lists, even for ordinary task-aligned panels. It refuses points outside the projected panel, including XR system UI. The tool-by-tool result on the headset emulator is in Android XR headset: tool baseline. - XR detection. XR detection is one shared predicate (
isAndroidXr,src/utils/android-cmdline-tools/androidXrDevice.ts) fortapOn,tapAny,tapAt,swipeOn(screen swipes, the scroll-search screen fallback and the default-pose check) andsendKeysrouting. It reads theandroid.software.xr.api.spatialsystem feature (the signal CtrlProxy uses) once per device and caches it for five minutes. Only without a device handle, or when the probe fails, does it fall back, uncached, to thexr-*form factor or XR System UI task/activity names in the observation back stack. That back-stack check is private to the predicate; panel geometry only receives the predicate’s answer. - XR hidden System UI taps. On XR,
tapAnyexcludes System UI nodes whose extractorvisible-to-userflag is false.tapOnpermits such a node only for a tap, and only when the node itself advertisesclick. Its stable selector (resource ID, test tag or unique ID) must also identify one captured source at the selected bounds in a complete hierarchy. Activation uses the XR accessibility node-click path withrequest_action.allowInvisible: trueonly for the hidden target itself, never an ancestor. Hidden nodes never use the bounds-only fallback. This additive flag defaults to false and has no effect on non-click actions. Selector clicks still require one match at the exact expected bounds with positive width and height. - XR hidden click confirmation. CtrlProxy accepting ACTION_CLICK on such a hidden node does not prove the drawn control activated. Some hidden nodes, such as the recents-strip
launcher_button, accept the click with no effect. So when the post-tap observation shows the screen unchanged,tapOnfails instead of succeeding. The failure names any approved hidden System UI control whose label shares a word with the target’s resource ID as thetextselector to use. Other hidden System UI matches still refuse with guidance to observe the visible control or use screenshot coordinates withtapAt. Ownership comes from the node resource ID or its window package name. - XR
tapAnywindows. UnconstrainedtapAnystarts in the captured foreground app window when available. Every AndroidtapAnyselection asks that predicate, whether or not the capture has hidden System UI. Unconstrained XRtapAnykeeps the capture package’s windows plus other packages’ application windows that overlap one of them (a permission dialog). A separate panel beside the app therefore cannot win. A window with no package name counts as another package, sotapAnydrops a package-less IME window. XR candidates prefer the topmost window, then complete sibling rows and top/left/capture order. - XR tap owners. A leaf container with no clickable descendant uses its nearest clickable owner within three ancestors. The search stops at a nested selector’s outer container, which may itself be the owner. It also stops before window roots, full-window ancestors, and ancestors containing other tap-actionable descendants outside the leaf-to-owner chain. It stops too before ancestors exceeding 25% of the area of the leaf’s owning window root (or viewport area when that root has no bounds). Hidden nodes do not count as covering application windows for taps or observation occlusion. Window covers exclude XR SystemUI home and caption windows; same-app and other-app dialogs still cover rows.
- XR observe. When the active-window app (or current back-stack task if absent) has any application window in the capture, observe excludes SystemUI nodes explicitly marked
visible-to-user: falsefrom elements, visible texts and the skeleton. It preserves visible captions and the raw action hierarchy; home-space output is unchanged. On the default XR display, observe reconciles hierarchy dimensions withwm size(override size first), rotated to match the capture. It does this because IME process bounds can shrink the reported hierarchy size. Each observe re-readswm size, so an override set mid-instance (displayConfigor raw adb) reaches the next observe. Recaptures and tap refreshes within it reuse that read, keyed by device and rotation parity, and a fresh read drops the other parity’s entry. - XR node clicks.
tapOnandtapAnyclick the accessibility node (or refuse) instead of sending panel-space coordinates. Compose owners without native selectors use unique captured bounds plus identity hints from their own fields or a hoisted descendant label. The match links merged and window roots before checking uniqueness. They skip the ghost-tap retry, because an unchanged hierarchy does not prove a node click missed and a second click would toggle a switch back. - XR unanswered clicks. A node click that CtrlProxy received but never answered is not a refusal. This happens when its reply outlives the client request timeout, because CtrlProxy replies only after the post-click settle and extraction.
tapOndecides such a click from the post-tap observation. It succeeds with a warning when the screen changed, and otherwise fails as unconfirmed with guidance to observe before retrying.tapAnyfails it as unconfirmed. Only an explicit CtrlProxy refusal, or a click that was never sent, returns the panel-coordinate error. - XR panel bounds. The first freeform app task in top-first order supplies the panel bounds, skipping System UI and the environment task. Screen swipes (including the scroll-search screen fallback) use these display bounds, already below the status bar. A full-display swipe can start below the panel, focus the System UI visibility barrier and dismiss the panel. AutoMobile therefore refuses missing-panel and edge gestures. This measured projection supports home space at the default headset pose only; it does not infer moved-panel poses or immersive layouts. This mapping does not convert
observenode bounds. - XR bounds spaces. For an embedded SpatialPanel,
xrPanelSpaceidentifies the application window and its bounds. Elements and skeleton/context rows declareboundsSpace: "panel"for that panel window orboundsSpace: "window"for other owning windows. These spaces are not comparable across windows or usable as screenshot coordinates. Observe omits both fields without an identified embedded SpatialPanel or on non-XR observations. Internal callers that tap a hierarchy element centre (exploration,setUIState’s bounds-centre fallback) pass the internalpointSpace: "native"option, which skips the panel mapping. The publictapAttool always uses screenshot space. XR glasses are outside this coordinate model. - XR text input. On the headset emulator the default keyboard (Gboard) stays the active editor connection, and the observed hierarchy has no readable focused field. So on an XR device (the shared predicate above), an Auto
sendKeystyperoutes toa11ywhen a keyboard other than the AutoMobile IME is shown with no readable focused editable field. The command’swarningsays so. Phones always keep the AutoMobile IME as the Auto default, even with Gboard shown and no readable focus (a WebView or Compose field). - Provisioning.
provisionDevicetakesruntimeas a system-image package id.parseAndroidSystemImageRuntimeaccepts any tag between API level and ABI (onlygoogle_apis_playstoreis special-cased). Default creation (pickAndroidSystemImage,src/devices/deviceProvisioning.ts) picks an image family from the requested form factor (androidImageFamilyFor). It picks handheld tags for phone, tablet, foldable or none (#14900). Fortvit picks only the TV tags, rankedandroid-tv,google-tv,google-tv-ps16kbehind API level and host ABI. Theandroid-tvtag leads because Play Store builds usually refuseadb root; this ordering rationale concerns Play Store images only and does not guarantee root onandroid-tv. The verifiedandroid-tvuser build also refusesadb root. A TV AVD gets thetv_1080pprofile. The tag lists and default profiles live once insrc/models/formFactor.tsand the broker’s family defaults read them. With no TV image in range the error names thesdkmanagercommand; nothing is downloaded. - CtrlProxy.
minSdk24 (android/gradle/libs.versions.toml) is not a blocker. The manifest declares no<uses-feature>and only aLAUNCHERcategory (noLEANBACK_LAUNCHER). The accessibility config requests window content, interactive windows and gesture dispatch. - Input.
sendKeyssupports arrows (KEYCODE_DPAD_*), enter, tab, escape, backspace, delete (INPUT_KEY_CODE_MAP,src/features/action/InputKey.ts). There is no D-pad centre, menu or media key.pressButtonsends back/home/recent as global actions with ADB fallback, plus volume/power via ADB. - Focus.
observereturnsfocusedElement(ActiveWindowAttribution.ts,HierarchyFocus.ts) from thefocusedproperty; TalkBack focus is separate (accessibility-focused). observereportsisScreenRoundand, when identifiable,surfaceonly forwatchdevices.surfacerequires an active window and hierarchy. Non-Wear-SystemUI apps areapp, and Wear SystemUI’sexperiences.globallauncher.*activities arelauncher. Itsmainui.activity.SysUiActivityistilewhen the hierarchy containscom.google.android.clockwork.sysui:id/carousel_tile_container. Otherwise it iswatchfacewhen the hierarchy containswatch_face_fallthroughorcom.google.android.clockwork.sysui:id/watchface_overlay. Other captures omitsurface: SystemUI hosts the watch face, tile and notification tray, so its package and activity alone cannot distinguish them.ambientchanges power state and reads the watch face’sinAmbientback fromdumpsys wear_service.