Prototype spec: dead taps, formatters, namespaces, glass and disposable apps¶
Part of the agent-authored prototype specification.
Dead taps (window.deadTaps, prototype_dead_tap_v1)¶
window.deadTaps: true enables emit events named prototype_dead_tap. Android
advertises prototype_dead_tap_v1, a host preflight capability, not a
strict-spec gate.
A root Final-pass observer reports single-pointer down/up gestures left unconsumed by descendants, with movement below touch slop. Scrolling, pager drags, multitouch and taps outside the content window never report. Interactive controls and dismissing scrims consume their gestures. Gesture-only nodes with nonempty long-press or double-tap actions mark their down handled without consuming it, preserving ancestor clicks. A single tap on one counts as handled even if its hold or double-tap action does not fire. Passive text, boxes, images and spacers stay dead.
Payloads contain only stack, screen, x and y; coordinates are window-local
dp rounded to one decimal. The deepest stack supplies its id and top screen; ties pick the lexicographically lowest stack id. Both are null
without stacks. The event uses normal sequence allocation, state, pages and
stacks, never typed text. Authored emits cannot use the
reserved prototype_ prefix. Disabling it or closing the runtime stops reports.
Value formatters (#14227)¶
Optional derive maps up to 32 STATE_KEY names to strict
{of, format, locale?, timeZone?} entries. of contains exactly one of
{data: "/pointer"} (relative to data), {state: "key"}, or
{value: number|string}. Every text field supporting {data:/pointer} also
accepts {derived:name}; undeclared names are validation errors, unused entries
are allowed, and malformed braces remain literal. Devices render them in
text node text, contentDescription, rich-text spans, button/FAB labels, topAppBar
title, badge text, dialog title/text and snackbar text. Other text-kind fields
(request url/headers/body, check messages, select/segmented/menu/searchBar labels)
validate unknown names but display the token literally on devices.
repeat.derive maps at most 8 names to the same entry shape with of restricted
to {item: "field"} or {value: number|string}. It projects strings onto each
original row for {item.createdAtText} (with the repeat’s actual alias).
Names cannot collide with any original item field, including non-scalar data
fields. Derived entries do not read other derived entries. Host validation checks projected
field references without evaluating device-local strings; the renderer defers value-dependent checks
on derived repeat keys and emit names. Missing source fields are allowed and format as empty strings.
format contains exactly one of these keys, each containing a strict object:
| Kind | Options and defaults | Input |
|---|---|---|
| number | minFraction?, maxFraction? (integers 0..20), grouping=true | finite number |
| compact | style=short (short or long) | finite number |
| currency | code required, three uppercase ISO-4217 letters | finite number |
| percent | minFraction?, maxFraction? (0..20) | ratio, so 0.256 is 25.6% with maxFraction=1 |
| date | style=medium (short, medium, long) | epoch milliseconds or ISO string |
| time | style=short (short, medium, long) | epoch milliseconds or ISO string |
| relative | style=long (narrow, short, long) | epoch milliseconds or ISO string |
minFraction must not exceed maxFraction when both are supplied. Omitted numeric fraction options use Intl/CLDR defaults (currency respects minor units, including zero for JPY). Number grouping true/default respects the locale’s minimum grouping digits; false disables grouping. Compact, currency, and percent do too. Locale defaults to the device locale; timeZone defaults to the device zone. Overrides accept a simple BCP 47 tag of at most 35 characters and an IANA zone identifier of at most 128 characters. Shape validation does not prove that the current engine supports a locale or zone.
Epoch milliseconds must be finite integers within the Date range. Strings are
YYYY-MM-DD (midnight UTC) or YYYY-MM-DDTHH:mm:ss[.fraction]Z / a signed
hh:mm offset. Hours must be 00–23 and minutes/seconds 00–59; hour 24 and
leap second 60 are rejected. Invalid calendar dates, unzoned date-times, wrong types and
missing pointers display as the empty string. The host’s pure formatter returns
undefined for invalid inputs; its resolver converts that to an empty string.
Relative formatting takes an injected nowMs snapshot; it never reads the real clock. Choose the largest elapsed threshold not exceeding abs(input-nowMs): year=365 days, month=30 days, day=24 hours, hour=60 minutes, minute=60 seconds, second=1000 ms. Truncate toward zero. Under one second uses localized “now”. There are no weeks or calendar-month arithmetic. Callers resolve entry locale and zone overrides before formatting, and keep the clock snapshot fixed when reproducible output is required.
prototype_format_v1 gates either derive map, including empty maps, before show
or the complete patch result. Renderers advertise it only once implemented. Shared derive/formatters.json cases define parity: normalize
U+202F and U+00A0 to plain space before comparisons. Exact cases pin supported
English output; structural cases allow documented CLDR differences in foreign
currency symbols, narrow relative abbreviations, zero-relative wording and
non-English data. Add engine overrides only for a measured platform
difference; the fixture note records the divergence policy and unit thresholds.
dateTime, duration, plural and fileSize are not format kinds (invalid). No dependencies are needed: the host uses Intl.NumberFormat,
Intl.DateTimeFormat and Intl.RelativeTimeFormat.
Platform namespaces (#15257)¶
Prefer portable fields, portable theme tokens, then theme.design; reserve ios/android
for native semantics. Each closed contract field has a why. Both renderers advertise
prototype_platform_namespace_v1 (iOS 17+). Foreign blocks are accepted and ignored with
paths in platformNotes; unknown fields are rejected on either platform. Window/theme
namespace blocks have no applicable node and are reported as ignored. The four node glass fields
require only prototype_glass_v1 on iOS; mixing any other iOS key requires
prototype_platform_namespace_v1 as well. Android ignores foreign glass fields
with their individual paths in platformNotes.
Android indication controls node clickable feedback (ripple or none); motion-off
still disables feedback. Stack predictiveBack.style preserves the normal pop for
default, uses horizontal movement and fade for crossActivity within the prototype
activity, and snaps without predictive scrubbing for none. Reduced motion still wins.
iOS buttonStyle applies .glass/.glassProminent on iOS 26+, using bordered buttons
below 26 with a substituted note. hover applies lift/highlight on iOS 17+ and is render-only.
The renderer custom-draws its tab bars, app bars and sheets to retain per-item identifiers, and
reports tab.role, bottomAccessory, navigationTitle and sheet.sizing as ignored. The
bottomAccessory field is node-only and structurally validated; its descendants provide no targets,
references or capabilities on either renderer. iOS ignores all Android fields.
Glass surfaces and scroll edges¶
style.surface is a closed enum containing only "glass". Optional strict
style.glass: {variant?, tint?, interactive?} takes regular|clear (default
regular), an existing hex/role/light-dark colour slot, and a boolean (default
false). The glass field without surface: "glass" in the same style is invalid, including
styleWhen entries; conditional glass options must repeat the surface. The cornerRadius field chooses the
shape; omission uses a capsule. Base and conditional styles require
prototype_glass_v1; bundles must list every required capability.
scroll.edgeEffect: "soft"|"hard"|"none" requires
prototype_scroll_edge_effect_v1. iOS 26 uses the native scroll edge style;
iOS 17–25 reuse the scrollability-aware fadeEdges mask, 24 dp for soft and
8 dp for hard. Authored fadeEdges lengths override those defaults; none
disables only the default fallback mask or native effect. Explicit fadeEdges
remain applied on every supported iOS version. Android accepts the contract but does not advertise or
render edgeEffect.
In ios, glassGroup: {spacing} accepts finite 0–200 dp on column, row, box,
flow, grid, list and listItem containers. Descendant glass nodes with shared
keys use group-scoped glassEffectID, independently of visibility-pair matching;
nested groups establish a new namespace. Keys must be unique within the nearest
group and cannot also belong to visibility pairs. Under repeat, including on the
repeated node, a glass shared key must be a template referencing repeat.key.
Existing capability rules still apply. glassUnion is a 1–64 character ASCII id token
([A-Za-z_][A-Za-z0-9_]*); glassTransition is matchedGeometry, materialize or
identity. Both require a base glass surface on the same node.
backgroundExtension: true is image-only and does not require the image itself
to be glass. All four fields are node-only (invalid in window.ios/theme.ios) and
require only the glass capability on iOS; Android ignores them with field paths
in platformNotes.
The system’s Liquid Glass implementation handles Reduce Transparency and
Increase Contrast. On iOS 17–25 the device does not advertise
prototype_glass_v1, so the host refuses glass there: there is no simulated
translucent fill or material substitute. Android advertises the capability on every API level:
API 31 and later blur earlier sibling layers (Haze) and older devices draw a tonal scrim instead.
A glass node without cornerRadius is a capsule on Android as on iOS. An Android
renderer advertising glass must report any approximation (clear variant,
ignored interactive) in platformNotes.
Motion tokens¶
animate.tempo: "fast" | "default" | "slow" requires prototype_motion_tokens_v1
and cannot be combined with durationMs or easing. The contract’s motionTokens
table selects a physical spring by scheme (motion: "standard" by default, or
"expressive"), property role and tempo. easing: "spring" selects the default
tempo of that scheme. Spatial properties are offset, scale, rotation, cornerRadius,
elevation, shadowColor, padding, border width and dp width/height; alpha, background,
color and border color use critically damped effects springs.
| Scheme / role | Damping ratio (fast / default / slow) | Stiffness (fast / default / slow) |
|---|---|---|
| standard spatial | 0.9 / 0.9 / 0.9 | 1400 / 700 / 300 |
| expressive spatial | 0.6 / 0.8 / 0.8 | 800 / 380 / 200 |
| either scheme effects | 1 / 1 / 1 | 3800 / 1600 / 800 |
Compose uses spring(dampingRatio, stiffness). SwiftUI uses
interpolatingSpring(mass: 1, stiffness: k, damping: 2 * dampingRatio * sqrt(k)),
so both renderers use the same physical spring. Reduced motion snaps spatial
changes and retains effects; motion off snaps everything. Existing motion v2/v3
capability requirements still apply; iOS advertises the token capability but
continues to refuse those broader features until its corresponding capabilities
are available.
Disposable apps¶
A disposable app installs one spec as its own app, with its own package, label, icon, permissions
and foreground-service types. The host core lives in src/features/prototype/disposableApp/.
The Android stamper packages a spec into a signed APK. The prototype actions installApp,
listApps and uninstallApp ({appId}, {all: true} or {expired: true}) run on the daemon’s
DisposableAppManager, built on the first such call. iOS refuses them until its stamper exists.
The headless virtual device refuses them too.
On Android, patch, status, inspect and awaitEvent with an installed spec id attach over
automobile-app-<appId>. Conflicting installed spec ids return their slugs. Call launchApp first.
Failed attachment uses CtrlProxy only when live inspection confirms that id; otherwise it
returns attach guidance. Inspection reconciles CtrlProxy sources, preserving disposable-app
entries and waits. Other actions use CtrlProxy.
The listener requires a nonblank assets/prototype/attach-token and an emulator identity
(kernel qemu flag or emulator build fingerprint/hardware). The stamper’s explicit
allowPhysicalDeviceAttach: true option writes assets/prototype/attach-allow-physical-device
to permit physical devices. This applies to debug and release templates alike, independently of APK debuggability. The token-in-APK model is development-only: anyone who can read the APK can recover the token. Reinstalling a slug in place reuses the token. A second connection cannot
replace an authenticated live peer. Status and patch conflicts redact storage.secure state keys.
Events replay at least once. Activities rebind targets to a process-scoped attach listener.
The appInstanceId, sequence ledger and unacknowledged events persist in app storage across
process kills. The journal records the package’s last update time, and the app discards a journal
written under another one, so an in-place reinstall (adb install -r, which keeps app storage)
starts a fresh identity and ledger; clearing app data deletes it. The journal is saved off the main
thread, at most once per event, and a frame reaches the host only after the state it exposes is saved.
hello_result reports identity and an optional
showingId, which changes when the Activity mounts a new runtime. A same-process remount clears
the dismissal and keeps pending events. Older apps without showingId keep process-only identity.
One daemon-host attacher serves every MCP registration and keeps app/device cursors. hello sends
appInstanceId and lastAcknowledgedSequence (initially zero), and {type: "ack", sequence,
appInstanceId} acknowledges matching instances after subscriber delivery. Epochs initialize before
replay. Status reconciles only its app. The 256-event buffer closes on overflow for replay. Device
cleanup and host disposal close sockets, remove adb forwards and forget device cursors. Uninstall
and reinstall each forget only that app’s cursors.
The app stores up to 200 unacknowledged events and replays them on the next hello. The host
de-duplicates replays by sequence within the connection and coordinator. The app drops the oldest
event on overflow and reports cumulative droppedEvents in hello and status. Sequence gaps expose
missing events. A separate writer uses a 256-frame queue and five-second write deadline. Queue
overflow or blocked writes close the peer, and events and requests continue with replay retained.
- Identity. The package is
dev.jasonpearson.automobile.app.<slug>_<sha256(slug) 8 hex>. Hyphens in the slug become underscores because Android package segments allow only[A-Za-z0-9_]. A slug is lowercase hyphen-separated words of at most 48 characters that start with a letter. The prefix is never agent-chosen, so a disposable app cannot replace a real one. - Permissions come only from the spec’s root
requires.INTERNETis always declared. Each canonical permission maps to its manifest permissions (locationmaps to fine and coarse;photosAddmaps to none). Eachrequires.backgroundkind addsFOREGROUND_SERVICEand itsFOREGROUND_SERVICE_<TYPE>permission;remoteNotificationadds none. Arequires.platformmodule whose runtime needs an install-time permission adds it (biometricaddsUSE_BIOMETRIC); it is never granted or denied, so it is not part of the permission mode. The permission mode isprompt(default),grantDeclared, or{grant, deny}, which may name only declared permissions and must not name one in both lists. - Template. The host picks the smallest flavor whose capabilities cover
requiredPrototypeCapabilities(spec). If none does, it refuses and names the missing capabilities and the closest flavor. - Registry. The registry file
disposable-apps.jsonunder the AutoMobile data dir keys records by device id. Each record holds appId, slug, platform, label, spec sha256, template, signer, installedAt and expiresAt. The host serializes writes and makes them atomic. It skips a corrupt file or record with a warning. An install writes its record, with the new expiresAt, as soon as the package is on the device and before the host applies permissions. A permission failure then surfaces as an error saying the app is installed without its permissions, and the sweep still sees the current TTL. - Lifecycle.
ttlHoursdefaults to 72, accepts 0 to 720, and 0 means no expiry. Re-installing a slug updates the app in place and keeps its storage unlessresetis set. The expiry sweep and uninstall refuse ids outside the prefix. They also refuse installed packages whose signer differs from the host’s disposable-app key: one requested id is refused with an error, and in a bulk removal the package is reported underskipped. Each removal is logged atwarn. An app that is already gone from the device still has its registry record cleared. - Device commands. The Android installer runs
adb install -r(thenpm clearforreset),pm grantper granted manifest permission, andpm revokeplus theuser-set user-fixedflags per denied one, so a denial reads as blocked with no dialog. It refuses a grant and a deny that share a manifest permission (microphoneandspeech) before any write.adb installandadb uninstallmust printSuccess. The installed signer comes from the package signing inspection; a signer set that cannot be read never matches the host key, and an unknown presence fails the removal instead of guessing.
Template packaging and stamping¶
The release template package contains an unsigned, unminified APK, the merged text
manifest, stamp points, capability metadata, and template identity plus APK SHA-256.
The host loads a local flavor through AUTOMOBILE_ANDROID_PROTOTYPE_APP_TEMPLATE
and checks its checksum; a released download is not available yet.
Stamping preserves the compiled code and resource table. The host changes the
package, provider authorities, literal label, exact permission set (always including
INTERNET), and explicitly enabled components in structured XML. App-owned resource
references retain the template resource namespace with private-resource access.
aapt2 link resolves those names back to binary resource ids, avoiding unsafe
binary-manifest string replacement. The spec and assets are baked under
assets/prototype/ at stamp time. An icon.backgroundColor (#RRGGBB or
#AARRGGBB) rewrites the prototype_icon_background colour value in the stored
resource table, in every configuration. That colour backs the adaptive icon and the
Android 12+ splash screen, so both follow it. The stamp fails if the template has no
literal colour by that name. An icon.asset is refused: the raster foreground
layer is not stamped yet.
Template signatures are removed before assembly. The resource table stays stored; zipalign aligns it before apksigner signs with v2/v3 using a persistent host-owned PKCS12 identity. Verification checks the resulting signer before publishing the content-addressed cache artifact. The signer certificate SHA-256 is available to the installation signing guard. Cache identity covers the template, stamp inputs, asset bytes, and signer; cache hits check the saved artifact digest.