@liiift-studio/deploy-vercel-from-sanity 1.1.0 → 1.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@liiift-studio/deploy-vercel-from-sanity",
-  "version": "1.1.0",
-  "description": "Sanity Studio plugin — trigger and monitor Vercel deployments with full status, history, and build logs. Supports Studio v3 through v6.",
+  "version": "1.2.0",
+  "description": "Sanity Studio plugin — trigger and monitor Vercel deployments with full status, history, and build logs. Supports Studio v3.30 through v6.",
   "license": "MIT",
   "author": "Liiift Studio",
   "keywords": [
@@ -22,7 +22,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js",
       "default": "./dist/index.mjs"
@@ -39,10 +39,11 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "@sanity/icons": ">=3",
-    "@sanity/ui": ">=2",
+    "@sanity/icons": ">=2 <6",
+    "@sanity/ui": ">=2 <5",
     "react": ">=18",
-    "sanity": ">=3"
+    "react-dom": ">=18",
+    "sanity": ">=3.30"
   },
   "devDependencies": {
     "@sanity/icons": "^5",
@@ -52,10 +53,15 @@
     "react": "^19",
     "sanity": "^6",
     "tsup": "^8",
-    "typescript": "^5"
+    "typescript": "^5",
+    "react-dom": "^19"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/Liiift-Studio/Deploy-Vercel-from-Sanity"
+  },
+  "sideEffects": true,
+  "engines": {
+    "node": ">=20.19"
   }
 }

package/src/compat/code.tsx

@@ -0,0 +1,29 @@
+// Monospace block — Studio's Code where available, a styled <code> block otherwise
+import type { CSSProperties, ComponentType, ReactNode } from 'react'
+import { UI, resolveExport } from './resolve'
+
+/** The real Code when the installed @sanity/ui still exports it, otherwise undefined. */
+const InstalledCode = resolveExport<ComponentType<{
+	size?: number
+	style?: CSSProperties
+	children: ReactNode
+}>>(UI, 'Code')
+
+/**
+ * Styling for the fallback Code element, approximating @sanity/ui's `size={1}`.
+ * `display: block` is included deliberately — `<code>` is inline by default while
+ * upstream's Code renders a block, so omitting it would concatenate every line.
+ */
+const FALLBACK_CODE_STYLE: CSSProperties = {
+	display: 'block',
+	fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+	fontSize: '0.8125rem',
+	lineHeight: 1.4,
+	margin: 0,
+}
+
+/** Monospace block. Uses Studio's Code where available, a plain `<code>` on @sanity/ui v4+. */
+export function Code({ style, children }: { style?: CSSProperties; children: ReactNode }): React.JSX.Element {
+	if (InstalledCode) return <InstalledCode size={1} style={style}>{children}</InstalledCode>
+	return <code style={{ ...FALLBACK_CODE_STYLE, ...style }}>{children}</code>
+}

package/src/compat/index.ts

@@ -0,0 +1,14 @@
+// Single entry point for every @sanity/ui value this plugin uses, resolved against the installed major
+export {
+	Box, Card, Flex, Grid, Text, Heading, Label, Badge, Spinner,
+	Button, TextInput, Select, Switch, Dialog, Stack,
+} from './primitives'
+export type { StackProps } from './primitives'
+export { useToast, ToastViewport } from './toast'
+export type { ToastParams, Toaster } from './toast'
+export { Tooltip } from './tooltip'
+export type { TooltipProps } from './tooltip'
+export { ActionMenu } from './menu'
+export type { ActionMenuProps, MenuAction } from './menu'
+export { Code } from './code'
+export { STACK_USES_GAP } from './resolve'

package/src/compat/menu.tsx

