@colixsystems/widget-sdk 0.207.0 → 0.210.0

package/README.md

@@ -83,7 +83,49 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.207.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**.
+`v0.210.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.210.0 (contract 1.169.0)
+
+**New component `<Modal>` — the standard dialog.** Widgets that opened a dialog each built their own header, close button and action row inside a bare `<Overlay>`, so no two dialogs in an app matched and none could be restyled from the theme. `<Modal>` is that dialog, built once on `<Overlay>`:
+
+```jsx
+import { useState } from "react";
+import { Modal, Button, TextField } from "@colixsystems/widget-sdk";
+
+function AddNote({ onSave }) {
+  const [open, setOpen] = useState(false);
+  const [note, setNote] = useState("");
+  return (
+    <>
+      <Button title="Add note" onPress={() => setOpen(true)} />
+      <Modal
+        visible={open}
+        onRequestClose={() => setOpen(false)}
+        title="Add note"
+        footer={
+          <>
+            <Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} />
+            <Button title="Save" onPress={() => onSave(note)} />
+          </>
+        }
+      >
+        <TextField value={note} onChangeText={setNote} placeholder="Note" accessibilityLabel="Note" />
+      </Modal>
+    </>
+  );
+}
+```
+
+It draws the title, a close button, a body that scrolls when it is long, and a footer action row laid out below it, and it renders outside the widget's layout box on both hosts exactly as `<Overlay>` does. Props: `visible`, `onRequestClose` (the close button, the backdrop press, Escape on web and the Android back button), `title`, `footer` (the action buttons, laid out as one right-aligned row that wraps; omit it for no footer), `presentation` (`dialog`, centred, the default | `sheet`, anchored to the bottom edge), `size` (`sm` | `md` | `lg` | `full`), `dismissOnBackdropPress`, `dismissible` (default true; false hides the close button and stops the backdrop, Escape and Android back from closing a dialog that must stay open, e.g. while it saves), `role` (`dialog` | `alertdialog`, web only), `initialFocusRef` (the control focused on open, web only), `closeAccessibilityLabel` (default `Close`), `accessibilityLabel` (names a dialog with no title) and `testID`. With no `onRequestClose` it draws no close button; with no title either, no header row. Use `dismissible={false}` only while that work runs and always restore it: with no footer button or in-body control, such a dialog cannot be closed. Do not wrap the body in your own `ScrollView`.
+
+A dialog that paints its own background hands whatever is rendered inside it a theme re-inked for that background, so SDK components and any component of yours calling `useTheme()` inside the `<Modal>` stay readable; text you style with the theme read *outside* the dialog does not follow, so build the body as its own component. In the exported app the dialog pads a `sheet` by the bottom safe-area inset and a `full` dialog by the top and bottom ones, and wraps its panel in React Native's `KeyboardAvoidingView`. This is not yet verified on a device, and `KeyboardAvoidingView` inside a React Native `Modal` window is a known risk on Android: until it is verified, keep a form with text inputs in the default `dialog` presentation. A bare `<Overlay>` gets neither.
+
+**New theme scope `modal`.** A dialog's `background`, `titleColor`, `scrim`, `radius`, `padding` and `shadow` are set app-wide under `themeConfig.components.modal` (Design > Components > Dialogs). `<Modal>` reads the scope itself, so the scope names it under `sdkComponents` and binds no `styleSchema` field. The `scrim` is always painted see-through: an opaque colour takes the default 55% alpha, and no scrim exceeds 85%. With no token set a `<Modal>` sits on exactly the panel and scrim `<Overlay>` has always drawn.
+
+**`<Overlay>` gains `presentation`, `role`, `initialFocusRef`, `backdropAccessible` and `testID`, and a themed scrim.** Its `accessibilityLabel` now names the web dialog node itself (the panel still carries it in the exported app). Apart from the scrim, a bare `<Overlay>` renders in the exported app exactly as before. `presentation="sheet"` anchors the panel to the bottom edge; `dialog` (the default) is the centred panel it always was. Its scrim now follows the `modal` scope's `scrim` token, and is unchanged when the token is unset. Keep `<Overlay>` for what is not a dialog: a media or document preview, a lightbox.
+
+The `<MarkdownInput>` link form now opens as a `<Modal>`. Hosts get `resolveModalTokens(theme, { size, presentation })`, `modalScopeDefaults(theme)` and `surfaceAwareTheme(theme, backgroundColor)` from `@colixsystems/widget-sdk/host`. Additive.
 
 ### What's new in 0.207.0 (contract 1.166.0)
 
@@ -2457,6 +2499,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `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.
+- `Modal` — the standard dialog, built on `Overlay`. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<Button title="Save" onPress={save} />}>…</Modal>` draws a title, a close button, a body that scrolls when it is long and a footer action row laid out below it. Its background, corner radius, padding, scrim, shadow and title colour come from the theme's `modal` scope (Design > Components > Dialogs), so every dialog in an app matches. Props: `visible`, `onRequestClose`, `dismissible`, `title`, `footer`, `presentation` (`dialog` | `sheet`), `size` (`sm` | `md` | `lg` | `full`), `dismissOnBackdropPress`, `role`, `initialFocusRef`, `closeAccessibilityLabel`, `accessibilityLabel`, `testID`. Use it for every dialog instead of hand-building a header and an action row inside `Overlay`.
 - `RichText` — the formatted-content renderer (sc-6970). `<RichText value={post.body} />` parses the markdown subset (`**bold**`, `*italic*` / `_italic_`, `` `code` ``, `#`/`##`/`###` headings, `-`/`*` bullets, `1.` ordered items, one-line `![alt](src "large")` images) and renders it with SDK primitives, so formatted content reads the same in the web Player and the exported Expo app. `value` is markdown, NOT HTML — widgets have no `dangerouslySetInnerHTML` on either host, so tags in a content string render as literal tag soup; stored text that still holds legacy HTML is stripped to plain text rather than shown as markup. Props: `value`, `renderImage` (`({ src, alt, size }) => node` — supply it when images are filestore ids, because resolving one needs the scopes your own widget holds; without it only absolute `http(s)` URLs render), `style`, `testID`. Colour, type scale and leading come from the workspace theme — never re-style them.
 - `MarkdownInput` — the authoring half of `<RichText>` (sc-6970). `<MarkdownInput value={draft} onChange={setDraft} />` is a multi-line field, a toolbar whose buttons wrap the current SELECTION in markdown markers (bold, italic, code, H2, H3, bullets, numbered list, each toggling back off), and a live `<RichText>` preview of the result underneath — the way to let an app USER write formatted text, instead of a bare `TextInput` plus hand-rolled buttons that can only splice literal tags into the value. Props: `value`, `onChange(next)`, `placeholder`, `previewLabel` (default `Preview`), `showPreview` (default true), `renderImage` (passed through to the preview), `minHeight` (150) and `maxHeight` (280) so a long draft scrolls inside its box, `accessibilityLabel`, `style`, `testID`.
 - `parseMarkdown`, `markdownToPlainText`, `parseMarkdownImage`, `formatMarkdownImage`, `stripHtmlToMarkdown`, `MARKDOWN_IMAGE_SIZES` — the same grammar as pure helpers, for content you inspect rather than render: the block list, a marker-free projection (list previews, search, a11y labels), the one-line image form read and written, a legacy-HTML row normalised to markdown on read, and the closed size list (`small` | `medium` | `large` | `full`).

