Prototype spec: device status, connectivity and window controls¶
Part of the agent-authored prototype specification.
Device status (#14316). Three state-only modules expose read-only device status under
/platform/<module>/<key>; a spec lists the module in requires.platform and reads keys with the
{platform} forms. Each module has a <module>.changed event whose {event} data carries the new
values, delivered like connectivity.changed. The state updates at once, and the event fires once
the state has been quiet for 500 ms. A flap that settles back on the last delivered values is not an
event. Unknown keys and events fail validation with a
path. Android and iOS provide these read-only modules with lazy system observers and debounced change
events; Android thermal state is absent below API 29. The iOS agent and ProtoViewer register all three
without permissions. Their shared registry stops observers after the final presentation releases it.
The host mirrors each delivered <module>.changed as platformStatus.<module> in prototype status
and inspect: values, the event’s device timestamp, the host receivedAt, and simulated for an
injected event. An agent can then assert the device’s last values without observing. A replayed event
older than the mirrored reading on the device clock does not replace it. Data with a key or value outside the module’s
state table, or cut by the emit budget, is not mirrored and leaves the previous reading.
| Module (capability) | Keys |
|---|---|
battery (prototype_platform_battery_v1) |
level 0-100, absent when unknown; state charging, full, unplugged or unknown |
power (prototype_platform_power_v1) |
saver boolean; thermal nominal, fair, serious or critical |
audio (prototype_platform_audio_v1) |
volume 0-100 (media stream); muted boolean; route speaker, wired, bluetooth, usb, airplay, cast or other; ringer normal, vibrate or silent (Android only) |
Connectivity (#14273). The connectivity module (prototype_platform_connectivity_v1) follows the
same shape:
/platform/connectivity/online,meteredandconstrainedare booleans.transportiswifi,cellular,ethernet,vpn,otherornone.constrainedis iOS Low Data Mode or Android Data Saver.connectivity.changedis debounced to one delivery per 500 ms.
CtrlProxy registers the Android runtime and advertises the capability; the embedded renderer leaves the
module to its host app. It reads the default network with registerDefaultNetworkCallback, registered on
the first state read so an idle overlay holds no callback, and needs only ACCESS_NETWORK_STATE. The
runtime seeds the state from the active network before the callback registers. So the callback’s first
delivery is not a transition, and a prototype does not see connectivity.changed just for starting.
On Android:
onlineisNET_CAPABILITY_VALIDATED, so a captive or unvalidated Wi-Fi isonline: falsewithtransport: "wifi".- With no default network the state is offline on
nonewithmeteredandconstrainedfalse. transporttakes the first ofvpn,wifi,cellular,ethernetthat the network carries, so a VPN reportsvpnover its underlying transport. Anything else isother.meteredis the absence ofNET_CAPABILITY_NOT_METERED.constrainedis Data Saver on (getRestrictBackgroundStatusnotDISABLED) on a metered network, because Data Saver restricts only metered networks.
State updates at once; the event fires once the state has been quiet for the debounce, and a flap that settles back on the last delivered state is not an event.
On iOS the agent and Viewer registries run NWPathMonitor (no entitlement), started on the module’s
first read:
onlineis a satisfied path with an interface.transportis the first of Wi-Fi, cellular and wired Ethernet the path uses (a VPN’s utun reportsother).meteredisisExpensiveandconstrainedis Low Data Mode.
The first path after start is the baseline, not a change. Every path that changes the state refreshes
/platform at once through a state-only refresh signal the driver applies without running a handler.
So a prototype shown before the first path still sees it; only connectivity.changed waits for the
debounce. The offline simulation override is not built.
The reading mappings are normative. prototypeDeviceStatusReference.ts is the reference the device status
runtimes copy, replayed from test/fixtures/prototype-device-status/:
- Thermal: Android
PowerManager.THERMAL_STATUS_*0 isnominal, 1-2fair, 3seriousand 4-6critical; iOSProcessInfo.ThermalStatemaps one to one. - Battery
state: AndroidBATTERY_STATUS_CHARGINGischarging,FULLisfull,DISCHARGINGandNOT_CHARGINGareunplugged, anything elseunknown; iOSUIDevice.BatteryStatemaps one to one. - Battery
leveland audiovolumeare whole percents (Android level over scale and stream index over its maximum; iOSbatteryLevelandoutputVolume). An unknown reading, such as the Simulator’s battery level of -1, leaves the key absent. iOS omitsmuted: an inactive host audio session can report zerooutputVolume, so volume alone does not establish mute status. Observing audio does not activate or reconfigure the host session. ringeris AndroidAudioManager.RINGER_MODE_*: silent, vibrate or normal.
The simulate override is normative too. prototypeDeviceStatusOverride.ts is the reference for
simulate state seeding (#14300) on these modules, replayed from the same directory’s override-*
fixtures:
- In
fakeplatform mode, the shown values freeze at the last reading. Later real readings are held back, and a seed merges into the shown values; anullseed value removes the key. - Switching back to
realdrops the override and shows the latest reading at once. Each change of the shown values is debounced into<module>.changedlike a real reading. - A seed is refused with its input path in
realmode. It is also refused for a key outside the state table, a key the platform does not report (ringeron iOS) or a value its rule refuses.
The simulate state action that drives this on a device is not built.
Biometric prompt (#14328). The biometric module (prototype_platform_biometric_v1) has one call,
biometric.authenticate with title (required, 1-64 characters), subtitle (optional, 1-128) and
allowDeviceCredential (optional boolean), and one event, biometric.attemptFailed, for a rejected
attempt while the prompt stays up. It has no /platform state and needs no requires.permissions
entry. Android hosts declare the normal USE_BIOMETRIC manifest permission for framework prompts. The
call proves presence only and returns no biometric data. Failures use the typed codes: cancelled, and
unavailable for a locked-out, unenrolled or hardware-less device. See
Android biometric runtime support
for host availability and error reasons. The iOS agent and ProtoViewer also register the module. Face ID
requires the host’s NSFaceIDUsageDescription; a missing key returns unavailable with reason
missing_usage_description. A saved iOS app keeps that key only when its spec lists biometric in
requires.platform. Allowing device credentials selects the system passcode fallback, including
on a device without enrolled biometrics.
Window controls (#14320). Four optional root window fields need
prototype_platform_window_controls_v1. They are not a platform module, so they need no
requires.platform entry:
keepScreenOn(boolean) keeps the screen awake.brightness(whole 0-100, orsystem) sets the prototype window’s brightness.orientation(portrait,landscapeorunlocked) requests an orientation.statusBar(light,darkorauto) picks the status bar content style.
Each applies only while the prototype is shown and is restored on dismiss; none writes a system
setting. Two controls are best effort: orientation over an overlay, and statusBar where the
runtime does not own the status bar (an Android overlay, the injected iOS agent). The iOS Simulator
ignores brightness.
CtrlProxy advertises the capability and applies
FLAG_KEEP_SCREEN_ON, window-local screenBrightness (system uses BRIGHTNESS_OVERRIDE_NONE) and
screenOrientation; unlocked and omission use SCREEN_ORIENTATION_UNSPECIFIED. Replacement rebuilds
these values from the new spec; removal releases them, and an animated exit resets them before waiting
for removal. Failed replacements restore the previous params. Inspect entries add orientation for the
requested orientation and statusBar: "unsupported" for an authored status bar style. Hierarchy window
entries add the same values as prototypeOrientation and prototypeStatusBar; omitted controls omit
these fields. Orientation reports a request, not proof that the device rotated. Embedded Android does
not advertise these overlay controls.
Prototype layout direction. Optional window.layoutDirection: "ltr" | "rtl" requires
prototype_layout_direction_v1. Omission inherits the host direction. The iOS renderer overrides
SwiftUI layout direction and root UIKit semantics for the prototype only, without changing locale.
Android does not advertise this capability, so the host refuses specs that set it before showing them.
Keyboard dismiss (#14320). The {type: "hideKeyboard"} action, which takes no fields, needs
prototype_hide_keyboard_v1. It is a plain UI action like dismiss, not a platform module, and touches only the
prototype’s own window: it hides the soft keyboard and clears text focus (Android WindowInsetsControllerCompat
hide(ime()); iOS endEditing(true)). CtrlProxy advertises the capability and dispatches the action to
the owning surface’s host on main, hiding the IME before clearing its view focus. Without a shown
window it does nothing; navigation focusability is retained. The embedded Android renderer does not
advertise it.
Settings deep links (#14320). The settings module (prototype_platform_settings_v1) has one call,
settings.open with page one of app, notifications, location, wifi, bluetooth or display. The
list is closed and the target package is always the prototype’s own runtime package; a spec cannot name
another. The module has no events or /platform state. Pages other than app and notifications are
Android only.
The spec validators are platform-neutral, so the host’s iOS show preflight refuses a literal
Android-only page with the action’s path; a bound page is left to the runtime. The Kotlin validator
needs no such check because it runs only on Android. The Swift agent validator has none yet because
the iOS agent does not advertise the module, which the host’s capability gate refuses.
CtrlProxy registers the module on Android and opens each page for its own package with
FLAG_ACTIVITY_NEW_TASK. Below API 26 notifications opens the app details page, and below API 29 wifi opens
the full Wi-Fi screen instead of the panel; both report outcome: "fallback". The result is {outcome, page,
handler?}, and no resolving Settings activity is the typed error unavailable. The embedded renderer and iOS do
not advertise it yet.
Contact and calendar pickers (#14318). Two modules reach the system pickers, which return only what the user picks and need no declared permission:
contacts(prototype_platform_contacts_v1) hascontacts.pickwith an optionalfieldslist (one to three unique values ofname,phone,email) and an optionalmultipleboolean. It issensitivebecause the result is personal data.calendar(prototype_platform_calendar_v1) hascalendar.insertwithtitle(required, 1-256 characters),startandend(required, whole milliseconds since the epoch),allDay,location(1-256) andnotes(1-2048).
Neither module has events or /platform state, and a back-out is the typed error
cancelled.
No production runtime advertises either module yet.