@@ -0,0 +1,225 @@
+// Overflow menu — Studio's MenuButton where available, a WAI-ARIA menu button implementation otherwise
+import { useCallback, useEffect, useId, useRef, useState } from 'react'
+import type { ComponentType, SVGProps } from 'react'
+import { UI, resolveExport } from './resolve'
+import { Button, Card, Flex, Stack, Text } from './primitives'
+
+/** An icon component, matching what this plugin's icon shim produces. */
+type IconComponent = ComponentType<SVGProps<SVGSVGElement>>
+
+/** One entry in an ActionMenu. Exactly one of `onClick` or `href` drives the behaviour. */
+export type MenuAction =
+	| { key?: string; text: string; icon: IconComponent; tone?: 'critical'; onClick: () => void; href?: never }
+	| { key?: string; text: string; icon: IconComponent; tone?: 'critical'; href: string; onClick?: never }
+
+/** Props for the compat ActionMenu — a declarative item list rather than nested JSX. */
+export type ActionMenuProps = {
+	/** Stable DOM id for the trigger. */
+	id: string
+	/** Accessible name for the trigger, which is icon-only. */
+	label: string
+	items: MenuAction[]
+	buttonIcon: IconComponent
+}
+
+const InstalledMenuButton = resolveExport<ComponentType<Record<string, unknown>>>(UI, 'MenuButton')
+const InstalledMenu = resolveExport<ComponentType<Record<string, unknown>>>(UI, 'Menu')
+const InstalledMenuItem = resolveExport<ComponentType<Record<string, unknown>>>(UI, 'MenuItem')
+
+/** Whether the installed @sanity/ui still exports the full menu trio. */
+const INSTALLED_MENU = InstalledMenuButton && InstalledMenu && InstalledMenuItem
+	? { MenuButton: InstalledMenuButton, Menu: InstalledMenu, MenuItem: InstalledMenuItem }
+	: null
+
+/** Stable identity for an item, used for React keys and focus tracking. Labels can repeat; keys should not. */
+const itemKey = (item: MenuAction, index: number): string => item.key ?? `${index}-${item.text}`
+
+/**
+ * Overflow menu. Uses Studio's MenuButton where available and otherwise implements
+ * the WAI-ARIA menu button pattern locally: focus moves into the menu on open,
+ * Arrow/Home/End move between items with a roving tabindex, Escape and Tab close
+ * and return focus to the trigger.
+ *
+ * The item list is snapshotted while the menu is open, so background polling
+ * cannot insert or remove rows under the pointer.
+ */
+export function ActionMenu({ id, label, items, buttonIcon }: ActionMenuProps): React.JSX.Element {
+	const menuId = useId()
+	const [open, setOpen] = useState(false)
+	const [activeIndex, setActiveIndex] = useState(0)
+	const wrapRef = useRef<HTMLDivElement>(null)
+	const triggerRef = useRef<HTMLButtonElement>(null)
+	const itemRefs = useRef<(HTMLElement | null)[]>([])
+
+	// Snapshot taken at open time — the live `items` array is rebuilt on every poll.
+	const [frozenItems, setFrozenItems] = useState<MenuAction[]>(items)
+	const shownItems = open ? frozenItems : items
+
+	/** Close the menu and hand focus back to the trigger, as the menu button pattern requires. */
+	const close = useCallback((returnFocus = true) => {
+		setOpen(false)
+		if (returnFocus) triggerRef.current?.focus()
+	}, [])
+
+	const openMenu = useCallback((index: number) => {
+		setFrozenItems(items)
+		setActiveIndex(index)
+		setOpen(true)
+	}, [items])
+
+	// Move DOM focus to follow the active item while the menu is open.
+	useEffect(() => {
+		if (!open || INSTALLED_MENU) return
+		itemRefs.current[activeIndex]?.focus()
+	}, [open, activeIndex])
+
+	// Fallback only — dismiss on outside pointer down. Escape and Tab are handled on the menu itself
+	// so they do not swallow keys belonging to any dialog the tool has open.
+	useEffect(() => {
+		if (INSTALLED_MENU || !open) return
+		const onPointerDown = (e: MouseEvent) => {
+			if (!wrapRef.current?.contains(e.target as Node)) setOpen(false)
+		}
+		document.addEventListener('mousedown', onPointerDown)
+		return () => document.removeEventListener('mousedown', onPointerDown)
+	}, [open])
+
+	const runAction = useCallback((item: MenuAction) => {
+		close()
+		item.onClick?.()
+	}, [close])
+
+	if (INSTALLED_MENU) {
+		const { MenuButton, Menu, MenuItem } = INSTALLED_MENU
+		return (
+			<MenuButton
+				id={id}
+				button={<Button mode="ghost" icon={buttonIcon} padding={2} aria-label={label} />}
+				popover={{ placement: 'bottom-end' }}
+				menu={
+					<Menu>
+						{items.map((item, i) => (
+							<MenuItem
+								key={itemKey(item, i)}
+								text={item.text}
+								icon={item.icon}
+								tone={item.tone}
+								{...(item.href
+									? { as: 'a', href: item.href, target: '_blank', rel: 'noreferrer' }
+									: { onClick: item.onClick })}
+							/>
+						))}
+					</Menu>
+				}
+			/>
+		)
+	}
+
+	/** Arrow/Home/End/Escape/Tab handling for the open menu, per the WAI-ARIA menu button pattern. */
+	const onMenuKeyDown = (e: React.KeyboardEvent) => {
+		const last = shownItems.length - 1
+		if (e.key === 'Escape') { e.stopPropagation(); close(); return }
+		if (e.key === 'Tab') { close(false); return }
+		if (e.key === 'ArrowDown') { e.preventDefault(); setActiveIndex(i => (i >= last ? 0 : i + 1)); return }
+		if (e.key === 'ArrowUp') { e.preventDefault(); setActiveIndex(i => (i <= 0 ? last : i - 1)); return }
+		if (e.key === 'Home') { e.preventDefault(); setActiveIndex(0); return }
+		if (e.key === 'End') { e.preventDefault(); setActiveIndex(last); return }
+	}
+
+	const onTriggerKeyDown = (e: React.KeyboardEvent) => {
+		if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') { e.preventDefault(); openMenu(0) }
+		else if (e.key === 'ArrowUp') { e.preventDefault(); openMenu(items.length - 1) }
+	}
+
+	return (
+		<div ref={wrapRef} style={{ position: 'relative' }}>
+			<Button
+				ref={triggerRef}
+				mode="ghost"
+				icon={buttonIcon}
+				padding={2}
+				id={id}
+				aria-label={label}
+				aria-haspopup="menu"
+				aria-expanded={open}
+				aria-controls={open ? menuId : undefined}
+				onClick={() => (open ? close() : openMenu(0))}
+				onKeyDown={onTriggerKeyDown}
+			/>
+			{open && (
+				<Card
+					id={menuId}
+					radius={2}
+					shadow={3}
+					padding={1}
+					role="menu"
+					aria-labelledby={id}
+					onKeyDown={onMenuKeyDown}
+					style={{ position: 'absolute', top: '100%', right: 0, marginTop: 4, zIndex: 1000, minWidth: 200 }}
+				>
+					{/* role="none" so the menu still directly owns its menuitem children. */}
+					<Stack space={1} role="none">
+						{shownItems.map((item, i) => {
+							const Icon = item.icon
+							const row = (
+								<Flex align="center" gap={2} paddingX={2} paddingY={2}>
+									<Icon width="1em" height="1em" aria-hidden="true" />
+									<Text size={1}>{item.text}</Text>
+								</Flex>
+							)
+							// A destructive item is wrapped in a critical-tone Card so it picks up Sanity's
+							// validated foreground/background pairing rather than a hand-picked colour.
+							const content = item.tone === 'critical'
+								? <Card tone="critical" radius={1}>{row}</Card>
+								: row
+							const shared = {
+								role: 'menuitem',
+								// Roving tabindex — the menu is one tab stop, arrows move within it.
+								tabIndex: i === activeIndex ? 0 : -1,
+								ref: (el: HTMLElement | null) => { itemRefs.current[i] = el },
+								onMouseEnter: () => setActiveIndex(i),
+								style: {
+									display: 'block',
+									width: '100%',
+									textAlign: 'left' as const,
+									cursor: 'pointer',
+									borderRadius: 3,
+									background: 'none',
+									border: 0,
+									padding: 0,
+									font: 'inherit',
+									color: 'inherit',
+									textDecoration: 'none',
+									// Card suppresses its own focus ring, so the active item draws one explicitly.
+									outline: i === activeIndex ? '2px solid var(--card-focus-ring-color, currentColor)' : 'none',
+									outlineOffset: -2,
+								},
+							}
+							return item.href ? (
+								<a
+									key={itemKey(item, i)}
+									{...shared}
+									href={item.href}
+									target="_blank"
+									rel="noreferrer"
+									onClick={() => close(false)}
+								>
+									{content}
+								</a>
+							) : (
+								<button
+									key={itemKey(item, i)}
+									{...shared}
+									type="button"
+									onClick={() => runAction(item)}
+								>
+									{content}
+								</button>
+							)
+						})}
+					</Stack>
+				</Card>
+			)}
+		</div>
+	)
+}

