@colixsystems/widget-sdk 0.115.0 → 0.116.0

package/README.md

@@ -72,6 +72,20 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.112.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.116.0 (contract 1.88.0)
+
+**New primitive `<Overlay>` — a widget can finally open something over the SCREEN (sc-6607).** Until now a widget could only paint an overlay inside its own root, where the host's layout containers clip it: a PDF preview, a lightbox, or a confirm dialog opened trapped inside the widget's tile, and no amount of `zIndex` fixed it (`overflow: "hidden"` clips regardless, and `position: "fixed"` does not exist on native).
+
+```jsx
+<Overlay visible={!!preview} onRequestClose={() => setPreview(null)} size="full">
+  <ScrollView>{renderPreview(preview)}</ScrollView>
+</Overlay>
+```
+
+`<Overlay>` renders its children OUTSIDE the widget's layout box on both hosts — the web Player portals them to the document root, the exported Expo app hands them to the OS modal — while they stay in your own React tree, so their state and hooks are untouched. `onRequestClose` carries the backdrop press, Escape on web, and the Android back button; `size` is `sm` | `md` (default) | `lg` | `full`; the scrim, surface, radius, padding and elevation come from the workspace theme.
+
+An anchored dropdown or popover is the one overlay kind that still belongs inside your own root — `<Overlay>` centres on the screen rather than on a trigger.
+
 ### What's new in 0.115.0 (contract unchanged)
 
 **`write-not-gated-on-user` now accepts a `useCanWrite()` gate — a widget may be opened to logged-out visitors (sc-6593).** The rule (added in 0.89.0, below) flagged any `useDatastoreMutation` write that carried no identity guard, and only a `.id` / `groupIds` / `roles` check counted as one. That encoded "a write needs a signed-in app user" as a platform fact, which it is not: a table whose permissions grant **Create** to *Everyone (anonymous + signed-in)* accepts a write from a logged-out visitor, and `useCanWrite(tableId)` answers `true` for them.
