overlay is an AUP cross-device primitive, not a Web Device layout component and not a Web-only widget. It is one of the 18 names in AUP_PRIMITIVES and appears in every target's DeviceCaps.primitives map as native, webview, partial, or unsupported.
Contract
| Field | Value |
|---|---|
| Primitive name | overlay |
| Layer | AUP cross-device primitive (AUP_PRIMITIVES) |
| Public status | experimental |
| Document capability | unsupported |
| Shared degradation chain | overlay → text |
| Author entry | AUP session / interactive Web (Showcase overlays) |
| Document renderer / notes | No dedicated document renderer for full overlay chrome; chain degrades to text |
| Showcase evidence | blocklets/showcase-dsl/.aup/pages/overlays.aup |
When to use
Alert, confirm, toast, HUD, or multi-step choice UI on a target that reports overlay support.
When not to use
Do not put live overlay samples on static docs. Document cannot host modal interaction chrome.
Document sample
Not provided. DEVICE_CAPS_DOCUMENT leaves overlay at the default unsupported. Shared chain: overlay → text. Public docs must not fake modal/toast UI.
Author and accept overlays on an interactive AUP session (Showcase overlays page), not on this site’s static document target.
Evidence anchors
| Item | Value |
|---|---|
| Registry | packages/aup/src/aup-types.ts · AUP_PRIMITIVES |
| Document caps | providers/runtime/web-device/src/device-caps.ts · DEVICE_CAPS_DOCUMENT |
| Degradation | packages/aup/src/degradation.ts · DEGRADATION_CHAINS |
| Internal matrix | docs/aup/capability-matrix.md (internal, non-routed) |
| Taxonomy hub | Primitive taxonomy and evidence |
| Sample contract rules | Live examples: scope and contract |