package/src/compat/primitives.tsx

@@ -0,0 +1,93 @@
+// Layout and control primitives resolved from the installed @sanity/ui, with plain-DOM fallbacks
+import { createElement, forwardRef } from 'react'
+import type { ComponentType, ReactNode } from 'react'
+import type * as SanityUi from '@sanity/ui'
+import { UI, resolveExport, STACK_USES_GAP } from './resolve'
+
+/** Loose props for a resolved @sanity/ui primitive — upstream types vary by major. */
+type AnyProps = Record<string, unknown>
+
+/**
+ * Build a last-resort component that renders a plain DOM element, used when the
+ * installed @sanity/ui no longer exports a name this plugin needs. It drops the
+ * design-system props it cannot honour so React does not warn about unknown
+ * attributes, and keeps children so the tool stays usable rather than blank.
+ *
+ * @param tag DOM element to render in place of the missing component.
+ */
+function domFallback(tag: string): ComponentType<AnyProps> {
+	const Fallback = forwardRef<HTMLElement, AnyProps>(function SanityUiFallback(props, ref) {
+		const { children, style, id, className, onClick, href, title, ...rest } = props
+		// Forward only attributes that are meaningful on a bare element.
+		const passthrough: AnyProps = { style, id, className, onClick, href, title, ref }
+		for (const key of ['role', 'type', 'value', 'checked', 'placeholder', 'disabled', 'onChange', 'onKeyDown']) {
+			if (key in rest) passthrough[key] = rest[key]
+		}
+		for (const key of Object.keys(rest)) {
+			if (key.startsWith('aria-') || key.startsWith('data-')) passthrough[key] = rest[key]
+		}
+		return createElement(tag, passthrough, children as ReactNode)
+	})
+	Fallback.displayName = `SanityUiFallback(${tag})`
+	return Fallback as unknown as ComponentType<AnyProps>
+}
+
+/**
+ * Resolve one @sanity/ui export, falling back to a DOM element when the installed
+ * major no longer provides it. Keeps a relocated export from turning into a
+ * module-evaluation failure that stops the whole Studio from booting.
+ *
+ * @param name Export name on the @sanity/ui barrel.
+ * @param tag  DOM element to degrade to.
+ */
+function primitive(name: string, tag: string): ComponentType<AnyProps> {
+	return resolveExport<ComponentType<AnyProps>>(UI, name) ?? domFallback(tag)
+}
+
+/*
+ * The value comes through the seam so a relocated export degrades instead of
+ * failing to link; the *type* is taken from the installed @sanity/ui so call
+ * sites keep full prop checking. If a future major tombstones one of these as
+ * `never` — as v4 did to Tooltip and Menu — the assertion makes every call site
+ * a build error rather than a silent runtime blank.
+ */
+export const Box = primitive('Box', 'div') as typeof SanityUi.Box
+export const Card = primitive('Card', 'div') as typeof SanityUi.Card
+export const Flex = primitive('Flex', 'div') as typeof SanityUi.Flex
+export const Grid = primitive('Grid', 'div') as typeof SanityUi.Grid
+export const Text = primitive('Text', 'span') as typeof SanityUi.Text
+export const Heading = primitive('Heading', 'h2') as typeof SanityUi.Heading
+export const Label = primitive('Label', 'label') as typeof SanityUi.Label
+export const Badge = primitive('Badge', 'span') as typeof SanityUi.Badge
+export const Spinner = primitive('Spinner', 'span') as typeof SanityUi.Spinner
+export const Button = primitive('Button', 'button') as typeof SanityUi.Button
+export const TextInput = primitive('TextInput', 'input') as typeof SanityUi.TextInput
+export const Select = primitive('Select', 'select') as typeof SanityUi.Select
+export const Switch = primitive('Switch', 'input') as typeof SanityUi.Switch
+export const Dialog = primitive('Dialog', 'div') as unknown as typeof SanityUi.Dialog
+
+const SanityStack = primitive('Stack', 'div')
+
+/** Props for the compat Stack. Mirrors the upstream surface this plugin uses. */
+export type StackProps = {
+	/** Spacing step on Sanity's scale, forwarded as `gap` or `space` per installed major. */
+	space?: number
+	padding?: number
+	paddingX?: number
+	paddingY?: number
+	flex?: number
+	style?: React.CSSProperties
+	className?: string
+	role?: string
+	children?: ReactNode
+}
+
+/**
+ * Vertical stack. Forwards `space` on @sanity/ui v2 and v3 and `gap` on v4+, so
+ * one call site spells spacing correctly on either major. See STACK_USES_GAP for
+ * how the two are told apart.
+ */
+export function Stack({ space, children, ...rest }: StackProps): React.JSX.Element {
+	const spacing = space === undefined ? {} : STACK_USES_GAP ? { gap: space } : { space }
+	return <SanityStack {...rest} {...spacing}>{children}</SanityStack>
+}