@@ -1090,6 +1104,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useWidgetRoute`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError` carrying `code`, the server's user-safe `message`, and `retryable` (`false` = this charge cannot succeed until the workspace, manifest, or amount changes — show the message, not a retry). `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute, openLink }` for internal page navigation; `openLink(link)` follows an author- or data-supplied link of unknown shape through the host's shared resolver (in-app page → internal route, off-app http(s) → opened outside, unsafe → refused) and is the safe choice for any value your code did not construct, while `Linking.openURL(url)` is for an external URL you built yourself. `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
+- `Overlay` — the screen-level overlay (sc-6607). `<Overlay visible={!!preview} onRequestClose={() => setPreview(null)} size="full">…</Overlay>` renders its children OUTSIDE the widget's layout box on both hosts (web portals it to the document root, native uses the OS modal), so no clipping card, `ScrollView` or neighbouring widget can cut off a document/media preview, lightbox or confirm dialog — which absolute positioning inside the widget cannot achieve on either platform. Children stay in your own React tree, so state and hooks work normally. `onRequestClose` carries the backdrop press, Escape on web, and the Android back button; `size` is `sm` | `md` (default) | `lg` | `full`; the scrim, surface, radius, padding and elevation come from the workspace theme. An anchored dropdown still belongs inside your own root.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.
 
 ## Design & visual polish

package/dist/contract.cjs

@@ -272,6 +272,16 @@ const LINK_ACTION_FIELDS = Object.freeze({
   radius: "buttonRadius",
 });
 
+// sc-6602: Image frames media with the flat `radius`/`borderColor`/`background`
+// trio rather than the `card*` names, so the card scope reaches it through this
+// map. Bound by id, so `shadow` is safe to carry here.
+const MEDIA_FRAME_FIELDS = Object.freeze({
+  background: "background",
+  borderColor: "borderColor",
+  radius: "radius",
+  shadow: "shadow",
+});
+
 // REQ-THEME-WIDGET: the card fields whose NAMES are unambiguous, so they bind to
 // ANY widget that reads them -- including a Mason-generated one, whose id can
 // never appear in a hand-maintained allowlist. That allowlist is why "make the
@@ -280,7 +290,8 @@ const LINK_ACTION_FIELDS = Object.freeze({
 // `shadow` is deliberately ABSENT: its name is bare and shared with the button
 // scope, so binding it by name would cross the scopes. The bare names stay on
 // the allowlist for exactly that reason -- `appstudio.image` also reads a
-// `background` field, and the button scope must not leak into it.
+// `background` field, and the button scope must not leak into it. The media
+// surfaces get themed elevation by ID instead (sc-6602); keep it out of here.
 const CARD_UNIVERSAL_FIELDS = Object.freeze({
   background: "cardBackground",
   borderColor: "cardBorderColor",
@@ -367,6 +378,12 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
       "appstudio.user-management": CARD_SURFACE_FIELDS,
       "appstudio.link": CARD_SURFACE_FIELDS,
+      // sc-6602: the media surfaces. They paint a card exactly as the widgets
+      // above do, so a themed elevation must reach them — a reference design's
+      // lifted hero image was unthemeable while these three were absent.
+      "appstudio.sound": CARD_SURFACE_FIELDS,
+      "appstudio.video": CARD_SURFACE_FIELDS,
+      "appstudio.image": MEDIA_FRAME_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -1770,6 +1787,17 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // sc-6607 — the SCREEN-level overlay. Widgets could previously only paint an
+  // overlay inside their own box, so a preview or dialog was clipped by the
+  // layout container the widget sits in; this is the one primitive that leaves
+  // that box on both hosts.
+  {
+    name: "Overlay",
+    description:
+      'Screen-level overlay. `<Overlay visible={open} onRequestClose={() => setOpen(false)} size="md">…panel…</Overlay>`. THE way to open anything that must cover the SCREEN rather than the widget — a preview (PDF, image, video), a lightbox, a confirm dialog, a full detail panel. It renders OUTSIDE the widget layout box on both hosts (react-native-web portals it to the document root; native uses the OS modal), so no `overflow: hidden` card, scroll container or sibling widget can clip or cover it — which absolute positioning inside the widget cannot achieve on either host. Children stay in your own React tree, so state and hooks work normally. Props: `visible` (boolean, required to show), `onRequestClose` (fired by the backdrop press, the Escape key on web, and the Android back button — always wire it or the overlay cannot be closed), `size` ("sm" | "md" | "lg" | "full", default "md"; `full` runs edge to edge for media), `dismissOnBackdropPress` (default true), `accessibilityLabel`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme — never re-style them. Keep it for screen-level surfaces: a dropdown anchored to its trigger still belongs inside the widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -3468,7 +3496,11 @@ const CONTRACT = deepFreeze({
   // plus the `pressableLift` primitive that resolves it per input — hover on
   // web, press on native. Tappable layout containers and widget surfaces lift
   // from this ONE table.
-  version: "1.87.0",
+  // 1.88.0: additive (sc-6607) — the `Overlay` primitive: the first surface a
+  // widget can open at SCREEN level. Everything before it was clipped by the
+  // layout container the widget sits in, so a preview or dialog could not leave
+  // the widget's own tile on either host.
+  version: "1.88.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -272,6 +272,16 @@ const LINK_ACTION_FIELDS = Object.freeze({
   radius: "buttonRadius",
 });
 
+// sc-6602: Image frames media with the flat `radius`/`borderColor`/`background`
+// trio rather than the `card*` names, so the card scope reaches it through this
+// map. Bound by id, so `shadow` is safe to carry here.
+const MEDIA_FRAME_FIELDS = Object.freeze({
+  background: "background",
+  borderColor: "borderColor",
+  radius: "radius",
+  shadow: "shadow",
+});
+
 // REQ-THEME-WIDGET: the card fields whose NAMES are unambiguous, so they bind to
 // ANY widget that reads them -- including a Mason-generated one, whose id can
 // never appear in a hand-maintained allowlist. That allowlist is why "make the
@@ -280,7 +290,8 @@ const LINK_ACTION_FIELDS = Object.freeze({
 // `shadow` is deliberately ABSENT: its name is bare and shared with the button
 // scope, so binding it by name would cross the scopes. The bare names stay on
 // the allowlist for exactly that reason -- `appstudio.image` also reads a
-// `background` field, and the button scope must not leak into it.
+// `background` field, and the button scope must not leak into it. The media
+// surfaces get themed elevation by ID instead (sc-6602); keep it out of here.
 const CARD_UNIVERSAL_FIELDS = Object.freeze({
   background: "cardBackground",
   borderColor: "cardBorderColor",
@@ -367,6 +378,12 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
       "appstudio.user-management": CARD_SURFACE_FIELDS,
       "appstudio.link": CARD_SURFACE_FIELDS,
+      // sc-6602: the media surfaces. They paint a card exactly as the widgets
+      // above do, so a themed elevation must reach them — a reference design's
+      // lifted hero image was unthemeable while these three were absent.
+      "appstudio.sound": CARD_SURFACE_FIELDS,
+      "appstudio.video": CARD_SURFACE_FIELDS,
+      "appstudio.image": MEDIA_FRAME_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -1770,6 +1787,17 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // sc-6607 — the SCREEN-level overlay. Widgets could previously only paint an
+  // overlay inside their own box, so a preview or dialog was clipped by the
+  // layout container the widget sits in; this is the one primitive that leaves
+  // that box on both hosts.
+  {
+    name: "Overlay",
+    description:
+      'Screen-level overlay. `<Overlay visible={open} onRequestClose={() => setOpen(false)} size="md">…panel…</Overlay>`. THE way to open anything that must cover the SCREEN rather than the widget — a preview (PDF, image, video), a lightbox, a confirm dialog, a full detail panel. It renders OUTSIDE the widget layout box on both hosts (react-native-web portals it to the document root; native uses the OS modal), so no `overflow: hidden` card, scroll container or sibling widget can clip or cover it — which absolute positioning inside the widget cannot achieve on either host. Children stay in your own React tree, so state and hooks work normally. Props: `visible` (boolean, required to show), `onRequestClose` (fired by the backdrop press, the Escape key on web, and the Android back button — always wire it or the overlay cannot be closed), `size` ("sm" | "md" | "lg" | "full", default "md"; `full` runs edge to edge for media), `dismissOnBackdropPress` (default true), `accessibilityLabel`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme — never re-style them. Keep it for screen-level surfaces: a dropdown anchored to its trigger still belongs inside the widget.',
+    rnComponent: null,
+    docsUrl: null,
+  },
 ];
 
 const CATEGORIES = [
@@ -3468,7 +3496,11 @@ const CONTRACT = deepFreeze({
   // plus the `pressableLift` primitive that resolves it per input — hover on
   // web, press on native. Tappable layout containers and widget surfaces lift
   // from this ONE table.
-  version: "1.87.0",
+  // 1.88.0: additive (sc-6607) — the `Overlay` primitive: the first surface a
+  // widget can open at SCREEN level. Everything before it was clipped by the
+  // layout container the widget sits in, so a preview or dialog could not leave
+  // the widget's own tile on either host.
+  version: "1.88.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -2151,6 +2151,36 @@ export const Gradient: (props: {
   children?: ReactNode;
 }) => any;
 
+/**
+ * sc-6607 — screen-level overlay. Renders OUTSIDE the widget's layout box on
+ * both hosts (web portals it to the document root, native uses the OS modal),
+ * so no clipping card, scroll container or neighbouring widget can cut it off.
+ * Use it for anything that takes over the screen — a document/media preview, a
+ * lightbox, a confirm dialog. An anchored dropdown still belongs inside the
+ * widget's own root.
+ *
+ * @example
+ *   <Overlay visible={!!preview} onRequestClose={() => setPreview(null)} size="full">
+ *     <ScrollView>{renderPreview(preview)}</ScrollView>
+ *   </Overlay>
+ */
+export const Overlay: (props: {
+  /** Nothing renders (and nothing is mounted) while this is false. */
+  visible?: boolean;
+  /** Backdrop press, Escape (web) and the Android back button all fire this. */
+  onRequestClose?: () => void;
+  /** Panel width tier. `full` runs edge to edge. Defaults to `md`. */
+  size?: "sm" | "md" | "lg" | "full";
+  /** Set false when only an explicit control may close the overlay. */
+  dismissOnBackdropPress?: boolean;
+  accessibilityLabel?: string;
+  /** Label for the backdrop's dismiss target. Defaults to "Close". */
+  closeAccessibilityLabel?: string;
+  /** Extra styles merged onto the themed panel. */
+  style?: any;
+  children?: ReactNode;
+}) => any;
+
 // ------------------------------------------------------- theme derivation
 // sc-3696: the colour maths both hosts resolve `useTheme()` with. Exported so
 // the Player (frontend/src/services/widgetTheme.js) and the exported app's

package/dist/index.js

@@ -90,6 +90,10 @@ export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";
 // the web variant and index.native.js picks the native variant.
 export { useClipboard, ClipboardError } from "./clipboard.js";
 export { useToast } from "./toast.js";
+// sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
+// each platform's primitives, so a widget's modal escapes its container box
+// identically on the Player and the Expo export.
+export { Overlay } from "./overlay.js";
 export {
   Text,
   View,

package/dist/index.native.js

@@ -88,6 +88,8 @@ export { isNarrowWidth, NARROW_WIDTH_PX } from "./container-width.js";
 // REQ-WSDK-PLATFORM §6 — Tier A hooks (native variants).
 export { useClipboard, ClipboardError } from "./clipboard.native.js";
 export { useToast } from "./toast.native.js";
+// sc-6607 — see the note on the web mirror in ./index.js.
+export { Overlay } from "./overlay.native.js";
 export {
   Text,
   View,

package/dist/overlay-tokens.js

@@ -0,0 +1,64 @@
+// sc-6607 — the values `<Overlay>` paints one screen-level overlay with.
+//
+// Presentation-free and platform-free, the same way `toast-host.js` is: both
+// hosts render the overlay from the SAME component (`overlay-view.js`), and
+// this module is where the theme becomes numbers. Keeping the maths here makes
+// it unit-testable without a renderer, and makes the scrim/panel contract a
+// thing tests can pin rather than a literal buried in JSX.
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+
+export const OVERLAY_SIZES = Object.freeze(["sm", "md", "lg", "full"]);
+
+export const OVERLAY_DEFAULTS = Object.freeze({
+  size: "md",
+  // Slate-black at 55%: dark enough to mute a busy page behind the panel,
+  // light enough that the page still reads as "still there, just behind".
+  scrim: "rgba(15, 23, 42, 0.55)",
+  // Breathing room between the panel and the screen edge on a phone.
+  screenPadding: 16,
+});
+
+// `full` deliberately has no ceiling — a media/PDF preview wants the screen.
+const SIZE_MAX_WIDTH = Object.freeze({
+  sm: 360,
+  md: 520,
+  lg: 760,
+  full: null,
+});
+
+export function normaliseOverlaySize(size) {
+  return OVERLAY_SIZES.indexOf(size) === -1 ? OVERLAY_DEFAULTS.size : size;
+}
+
+/**
+ * Resolve the values one overlay is painted with, from the workspace theme.
+ *
+ * Returns primitives only, so the panel a widget opens carries the workspace's
+ * own surface, radius, spacing and elevation instead of a hard-coded card.
+ *
+ * @param {object} theme — the resolved workspace theme (`useTheme()` shape).
+ * @param {string} size — `sm` | `md` | `lg` | `full`.
+ */
+export function resolveOverlayTokens(theme, size) {
+  const safeSize = normaliseOverlaySize(size);
+  const base = theme && typeof theme === "object" ? theme : DEFAULT_THEME_TOKENS;
+  const fallback = DEFAULT_THEME_TOKENS;
+  const colors = base.colors || fallback.colors;
+  const radii = base.radii || fallback.radii;
+  const spacing = base.spacing || fallback.spacing;
+  const elevation = (base.elevation || fallback.elevation).lg || {};
+
+  return {
+    size: safeSize,
+    scrim: OVERLAY_DEFAULTS.scrim,
+    surface: colors.surface || fallback.colors.surface,
+    radius: safeSize === "full" ? 0 : radii.lg || fallback.radii.lg,
+    padding: spacing.lg || fallback.spacing.lg,
+    // A `full` overlay runs edge to edge; every other size keeps a margin so
+    // the scrim stays visible and the panel reads as a layer, not a screen.
+    screenPadding: safeSize === "full" ? 0 : OVERLAY_DEFAULTS.screenPadding,
+    maxWidth: SIZE_MAX_WIDTH[safeSize],
+    elevation,
+  };
+}

package/dist/overlay-view.js

@@ -0,0 +1,109 @@
+// sc-6607 — the ONE implementation behind the `<Overlay>` SDK primitive.
+//
+// A widget that opens a preview, a lightbox, or a confirm dialog used to have
+// no way to paint over the SCREEN: it rendered the panel as an absolutely
+// positioned child of its own root, where the Player's layout containers
+// (`overflow: hidden` cards, scroll containers) clip it and where React Native
+// has no `position: "fixed"` at all. `<Overlay>` fixes that for both hosts at
+// once by rendering into React Native's `Modal`, which leaves the parent's
+// layout on BOTH platforms — react-native-web portals it to `document.body`,
+// native hands it to the OS — while keeping the children in the widget's own
+// React tree, so their state, hooks and WidgetContext all survive.
+//
+// The two platform bindings (`overlay.js` / `overlay.native.js`) differ ONLY in
+// where the primitives come from; the component itself is defined once here so
+// the hosts cannot drift (CLAUDE.md §3, §8).
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { resolveOverlayTokens } from "./overlay-tokens.js";
+
+/**
+ * Bind the shared overlay component to one platform's primitives.
+ *
+ * @param {{Modal: any, View: any, Pressable: any, StyleSheet: any}} rn
+ */
+export function makeOverlay(rn) {
+  const { Modal, View, Pressable, StyleSheet } = rn;
+
+  function Overlay({
+    visible = false,
+    onRequestClose,
+    size = "md",
+    dismissOnBackdropPress = true,
+    accessibilityLabel,
+    closeAccessibilityLabel = "Close",
+    style,
+    children,
+  }) {
+    const theme = useHostTheme();
+    const tokens = React.useMemo(
+      () => resolveOverlayTokens(theme, size),
+      [theme, size],
+    );
+    const requestClose = React.useCallback(() => {
+      if (typeof onRequestClose === "function") onRequestClose();
+    }, [onRequestClose]);
+
+    // Unmounted while closed: `Modal` appends a host container the moment it
+    // renders, so every widget on the page would otherwise leave one behind.
+    if (!visible) return null;
+
+    const backdrop = {
+      flex: 1,
+      alignItems: "center",
+      justifyContent: "center",
+      padding: tokens.screenPadding,
+      backgroundColor: tokens.scrim,
+    };
+    const panel = {
+      width: "100%",
+      // Capped to the padded screen box so a tall panel scrolls inside its own
+      // ScrollView instead of overflowing past the viewport unreachably.
+      maxHeight: "100%",
+      flexShrink: 1,
+      ...(tokens.maxWidth ? { maxWidth: tokens.maxWidth } : { flex: 1 }),
+      backgroundColor: tokens.surface,
+      borderRadius: tokens.radius,
+      padding: tokens.padding,
+      ...tokens.elevation,
+    };
+
+    return React.createElement(
+      Modal,
+      {
+        visible: true,
+        transparent: true,
+        // Not animated on purpose: the web host arms the overlay's dialog role
+        // and its Escape handler when the entrance animation ENDS, so a fade
+        // leaves a window where the keyboard cannot dismiss it — and a dropped
+        // animation event would leave it un-dismissable for good.
+        animationType: "none",
+        onRequestClose: requestClose,
+      },
+      React.createElement(
+        View,
+        { style: backdrop },
+        dismissOnBackdropPress
+          ? React.createElement(Pressable, {
+              style: StyleSheet.absoluteFill,
+              onPress: requestClose,
+              accessibilityRole: "button",
+              accessibilityLabel: closeAccessibilityLabel,
+            })
+          : null,
+        React.createElement(
+          View,
+          {
+            style: [panel, style],
+            accessibilityLabel,
+          },
+          children,
+        ),
+      ),
+    );
+  }
+
+  Overlay.displayName = "Overlay";
+  return Overlay;
+}

package/dist/overlay.js

@@ -0,0 +1,13 @@
+// sc-6607 — `<Overlay>` (web). Binds the shared implementation in
+// ./overlay-view.js to react-native-web's primitives.
+//
+// The import is `react-native-web` rather than the bare `react-native`
+// specifier for the rolldown optional-peer-dep reason spelled out at the top of
+// ./primitives.js. react-native-web's `Modal` portals its subtree into a
+// `document.body` container at `position: fixed`, which is exactly what makes
+// the overlay escape the widget's clipping ancestors.
+
+import * as ReactNative from "react-native-web";
+import { makeOverlay } from "./overlay-view.js";
+
+export const Overlay = makeOverlay(ReactNative);

package/dist/overlay.native.js

@@ -0,0 +1,11 @@
+// sc-6607 — `<Overlay>` (native). Binds the shared implementation in
+// ./overlay-view.js to React Native's own primitives.
+//
+// RN's `Modal` renders outside the parent's layout and routes the Android
+// hardware back button to `onRequestClose`, matching what react-native-web's
+// portal does on the web (./overlay.js). Only the import differs.
+
+import { Modal, View, Pressable, StyleSheet } from "react-native";
+import { makeOverlay } from "./overlay-view.js";
+
+export const Overlay = makeOverlay({ Modal, View, Pressable, StyleSheet });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.115.0",
+  "version": "0.116.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/vetted-imports-audit.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-page-url.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-hardcoded-design.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/corner-radius.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/interaction-lift.test.js src/__tests__/toast-host.test.js src/__tests__/overlay-tokens.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js src/__tests__/hooks-camera.test.js src/__tests__/hooks-bound-columns.test.js src/__tests__/hooks-stable-query.test.js src/__tests__/hooks-can-write.test.js src/__tests__/widget-route.test.js"
   },
   "engines": {
     "node": ">=18"