package/dist/contract.cjs

@@ -723,6 +723,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Dialogs: `<Modal>` reads this scope directly, so it names the SDK component
+  // it styles and binds no widget field. `<Overlay>` reads the scrim alone.
+  modal: Object.freeze({
+    label: "Dialogs",
+    sdkComponents: Object.freeze(["Modal"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      titleColor: Object.freeze({ type: "color" }),
+      scrim: Object.freeze({
+        type: "color",
+        translucent: true,
+        note: "also the backdrop behind every <Overlay>",
+      }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.lg" }),
+      padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.lg" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2886,7 +2905,15 @@ const PRIMITIVES = [
   {
     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.',
+      '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 and is not a dialog — a preview (PDF, image, video), a lightbox, a full-screen viewer. A dialog (a title, a close button, actions) is `<Modal>`, which is built on this. 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), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (web only), `accessibilityLabel` (names the dialog), `testID`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme (the scrim from Design > Components > Dialogs) — 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,
+  },
+  // The standard dialog, built on `<Overlay>`, so widgets stop hand-building one.
+  {
+    name: "Modal",
+    description:
+      'Standard dialog. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<><Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} /><Button title="Save" onPress={save} /></>}>…body…</Modal>`. THE way to open a dialog, a form in a pop-up, a detail panel or a bottom sheet: it draws the title, the close button, a body that scrolls when it is long, and a footer action row laid out below it, and its background, corner radius, padding, scrim, shadow and title colour come from the theme (Design > Components > Dialogs), so every dialog in the app matches. It is built on `<Overlay>`, so it renders OUTSIDE the widget layout box on both hosts and nothing can clip it. Never hand-build a header, a close button or an action row inside a bare `<Overlay>`; keep `<Overlay>` for surfaces that are not a dialog (a media or document preview, a lightbox). Props: `visible` (boolean), `onRequestClose` (fired by the close button, the backdrop press, the Escape key on web and the Android back button — always wire it), `dismissible` (default true; false hides the close button and stops the backdrop, Escape and Android back from closing it, for a dialog that must stay open while it saves — only while that work runs, and always restore it, or nobody can close the dialog), `title` (string), `footer` (the action buttons, laid out as one right-aligned row that wraps on a phone; omit for no footer), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge; keep a form with text inputs in "dialog" — in the exported app the keyboard handling of a sheet is not yet verified on a device), `size` ("sm" | "md" | "lg" | "full", default "md"), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (a ref to the control focused on open; web only), `closeAccessibilityLabel` (default "Close" — pass your translated label), `accessibilityLabel` (names a dialog with no title) and `testID`. With no `onRequestClose` it draws no close button. Components rendered inside it read a theme re-inked for the background the dialog paints, so build the body as its own component. Do not wrap the body in your own `ScrollView` and do not re-style the panel.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -5554,7 +5581,15 @@ const CONTRACT = deepFreeze({
   // 1.166.0: additive (sc-10927) — the `Banner` primitive (a themed inline
   //    error, warning, success or notice) and the `alert` component scope it
   //    reads.
-  version: "1.166.0",
+  // 1.169.0: additive (sc-10924) — the `Modal` primitive: the standard dialog
+  //    (title, close button, scrolling body, footer action row; `presentation`
+  //    "dialog" | "sheet") built on `Overlay`. New `themeComponents.modal`
+  //    scope (background, titleColor, scrim, radius, padding, shadow), read by
+  //    `Modal`; `Overlay` reads its `scrim` and gains `presentation`, `role`,
+  //    `initialFocusRef`, `backdropAccessible` and `testID`. A scope may now
+  //    name `sdkComponents` and bind no widget field; a colour token may be
+  //    `translucent` (always painted see-through) and carry a `note`.
+  version: "1.169.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -723,6 +723,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Dialogs: `<Modal>` reads this scope directly, so it names the SDK component
+  // it styles and binds no widget field. `<Overlay>` reads the scrim alone.
+  modal: Object.freeze({
+    label: "Dialogs",
+    sdkComponents: Object.freeze(["Modal"]),
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      titleColor: Object.freeze({ type: "color" }),
+      scrim: Object.freeze({
+        type: "color",
+        translucent: true,
+        note: "also the backdrop behind every <Overlay>",
+      }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.lg" }),
+      padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.lg" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2886,7 +2905,15 @@ const PRIMITIVES = [
   {
     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.',
+      '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 and is not a dialog — a preview (PDF, image, video), a lightbox, a full-screen viewer. A dialog (a title, a close button, actions) is `<Modal>`, which is built on this. 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), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (web only), `accessibilityLabel` (names the dialog), `testID`, and `style` for extra panel styles. The scrim, surface, radius, padding and elevation come from the workspace theme (the scrim from Design > Components > Dialogs) — 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,
+  },
+  // The standard dialog, built on `<Overlay>`, so widgets stop hand-building one.
+  {
+    name: "Modal",
+    description:
+      'Standard dialog. `<Modal visible={open} onRequestClose={() => setOpen(false)} title="Edit order" footer={<><Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} /><Button title="Save" onPress={save} /></>}>…body…</Modal>`. THE way to open a dialog, a form in a pop-up, a detail panel or a bottom sheet: it draws the title, the close button, a body that scrolls when it is long, and a footer action row laid out below it, and its background, corner radius, padding, scrim, shadow and title colour come from the theme (Design > Components > Dialogs), so every dialog in the app matches. It is built on `<Overlay>`, so it renders OUTSIDE the widget layout box on both hosts and nothing can clip it. Never hand-build a header, a close button or an action row inside a bare `<Overlay>`; keep `<Overlay>` for surfaces that are not a dialog (a media or document preview, a lightbox). Props: `visible` (boolean), `onRequestClose` (fired by the close button, the backdrop press, the Escape key on web and the Android back button — always wire it), `dismissible` (default true; false hides the close button and stops the backdrop, Escape and Android back from closing it, for a dialog that must stay open while it saves — only while that work runs, and always restore it, or nobody can close the dialog), `title` (string), `footer` (the action buttons, laid out as one right-aligned row that wraps on a phone; omit for no footer), `presentation` ("dialog", centred, the default | "sheet", anchored to the bottom edge; keep a form with text inputs in "dialog" — in the exported app the keyboard handling of a sheet is not yet verified on a device), `size` ("sm" | "md" | "lg" | "full", default "md"), `dismissOnBackdropPress` (default true), `role` ("dialog" default | "alertdialog"; web only), `initialFocusRef` (a ref to the control focused on open; web only), `closeAccessibilityLabel` (default "Close" — pass your translated label), `accessibilityLabel` (names a dialog with no title) and `testID`. With no `onRequestClose` it draws no close button. Components rendered inside it read a theme re-inked for the background the dialog paints, so build the body as its own component. Do not wrap the body in your own `ScrollView` and do not re-style the panel.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -5550,7 +5577,15 @@ const CONTRACT = deepFreeze({
   // 1.166.0: additive (sc-10927) — the `Banner` primitive (a themed inline
   //    error, warning, success or notice) and the `alert` component scope it
   //    reads.
-  version: "1.166.0",
+  // 1.169.0: additive (sc-10924) — the `Modal` primitive: the standard dialog
+  //    (title, close button, scrolling body, footer action row; `presentation`
+  //    "dialog" | "sheet") built on `Overlay`. New `themeComponents.modal`
+  //    scope (background, titleColor, scrim, radius, padding, shadow), read by
+  //    `Modal`; `Overlay` reads its `scrim` and gains `presentation`, `role`,
+  //    `initialFocusRef`, `backdropAccessible` and `testID`. A scope may now
+  //    name `sdkComponents` and bind no widget field; a colour token may be
+  //    `translucent` (always painted see-through) and carry a `note`.
+  version: "1.169.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -89,6 +89,19 @@ export function BackdropScope({ basis, children }) {
   return React.createElement(HostWidgetContext.Provider, { value }, children);
 }
 
+/**
+ * @internal — hands a subtree `theme` in place of the host's (`<Modal>` uses
+ * it for the theme re-inked for its own background). No theme, no change.
+ */
+export function ThemeScope({ theme, children }) {
+  const ctx = useContext(HostWidgetContext);
+  const value = useMemo(
+    () => (theme && ctx ? { ...ctx, workspace: { ...ctx.workspace, theme } } : ctx),
+    [ctx, theme],
+  );
+  return React.createElement(HostWidgetContext.Provider, { value }, children);
+}
+
 // Exported for ./toast.js + future hook modules outside hooks.js. Internal
 // utility — widget code should not import this directly.
 export function useWidgetContextOrThrow(hookName) {

package/dist/host.d.ts

@@ -45,6 +45,13 @@ export function normaliseThemeComponents(raw: unknown): ThemeComponents;
  */
 export function bannerScopeDefaults(theme: unknown): Record<string, string | number>;
 
+/**
+ * The theme a surface painting `backgroundColor` hands its subtree: surface
+ * tokens derived for that fill, and any type tier whose own ink cannot be read
+ * on it re-inked. Returns `theme` itself when the colour is unusable.
+ */
+export function surfaceAwareTheme<T>(theme: T, backgroundColor: unknown): T;
+
 /** Minimum contrast: `text` for labels (WCAG 1.4.3), `boundary` for edges (1.4.11). */
 export const INK_CONTRAST: Readonly<{ text: number; boundary: number }>;
 
@@ -152,6 +159,45 @@ export interface ToastControllerOptions {
   clearTimer?: (handle: unknown) => void;
 }
 
+/** What one `<Modal>` paints with; see `resolveModalTokens`. */
+export interface ModalTokens {
+  size: "sm" | "md" | "lg" | "full";
+  presentation: "dialog" | "sheet";
+  scrim: string;
+  /** The `background` token as set (it may be see-through), else the surface. */
+  background: string;
+  /** What the panel paints: `background` composited over the overlay surface. */
+  panelColor: string;
+  /** `panelColor` when a background is set, for re-inking the body; else null. */
+  bodyBackdrop: string | null;
+  radius: number;
+  padding: number;
+  /** The themed elevation as a style, or null for the overlay's own. */
+  shadow: Record<string, unknown> | null;
+  /** The elevation level in force: the themed one, else the overlay's. */
+  shadowLevel: "none" | "sm" | "md" | "lg";
+  titleColor: string;
+  closeColor: string;
+  sectionGap: number;
+  actionGap: number;
+}
+
+/**
+ * The look of the SDK `<Modal>` under a resolved theme: its `modal` component
+ * scope over the overlay's defaults. For a host previewing Theme Settings >
+ * Dialogs with the values the dialog itself paints.
+ */
+export function resolveModalTokens(
+  theme: unknown,
+  options?: { size?: string; presentation?: string },
+): ModalTokens;
+
+/**
+ * What the `modal` scope's tokens without a `uiDefault` path resolve to while
+ * unset: the scrim, and the title colour on the background currently set.
+ */
+export function modalScopeDefaults(theme: unknown): { scrim: string; titleColor: string };
+
 export const TOAST_DEFAULTS: { durationMs: number; maxVisible: number };
 
 export function normalizeToastKind(kind: unknown): ToastKind;

package/dist/host.js

@@ -42,12 +42,16 @@ export {
 // Host plumbing, deliberately off the author entry point: a widget reads the
 // already-correct `useTheme().colors`, it never derives them itself.
 export { deriveSurfaceTokens, inkForBackdrop, INK_CONTRAST } from "./contract.js";
+export { surfaceAwareTheme } from "./surface-theme.js";
 
 // REQ-WSDK-PLATFORM §6: the host half of `useToast()` — the queue, the
 // auto-dismiss timing, and the themed values a toast is painted with. The
 // widget-facing hook only forwards to `ctx.toast.showToast`; the host owns the
 // surface, and sharing everything but the JSX is what keeps the web Player and
 // the Expo export rendering the same notification (CLAUDE.md §8).
+// The dialog's resolved look, for the Studio's Design > Components > Dialogs preview.
+export { resolveModalTokens, modalScopeDefaults } from "./modal-tokens.js";
+
 export {
   createToastController,
   resolveToastTokens,

package/dist/index.d.ts

@@ -3257,13 +3257,107 @@ export const Overlay: (props: {
   onRequestClose?: () => void;
   /** Panel width tier. `full` runs edge to edge. Defaults to `md`. */
   size?: "sm" | "md" | "lg" | "full";
+  /** Centred (`dialog`, the default) or anchored to the bottom edge (`sheet`). */
+  presentation?: OverlayPresentation;
   /** Set false when only an explicit control may close the overlay. */
   dismissOnBackdropPress?: boolean;
+  /**
+   * Set false when the content has its own close control: the backdrop stays
+   * pressable but leaves the tab order and the accessibility tree.
+   */
+  backdropAccessible?: boolean;
+  /** The web dialog node's role. Defaults to "dialog". No native equivalent. */
+  role?: "dialog" | "alertdialog";
+  /**
+   * Names the dialog: on the web the node that carries the role, in the
+   * exported app the panel (React Native's Modal carries no name).
+   */
   accessibilityLabel?: string;
+  /** The id of the element that names the dialog; wins over the label. Web only. */
+  accessibilityLabelledBy?: string;
   /** Label for the backdrop's dismiss target. Defaults to "Close". */
   closeAccessibilityLabel?: string;
+  /** Focused on open instead of the dialog itself. Web only; a no-op on native. */
+  initialFocusRef?: { current: any };
   /** Extra styles merged onto the themed panel. */
   style?: any;
+  /** Set on the panel. */
+  testID?: string;
+  children?: ReactNode;
+}) => any;
+
+export type OverlayPresentation = "dialog" | "sheet";
+
+/**
+ * The standard dialog, built on `<Overlay>`: a title, a close button, a body
+ * that scrolls when it is long, and a footer action row laid out below it.
+ * Its background, corner radius, padding, scrim, shadow and title colour come
+ * from the theme's `modal` scope (Design > Components > Dialogs), so every dialog in
+ * the app matches. Use it instead of hand-building a header and an action row
+ * inside a bare `<Overlay>`.
+ *
+ * A dialog that paints its own background hands what is rendered inside it a
+ * theme re-inked for that background, so SDK components and any component
+ * calling `useTheme()` inside the Modal stay readable.
+ *
+ * In the exported app the dialog pads a `sheet` by the bottom safe-area inset
+ * and a `full` dialog by the top and bottom ones, and wraps its panel in React
+ * Native's `KeyboardAvoidingView`. This is not yet verified on a device, and
+ * `KeyboardAvoidingView` inside a React Native `Modal` window is a known risk
+ * on Android: until it is verified, keep a form with text inputs in the
+ * default `dialog` presentation. A bare `<Overlay>` gets neither.
+ *
+ * @example
+ *   <Modal
+ *     visible={open}
+ *     onRequestClose={() => setOpen(false)}
+ *     title="Edit order"
+ *     footer={
+ *       <>
+ *         <Button variant="secondary" title="Cancel" onPress={() => setOpen(false)} />
+ *         <Button title="Save" onPress={save} />
+ *       </>
+ *     }
+ *   >
+ *     <TextField value={note} onChangeText={setNote} placeholder="Note" />
+ *   </Modal>
+ */
+export const Modal: (props: {
+  /** Nothing renders (and nothing is mounted) while this is false. */
+  visible?: boolean;
+  /**
+   * The close button, backdrop press, Escape (web) and Android back fire this.
+   * Omitted, no close button is drawn and only your own controls close it.
+   */
+  onRequestClose?: () => void;
+  /**
+   * Defaults to true. False while the dialog must stay open (a save in
+   * flight): no close button, and the backdrop, Escape and Android back do
+   * not fire `onRequestClose`. Only while that work runs, and always restore
+   * it: with no footer button or in-body control, nobody can close the dialog.
+   */
+  dismissible?: boolean;
+  /** With no title and no close button the dialog has no header row. */
+  title?: string;
+  /** The action buttons: one right-aligned row that wraps. Omit for no footer. */
+  footer?: ReactNode;
+  /** Centred (`dialog`, the default) or anchored to the bottom edge (`sheet`). */
+  presentation?: OverlayPresentation;
+  /** Panel width tier. `full` runs edge to edge. Defaults to `md`. */
+  size?: "sm" | "md" | "lg" | "full";
+  /** Set false when only the close button or a footer action may close it. */
+  dismissOnBackdropPress?: boolean;
+  /** Defaults to "dialog". Web only; native has no equivalent. */
+  role?: "dialog" | "alertdialog";
+  /** Focused on open instead of the dialog itself. Web only; a no-op on native. */
+  initialFocusRef?: { current: any };
+  /** Label for the close button. Defaults to "Close". */
+  closeAccessibilityLabel?: string;
+  /** Names a dialog that has no title; the title names it otherwise. */
+  accessibilityLabel?: string;
+  /** On the panel; the parts take `-close`, `-body` and `-footer`. */
+  testID?: string;
+  /** The body. It scrolls on its own: do not wrap it in a ScrollView. */
   children?: ReactNode;
 }) => any;
 

package/dist/index.js

@@ -272,6 +272,8 @@ export { Tabs } from "./tabs.js";
 export { Spinner, Skeleton } from "./loading.js";
 // A themed inline message; follows the theme's `alert` scope.
 export { Banner } from "./banner.js";
+// The standard dialog, on `<Overlay>`; follows the theme's `modal` scope.
+export { Modal } from "./modal.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/index.native.js

@@ -265,6 +265,8 @@ export { Tabs } from "./tabs.native.js";
 export { Spinner, Skeleton } from "./loading.native.js";
 // A themed inline message; follows the theme's `alert` scope.
 export { Banner } from "./banner.native.js";
+// The standard dialog, on `<Overlay>`; follows the theme's `modal` scope.
+export { Modal } from "./modal.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

package/dist/markdown-input-view.js

@@ -34,9 +34,9 @@ const TOOLS = Object.freeze([
   },
 ]);
 
-export function makeMarkdownInput(rn, RichText, Overlay) {
+export function makeMarkdownInput(rn, RichText, Modal, Button) {
   const { Text, View, Pressable, TextInput } = rn;
-  const MarkdownLinkDialog = makeMarkdownLinkDialog(rn, Overlay);
+  const MarkdownLinkDialog = makeMarkdownLinkDialog(rn, Modal, Button);
 
   function MarkdownInput({
     value,
@@ -210,7 +210,6 @@ export function makeMarkdownInput(rn, RichText, Overlay) {
         visible: linkOpen,
         onClose: () => setLinkOpen(false),
         onSubmit: insertLink,
-        tokens,
         pages,
         initialLabel: selected,
         testID,

package/dist/markdown-input.js

@@ -5,11 +5,13 @@
 import * as ReactNative from "react-native-web";
 import { makeMarkdownInput } from "./markdown-input-view.js";
 import { RichText } from "./richtext.js";
-import { Overlay } from "./overlay.js";
+import { Modal } from "./modal.js";
+import { Button } from "./button.js";
 import { TextInput } from "./primitives.js";
 
 export const MarkdownInput = makeMarkdownInput(
   { ...ReactNative, TextInput },
   RichText,
-  Overlay,
+  Modal,
+  Button,
 );

package/dist/markdown-input.native.js

@@ -5,12 +5,14 @@
 import { Text, View, Pressable, TextInput, ScrollView } from "react-native";
 import { makeMarkdownInput } from "./markdown-input-view.js";
 import { RichText } from "./richtext.native.js";
-import { Overlay } from "./overlay.native.js";
+import { Modal } from "./modal.native.js";
+import { Button } from "./button.native.js";
 
 // sc-7349: ScrollView joins the set for the link form's page list, which must
 // scroll rather than grow an app's every page past the panel.
 export const MarkdownInput = makeMarkdownInput(
   { Text, View, Pressable, TextInput, ScrollView },
   RichText,
-  Overlay,
+  Modal,
+  Button,
 );