package/src/compat/resolve.ts

@@ -0,0 +1,55 @@
+// Reads the installed @sanity/ui and @sanity/icons namespaces so relocated exports degrade instead of failing to link
+import * as sanityUi from '@sanity/ui'
+import * as sanityIcons from '@sanity/icons'
+
+/**
+ * The installed namespaces, read through an index signature.
+ *
+ * Both packages have split their barrels: @sanity/icons v5 removed the named
+ * `*Icon` exports, and @sanity/ui v4 moved Tooltip, Menu, MenuButton, MenuItem,
+ * Code, Popover and useToast into subpath entry points. Those subpaths do not
+ * exist on the earlier majors this plugin supports, so neither import shape works
+ * across the range.
+ *
+ * Both packages also still *declare* the moved names in their `.d.ts` — typed
+ * `never`, with a deprecation note — so a static named import type-checks at the
+ * import site and only fails when the value is used or evaluated. Reading the
+ * namespace turns a link-time failure into a value this code can branch on.
+ *
+ * Verified through Vite/Rollup: aliasing the namespace into a binding is what
+ * forces bundlers to materialise a real namespace object rather than rewriting
+ * member access into named bindings. Do not inline these back into direct
+ * `sanityUi.x` access without re-checking the emitted bundle.
+ */
+export const UI = sanityUi as unknown as Record<string, unknown>
+export const ICONS = sanityIcons as unknown as Record<string, unknown>
+
+/**
+ * Look up one export by name, returning undefined when the installed major no
+ * longer provides it.
+ *
+ * @param ns   Namespace to read — {@link UI} or {@link ICONS}.
+ * @param name Exact export name, e.g. `Tooltip`.
+ */
+export function resolveExport<T>(ns: Record<string, unknown>, name: string): T | undefined {
+	const value = ns[name]
+	// A deprecation tombstone can be present but not callable; only accept usable values.
+	return typeof value === 'function' || (typeof value === 'object' && value !== null)
+		? (value as T)
+		: undefined
+}
+
+/**
+ * Whether the installed @sanity/ui expects `gap` rather than `space` on Stack.
+ *
+ * v4 renamed the prop, typed the old name `never`, and ignores it at runtime —
+ * so guessing wrong collapses every vertical gap silently. It also rewrote Stack
+ * from a `forwardRef` component into a plain function generic, in the same
+ * release. Probing the shape of Stack itself keeps the signal attached to the
+ * component whose prop is being chosen, rather than to an unrelated export.
+ *
+ * Verified: forwardRef object on @sanity/ui 2.16.27 and 3.5.3, plain function on
+ * 4.0.5. Passing both prop names is not an option — `gap` leaks to the DOM as a
+ * stray attribute on v2, and `space` leaks on v4.
+ */
+export const STACK_USES_GAP = typeof (UI.Stack as unknown) === 'function'

package/src/compat/toast.tsx

@@ -0,0 +1,173 @@
+// Toast delivery — Studio's own toast system where available, a local live-region viewport otherwise
+import { useCallback, useEffect, useState } from 'react'
+import type { ReactNode } from 'react'
+import { UI, resolveExport } from './resolve'
+import { Box, Button, Card, Flex, Stack, Text } from './primitives'
+import { CloseIcon } from '../icons'
+
+/** A toast request — the subset of @sanity/ui's ToastParams this plugin uses. */
+export type ToastParams = {
+	status?: 'success' | 'error' | 'warning' | 'info'
+	title?: ReactNode
+	description?: ReactNode
+}
+
+/** The object returned by useToast. Only `push` is used here. */
+export type Toaster = { push: (params: ToastParams) => void }
+
+/** A queued fallback toast. `id` is a monotonic counter, unique for the session. */
+type LocalToast = ToastParams & { id: number }
+
+/** How long a non-error fallback toast stays on screen, in milliseconds. */
+const LOCAL_TOAST_MS = 6000
+
+/** Most toasts kept on screen at once; older ones are dropped so the column cannot grow past the viewport. */
+const MAX_VISIBLE_TOASTS = 4
+
+/** Stacking index for the fallback viewport. High enough to clear Studio chrome, since it is not in Sanity's Layer stack. */
+const TOAST_Z_INDEX = 1000000
+
+/** Card tone per toast status, used only by the fallback viewport. */
+const LOCAL_TOAST_TONE: Record<string, 'positive' | 'critical' | 'caution' | 'primary'> = {
+	success: 'positive',
+	error: 'critical',
+	warning: 'caution',
+	info: 'primary',
+}
+
+/** Statuses that stay until dismissed — they carry text the user is expected to act on. */
+const PERSISTENT_STATUSES = new Set(['error', 'warning'])
+
+let nextToastId = 0
+let localToasts: LocalToast[] = []
+const toastListeners = new Set<(toasts: LocalToast[]) => void>()
+const dismissTimers = new Map<number, ReturnType<typeof setTimeout>>()
+
+/** Publish the current fallback queue to every mounted viewport. */
+function emitToasts(): void {
+	for (const listener of toastListeners) listener(localToasts)
+}
+
+/** Remove one fallback toast and cancel its pending auto-dismiss. */
+function removeLocalToast(id: number): void {
+	const timer = dismissTimers.get(id)
+	if (timer) {
+		clearTimeout(timer)
+		dismissTimers.delete(id)
+	}
+	localToasts = localToasts.filter(t => t.id !== id)
+	emitToasts()
+}
+
+/** Start (or restart) the auto-dismiss countdown for one toast. Persistent statuses are left alone. */
+function scheduleDismiss(id: number, status: ToastParams['status']): void {
+	if (PERSISTENT_STATUSES.has(status ?? 'info')) return
+	const existing = dismissTimers.get(id)
+	if (existing) clearTimeout(existing)
+	dismissTimers.set(id, setTimeout(() => removeLocalToast(id), LOCAL_TOAST_MS))
+}
+
+/** Queue a fallback toast, trimming the oldest if the column is already full. */
+function pushLocalToast(params: ToastParams): void {
+	const toast: LocalToast = { ...params, id: nextToastId++ }
+	localToasts = [...localToasts, toast].slice(-MAX_VISIBLE_TOASTS)
+	emitToasts()
+	scheduleDismiss(toast.id, toast.status)
+}
+
+/** The real hook when the installed @sanity/ui still exports it, otherwise undefined. */
+const installedUseToast = resolveExport<() => Toaster>(UI, 'useToast')
+
+/** Stable fallback toaster — identity never changes, so it is safe in dependency arrays. */
+const localToaster: Toaster = { push: pushLocalToast }
+
+/**
+ * Push toasts through Studio's toast system where available, or through
+ * {@link ToastViewport} on @sanity/ui v4+.
+ *
+ * The branch is decided once at module load, so the hook-call order of any
+ * component using this is constant across renders.
+ */
+export function useToast(): Toaster {
+	const real = installedUseToast
+	if (real) return real()
+	return localToaster
+}
+
+/**
+ * Live region for fallback toasts.
+ *
+ * The wrapper stays mounted and empty when there is nothing to show: assistive
+ * tech has to observe a live region *before* content lands in it, so a region
+ * created and populated in the same commit is routinely missed. Renders nothing
+ * at all when the installed @sanity/ui provides its own toast system.
+ */
+export function ToastViewport(): React.JSX.Element | null {
+	const [toasts, setToasts] = useState<LocalToast[]>(localToasts)
+
+	useEffect(() => {
+		if (installedUseToast) return
+		toastListeners.add(setToasts)
+		// Re-read after subscribing: a toast pushed between render and commit would otherwise be missed.
+		setToasts(localToasts)
+		return () => { toastListeners.delete(setToasts) }
+	}, [])
+
+	const hold = useCallback((id: number) => {
+		const timer = dismissTimers.get(id)
+		if (timer) {
+			clearTimeout(timer)
+			dismissTimers.delete(id)
+		}
+	}, [])
+
+	if (installedUseToast) return null
+
+	return (
+		<Box
+			role="status"
+			aria-live="polite"
+			aria-atomic={false}
+			// pointer-events is released so the fixed column cannot swallow clicks on the tool beneath it.
+			style={{
+				position: 'fixed',
+				bottom: 16,
+				right: 16,
+				zIndex: TOAST_Z_INDEX,
+				width: 'min(360px, calc(100vw - 32px))',
+				pointerEvents: 'none',
+			}}
+		>
+			<Stack space={2}>
+				{toasts.map(toast => (
+					<Card
+						key={toast.id}
+						padding={3}
+						radius={2}
+						shadow={3}
+						tone={LOCAL_TOAST_TONE[toast.status ?? 'info'] ?? 'primary'}
+						style={{ pointerEvents: 'auto' }}
+						onMouseEnter={() => hold(toast.id)}
+						onFocusCapture={() => hold(toast.id)}
+						onMouseLeave={() => scheduleDismiss(toast.id, toast.status)}
+					>
+						<Flex align="flex-start" gap={3}>
+							<Stack space={2} flex={1}>
+								{toast.title && <Text size={1} weight="semibold">{toast.title}</Text>}
+								{toast.description && <Text size={1} muted>{toast.description}</Text>}
+							</Stack>
+							<Button
+								mode="bleed"
+								padding={2}
+								icon={CloseIcon}
+								text=""
+								aria-label="Dismiss notification"
+								onClick={() => removeLocalToast(toast.id)}
+							/>
+						</Flex>
+					</Card>
+				))}
+			</Stack>
+		</Box>
+	)
+}