@adea-ai/ui 0.94.0 → 0.95.1

package/dist/r/src/styles/base.css

@@ -250,6 +250,18 @@
   }
 }
 
+/**
+ * Opt into the stable 2xl control rung only when a coarse pointer is available.
+ * `any-pointer` intentionally includes hybrid devices without changing the
+ * glyph or desktop density of the selected Button size.
+ */
+@utility touch-target-comfortable {
+  @media (any-pointer: coarse) {
+    min-inline-size: var(--control-height-2xl);
+    min-block-size: var(--control-height-2xl);
+  }
+}
+
 /**
  * The drag region of a frameless desktop window.
  *
@@ -422,9 +434,9 @@
   }
 }
 
-/* The glass treatment used by the top bar, the rail, and floating overlays.
-   `--glass-*` are private: a consumer chooses *whether* to be glassy through
-   the component prop, not by reaching for these. */
+/* Glass treatments used by the top bar, rail, scene-control groups and floating
+   overlays. Consumers use the owning component; shared composites use the
+   named utility instead of restyling a primitive. */
 @utility glass-panel {
   background: color-mix(in oklch, var(--chrome) calc(var(--chrome-alpha) * 100%), transparent);
   backdrop-filter: blur(18px) saturate(1.6);
@@ -438,6 +450,12 @@
   -webkit-backdrop-filter: blur(12px) saturate(1.4);
 }
 
+@utility glass-scrim {
+  background: color-mix(in oklch, var(--scrim) 20%, transparent);
+  backdrop-filter: blur(2px);
+  -webkit-backdrop-filter: blur(2px);
+}
+
 /* The focus ring. Applied by components that cannot use the global outline
    because they need the ring to follow their own radius. */
 @utility focus-ring {
@@ -657,7 +675,8 @@
 
 @media (prefers-reduced-transparency: reduce) {
   .glass-panel,
-  .glass-surface {
+  .glass-surface,
+  .glass-scrim {
     backdrop-filter: none !important;
     -webkit-backdrop-filter: none !important;
     background: var(--background) !important;
@@ -670,18 +689,19 @@
   }
 
   .glass-panel,
-  .glass-surface {
+  .glass-surface,
+  .glass-scrim {
     background: var(--background) !important;
     border: 1px solid var(--foreground) !important;
   }
 }
 
-/* An engine without backdrop-filter would render the glass tint alone, which
-   is 3-8% alpha — effectively a transparent panel. Fall back to a solid
-   surface instead, keeping borders and shadows so panels stay delimited. */
+/* Without backdrop-filter there is no blurred context behind a glass surface.
+   Fall back to a solid surface so glass panels and scrim groups stay legible. */
 @supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
   .glass-panel,
-  .glass-surface {
+  .glass-surface,
+  .glass-scrim {
     background: var(--background) !important;
   }
 }

package/dist/r/src/styles/theme.css

@@ -582,6 +582,7 @@
   --control-height-md: 2rem; /* 32px — form default */
   --control-height-lg: 2.25rem; /* 36px */
   --control-height-xl: 2.5rem; /* 40px */
+  --control-height-2xl: 3rem; /* 48px — stable touch target */
 
   --control-padding-2xs: 0.375rem;
   --control-padding-xs: 0.5rem;
@@ -589,6 +590,7 @@
   --control-padding-md: 0.75rem;
   --control-padding-lg: 0.875rem;
   --control-padding-xl: 1rem;
+  --control-padding-2xl: 1.125rem;
 
   --row-height-sm: 1.75rem;
   --row-height-md: 2rem;
@@ -646,14 +648,15 @@
   --z-toast: 180;
 }
 
-/* Compact density: the whole control ladder one rung tighter.
+/* Compact density: the standard control ladder one rung tighter.
  *
  * It is a *shift* rather than a second set of numbers chosen by eye, so the
  * relationship between the rungs is identical at either density and a control keeps
  * its place in the ladder. Height moves by 4px per rung and padding by 2px, which is
  * the step each already uses, and the row heights move by the same 4px. A `sm`
  * control goes from 28px to 24px — the `xs` control's comfortable height. That is the
- * intended meaning, not an oversight.
+ * intended meaning, not an oversight. The `2xl` touch target is intentionally
+ * omitted here so it stays at least 48px at either density.
  *
  * 16px at `2xs` is the floor. One rung below it would be 12px, under the minimum
  * comfortable touch target, so the ladder compresses from the bottom rather than
@@ -833,6 +836,7 @@
   --height-control-md: var(--control-height-md);
   --height-control-lg: var(--control-height-lg);
   --height-control-xl: var(--control-height-xl);
+  --height-control-2xl: var(--control-height-2xl);
   /* Tailwind `size-*` prefers --size-* and then --spacing-*. Without this
      bridge, square icon controls use the padding ladder below for both axes.
      Height, square size and inline padding remain distinct semantic contracts. */
@@ -842,6 +846,7 @@
   --size-control-md: var(--control-height-md);
   --size-control-lg: var(--control-height-lg);
   --size-control-xl: var(--control-height-xl);
+  --size-control-2xl: var(--control-height-2xl);
   --height-row-sm: var(--row-height-sm);
   --height-row-md: var(--row-height-md);
   --height-row-lg: var(--row-height-lg);
@@ -855,6 +860,7 @@
   --spacing-control-md: var(--control-padding-md);
   --spacing-control-lg: var(--control-padding-lg);
   --spacing-control-xl: var(--control-padding-xl);
+  --spacing-control-2xl: var(--control-padding-2xl);
 
   --width-rail: var(--rail-width);
   --width-rail-expanded: var(--rail-width-expanded);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.94.0",
+  "version": "0.95.1",
   "description": "The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.",
   "keywords": [
     "adea",
@@ -103,6 +103,7 @@
     "check:packed-layout": "node --test scripts/check-packed-layout-process.test.mjs && node scripts/check-packed-layout.mjs",
     "check:packed-consumer": "bun scripts/check-packed-consumer.ts",
     "check:packed-list-row": "bun scripts/check-packed-list-row.ts",
+    "check:packed-scene-controls": "bun scripts/check-packed-scene-controls.ts",
     "check:packed-conversation": "bun scripts/check-packed-conversation.ts",
     "check:packed-transcript": "bun scripts/check-packed-transcript.ts",
     "check:packed-layout-renderer": "bun scripts/check-packed-layout-renderer.ts",

package/registry.json

@@ -1962,6 +1962,30 @@
         }
       ]
     },
+    {
+      "name": "scene-controls",
+      "type": "registry:ui",
+      "title": "Scene Controls",
+      "description": "Shared host-neutral scene movement, jump and zoom controls.",
+      "dependencies": [
+        "lucide-solid@^1.48.0"
+      ],
+      "registryDependencies": [
+        "@adea-ai/ui/action-button"
+      ],
+      "files": [
+        {
+          "path": "src/components/composites/scene-controls/index.ts",
+          "type": "registry:ui",
+          "target": "components/composites/scene-controls/index.ts"
+        },
+        {
+          "path": "src/components/composites/scene-controls/scene-controls.tsx",
+          "type": "registry:ui",
+          "target": "components/composites/scene-controls/scene-controls.tsx"
+        }
+      ]
+    },
     {
       "name": "settings",
       "type": "registry:ui",

package/src/components/composites/action-button/action-button.tsx

@@ -84,6 +84,7 @@ export function ActionButton<T extends ValidComponent = 'button'>(props: ActionB
     'as',
     'variant',
     'size',
+    'touchTarget',
     'class',
     'children',
     'disabled',
@@ -106,6 +107,7 @@ export function ActionButton<T extends ValidComponent = 'button'>(props: ActionB
     ...rest,
     variant: local.variant,
     size: local.size,
+    touchTarget: local.touchTarget,
     class: [local.class, local.tooltip && disabled() && 'aria-disabled:pointer-events-auto']
       .filter(Boolean)
       .join(' '),

package/src/components/composites/scene-controls/index.ts

@@ -0,0 +1,7 @@
+/** Shared host-neutral scene movement, jump and zoom controls. */
+export {
+  SceneControls,
+  type SceneControlLabels,
+  type SceneControlsProps,
+  type SceneMovementDirection,
+} from './scene-controls'

package/src/components/composites/scene-controls/scene-controls.tsx

@@ -0,0 +1,282 @@
+import { ArrowDown, ArrowLeft, ArrowRight, ArrowUp, ZoomIn, ZoomOut } from 'lucide-solid'
+import { createSignal, onCleanup, Show, type JSX } from 'solid-js'
+import { ActionButton } from '../action-button'
+
+/** A host-neutral direction reported while a movement control is held. */
+export type SceneMovementDirection = 'forward' | 'left' | 'backward' | 'right'
+
+/** Accessible names and tooltip text for the shared scene controls. */
+export type SceneControlLabels = {
+  movementGroup: string
+  forward: string
+  forwardTooltip: string
+  left: string
+  leftTooltip: string
+  backward: string
+  backwardTooltip: string
+  right: string
+  rightTooltip: string
+  jump: string
+  jumpTooltip: string
+  zoomGroup: string
+  zoomOut: string
+  zoomIn: string
+}
+
+const DEFAULT_LABELS: SceneControlLabels = {
+  movementGroup: 'Scene movement controls',
+  forward: 'Move forward',
+  forwardTooltip: 'Hold to move forward',
+  left: 'Move left',
+  leftTooltip: 'Hold to move left',
+  backward: 'Move backward',
+  backwardTooltip: 'Hold to move backward',
+  right: 'Move right',
+  rightTooltip: 'Hold to move right',
+  jump: 'Jump',
+  jumpTooltip: 'Hold to jump',
+  zoomGroup: 'Camera zoom',
+  zoomOut: 'Zoom out',
+  zoomIn: 'Zoom in',
+}
+
+const pointerSource = (pointerId: number) => `pointer:${pointerId}`
+const keySource = (key: string) => `key:${key}`
+
+export type SceneControlsProps = {
+  /** Called on the transition into and out of each held movement direction. */
+  onMovementChange?: (direction: SceneMovementDirection, pressed: boolean) => void
+  /** Called when the jump action becomes pressed or released. */
+  onJumpChange?: (pressed: boolean) => void
+  /** Called once when zoom in is activated. */
+  onZoomIn?: () => void
+  /** Called once when zoom out is activated. */
+  onZoomOut?: () => void
+  /** Override the default English accessible names and tooltip copy. */
+  labels?: Partial<SceneControlLabels>
+}
+
+type HoldActionProps = {
+  label: string
+  tooltip: string
+  createChangeCallback: () => (pressed: boolean) => void
+  children: JSX.Element
+}
+
+/**
+ * A held action that reports one down/up pair across pointer and keyboard input.
+ *
+ * The arrangement, rounded scrim group surfaces and release policy translate
+ * Adea's on-screen scene controls; host key synthesis and scene APIs are replaced
+ * by callbacks.
+ */
+function HoldAction(props: HoldActionProps) {
+  const [pressed, setPressed] = createSignal(false)
+  const sources = new Set<string>()
+  let activeChangeCallback: ((pressed: boolean) => void) | undefined
+
+  const press = (source: string) => {
+    if (sources.has(source)) return
+    const wasPressed = sources.size > 0
+    sources.add(source)
+    if (!wasPressed) {
+      setPressed(true)
+      activeChangeCallback = props.createChangeCallback()
+      activeChangeCallback(true)
+    }
+  }
+
+  const release = (source: string) => {
+    if (!sources.delete(source) || sources.size > 0) return
+    setPressed(false)
+    const callback = activeChangeCallback
+    activeChangeCallback = undefined
+    callback?.(false)
+  }
+
+  const releaseAll = () => {
+    if (sources.size === 0) return
+    sources.clear()
+    setPressed(false)
+    const callback = activeChangeCallback
+    activeChangeCallback = undefined
+    callback?.(false)
+  }
+
+  const onWindowPointerUp = (event: PointerEvent) => release(pointerSource(event.pointerId))
+  const onWindowBlur = () => releaseAll()
+
+  if (typeof window !== 'undefined') {
+    window.addEventListener('pointerup', onWindowPointerUp)
+    window.addEventListener('blur', onWindowBlur)
+  }
+
+  onCleanup(() => {
+    releaseAll()
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('pointerup', onWindowPointerUp)
+      window.removeEventListener('blur', onWindowBlur)
+    }
+  })
+
+  return (
+    <ActionButton
+      type="button"
+      variant="secondary"
+      size="icon-2xl"
+      aria-label={props.label}
+      aria-pressed={pressed()}
+      tooltip={props.tooltip}
+      class="touch-none select-none"
+      onContextMenu={(event) => event.preventDefault()}
+      onPointerDown={(event) => {
+        if (event.button !== 0) return
+        event.preventDefault()
+        const source = pointerSource(event.pointerId)
+        if (sources.has(source)) return
+        try {
+          event.currentTarget.setPointerCapture(event.pointerId)
+        } catch {
+          // Pointer capture is not available in every embedded browser. The
+          // window pointerup fallback still closes this held action.
+        }
+        press(source)
+      }}
+      onPointerUp={(event) => release(pointerSource(event.pointerId))}
+      onPointerCancel={(event) => release(pointerSource(event.pointerId))}
+      onLostPointerCapture={(event) => release(pointerSource(event.pointerId))}
+      onKeyDown={(event) => {
+        if (event.key !== ' ' && event.key !== 'Enter') return
+        event.preventDefault()
+        press(keySource(event.key))
+      }}
+      onKeyUp={(event) => {
+        if (event.key !== ' ' && event.key !== 'Enter') return
+        event.preventDefault()
+        release(keySource(event.key))
+      }}
+      onBlur={releaseAll}
+      onClick={(event) => {
+        // Assistive technology can activate a button without pointer or keyboard
+        // down/up events. Treat that activation as one short held action.
+        if (event.detail !== 0 || sources.size > 0) return
+        press('activation')
+        release('activation')
+      }}
+    >
+      {props.children}
+    </ActionButton>
+  )
+}
+
+/**
+ * Shared movement, jump and zoom controls for a host-rendered scene.
+ *
+ * Movement and jump callbacks receive pressed/released state from pointer and
+ * keyboard input. Zoom callbacks fire on activation. The host owns positioning,
+ * scene state and camera behavior.
+ */
+export function SceneControls(props: SceneControlsProps) {
+  const labels = () => ({ ...DEFAULT_LABELS, ...props.labels })
+
+  return (
+    <div class="flex min-w-0 max-w-full flex-wrap items-end gap-3">
+      <Show when={props.onMovementChange}>
+        <div
+          role="group"
+          aria-label={labels().movementGroup}
+          class="glass-scrim grid min-w-0 max-w-full grid-cols-3 gap-1.5 rounded-3xl p-2"
+        >
+          <span aria-hidden="true" />
+          <HoldAction
+            label={labels().forward}
+            tooltip={labels().forwardTooltip}
+            createChangeCallback={() => {
+              const callback = props.onMovementChange
+              return (pressed) => callback?.('forward', pressed)
+            }}
+          >
+            <ArrowUp aria-hidden="true" />
+          </HoldAction>
+          <span aria-hidden="true" />
+          <HoldAction
+            label={labels().left}
+            tooltip={labels().leftTooltip}
+            createChangeCallback={() => {
+              const callback = props.onMovementChange
+              return (pressed) => callback?.('left', pressed)
+            }}
+          >
+            <ArrowLeft aria-hidden="true" />
+          </HoldAction>
+          <HoldAction
+            label={labels().backward}
+            tooltip={labels().backwardTooltip}
+            createChangeCallback={() => {
+              const callback = props.onMovementChange
+              return (pressed) => callback?.('backward', pressed)
+            }}
+          >
+            <ArrowDown aria-hidden="true" />
+          </HoldAction>
+          <HoldAction
+            label={labels().right}
+            tooltip={labels().rightTooltip}
+            createChangeCallback={() => {
+              const callback = props.onMovementChange
+              return (pressed) => callback?.('right', pressed)
+            }}
+          >
+            <ArrowRight aria-hidden="true" />
+          </HoldAction>
+        </div>
+      </Show>
+      <div class="ml-auto flex min-w-0 max-w-full flex-col items-end gap-2">
+        <Show when={props.onZoomIn || props.onZoomOut}>
+          <div
+            role="group"
+            aria-label={labels().zoomGroup}
+            class="glass-scrim flex min-w-0 max-w-full flex-wrap gap-1.5 rounded-2xl p-1.5"
+          >
+            <Show when={props.onZoomOut}>
+              <ActionButton
+                type="button"
+                variant="secondary"
+                size="icon-2xl"
+                aria-label={labels().zoomOut}
+                tooltip={labels().zoomOut}
+                onClick={() => props.onZoomOut?.()}
+              >
+                <ZoomOut aria-hidden="true" />
+              </ActionButton>
+            </Show>
+            <Show when={props.onZoomIn}>
+              <ActionButton
+                type="button"
+                variant="secondary"
+                size="icon-2xl"
+                aria-label={labels().zoomIn}
+                tooltip={labels().zoomIn}
+                onClick={() => props.onZoomIn?.()}
+              >
+                <ZoomIn aria-hidden="true" />
+              </ActionButton>
+            </Show>
+          </div>
+        </Show>
+        <Show when={props.onJumpChange}>
+          <HoldAction
+            label={labels().jump}
+            tooltip={labels().jumpTooltip}
+            createChangeCallback={() => {
+              const callback = props.onJumpChange
+              return (pressed) => callback?.(pressed)
+            }}
+          >
+            <ArrowUp aria-hidden="true" />
+          </HoldAction>
+        </Show>
+      </div>
+    </div>
+  )
+}

package/src/components/ui/button/button.tsx

@@ -47,6 +47,7 @@ export const buttonVariants = cva(
         md: `${controlSize.md} [&_svg]:size-4`,
         lg: `${controlSize.lg} [&_svg]:size-4`,
         xl: `${controlSize.xl} [&_svg]:size-5`,
+        '2xl': `${controlSize['2xl']} [&_svg]:size-6`,
         /* Square, for an icon with no label. The accessible name then has to
            come from `aria-label` or a visually hidden label — an icon-only
            button with neither is the accessibility finding the Storybook lane
@@ -57,6 +58,11 @@ export const buttonVariants = cva(
         'icon-md': 'size-control-md p-0 [&_svg]:size-4',
         'icon-lg': 'size-control-lg p-0 [&_svg]:size-4',
         'icon-xl': 'size-control-xl p-0 [&_svg]:size-5',
+        'icon-2xl': 'size-control-2xl p-0 [&_svg]:size-6',
+      },
+      /** Opt in to a stable touch target on devices with any coarse pointer. */
+      touchTarget: {
+        comfortable: 'touch-target-comfortable',
       },
     },
     defaultVariants: {
@@ -76,13 +82,25 @@ export type ButtonProps<T extends ValidComponent = 'button'> = PolymorphicProps<
 >
 
 export function Button<T extends ValidComponent = 'button'>(props: ButtonProps<T>) {
-  const [local, rest] = splitProps(props as ButtonProps, ['variant', 'size', 'class'])
+  const [local, rest] = splitProps(props as ButtonProps, [
+    'variant',
+    'size',
+    'touchTarget',
+    'class',
+  ])
 
   return (
     <Polymorphic
       as="button"
       type="button"
-      class={cn(buttonVariants({ variant: local.variant, size: local.size }), local.class)}
+      class={cn(
+        buttonVariants({
+          variant: local.variant,
+          size: local.size,
+          touchTarget: local.touchTarget,
+        }),
+        local.class
+      )}
       {...(rest as ComponentProps<'button'>)}
     />
   )

package/src/components/ui/dialog/dialog.tsx

@@ -147,11 +147,16 @@ export function createDialogFocusRestoration({
           if (
             !(target instanceof HTMLElement) ||
             target === document.body ||
-            target === document.documentElement ||
+            target === document.documentElement
+          ) {
+            return
+          }
+          if (
             target === element ||
             element.contains(target) ||
             target === (opener instanceof HTMLElement ? opener : null)
           ) {
+            if (!cycle.closed) cycle.focusMovedOutside = false
             return
           }
           cycle.focusMovedOutside = true

package/src/components/ui/modal-dialog/modal-dialog.tsx

@@ -33,6 +33,12 @@ import {
  *      handler takes control or focus has moved to another layer. For controlled
  *      dialogs without a composed trigger, pass `restoreFocusRef` when the opener
  *      cannot be inferred from the focused element.
+ *   5. **It keeps its own portal out of an enclosing layer's `aria-hidden`
+ *      bookkeeping.** A non-modal dialog opened while a modal `Sheet` is alive would
+ *      otherwise be aria-hidden one frame after it mounts — the enclosing layer's
+ *      hide-outside observer walks late-arriving body children as background. The
+ *      portal carries the marker that observer exempts; a modal layer opened above
+ *      still hides it, because that path matches a different attribute.
  *
  * Use `Dialog` directly when you need its composition; use this when you want a
  * dialog that is correct by default. `size="settings"` supplies a wide, bounded
@@ -111,6 +117,20 @@ export function ModalDialog(props: ModalDialogProps) {
         if (!wasInert[index]) node.removeAttribute('inert')
       })
     })
+
+    // Kobalte's hide-outside observer walks body children added after its layer
+    // opened and aria-hides them one frame later, so a non-modal dialog portaled
+    // in during that window would land outside the accessibility tree — role
+    // queries never resolve it again while the enclosing layer stays open. The
+    // observer exempts added nodes carrying its top-layer marker (it checks the
+    // React Aria spelling it ported; `data-kb-top-layer` is only matched by a
+    // newer layer's initial walk, which must still hide this dialog).
+    let portal = element
+    while (portal.parentElement !== null && portal.parentElement !== document.body) {
+      portal = portal.parentElement
+    }
+    portal.setAttribute('data-react-aria-top-layer', 'true')
+    onCleanup(() => portal.removeAttribute('data-react-aria-top-layer'))
   })
 
   return (

package/src/components/ui/sheet/sheet.tsx

@@ -1,11 +1,15 @@
-import { Dialog as KobalteDialog, Content as KobalteDialogContent } from '@kobalte/core/dialog'
+import {
+  Dialog as KobalteDialog,
+  Content as KobalteDialogContent,
+  useDialogContext,
+} from '@kobalte/core/dialog'
 // AlertDialog shares DialogRoot.Content; Sheet uses the stable named primitive.
 import { X } from 'lucide-solid'
-import type { ComponentProps, JSX } from 'solid-js'
+import type { Accessor, ComponentProps, JSX } from 'solid-js'
 import { Show, splitProps } from 'solid-js'
 import { cva, type VariantProps } from '#lib/variants'
 import { cn } from '#lib/utils'
-import { DialogOverlay } from '../dialog/dialog'
+import { createDialogFocusRestoration, DialogOverlay } from '../dialog/dialog'
 
 /**
  * Sheet.
@@ -18,6 +22,11 @@ import { DialogOverlay } from '../dialog/dialog'
  * `side` decides which edge; the panel is a full-height column for `start` and
  * `end`, and a full-width row for `top` and `bottom`. The slide-in direction
  * follows from the side, so a caller never pairs them by hand.
+ *
+ * Controlled sheets opened from outside a `SheetTrigger` restore focus to the
+ * element focused before opening. Pass `restoreFocusRef` when a stable external
+ * opener must be used instead, such as when another layer closes before the
+ * sheet opens.
  */
 const sheetVariants = cva(
   'bg-popover text-popover-foreground fixed z-(--z-dialog) flex flex-col gap-4 border-border shadow-lg',
@@ -39,10 +48,27 @@ const sheetVariants = cva(
 export type SheetContentProps = ComponentProps<typeof KobalteDialogContent> &
   VariantProps<typeof sheetVariants> & {
     closeButton?: JSX.Element | false
+    /** Supplies the stable external element to focus when the controlled sheet closes. */
+    restoreFocusRef?: Accessor<HTMLElement | undefined>
   }
 
 export function SheetContent(props: SheetContentProps) {
-  const [local, rest] = splitProps(props, ['class', 'side', 'children', 'closeButton'])
+  const [local, rest] = splitProps(props, [
+    'class',
+    'side',
+    'children',
+    'closeButton',
+    'restoreFocusRef',
+    'onOpenAutoFocus',
+    'onCloseAutoFocus',
+  ])
+  const dialog = useDialogContext()
+  const focusRestoration = createDialogFocusRestoration({
+    open: dialog.isOpen,
+    restoreFocusRef: local.restoreFocusRef,
+    onOpenAutoFocus: local.onOpenAutoFocus,
+    onCloseAutoFocus: local.onCloseAutoFocus,
+  })
 
   return (
     <KobalteDialog.Portal>
@@ -55,11 +81,18 @@ export function SheetContent(props: SheetContentProps) {
           local.class
         )}
         {...rest}
+        onOpenAutoFocus={focusRestoration.onOpenAutoFocus}
+        onCloseAutoFocus={focusRestoration.onCloseAutoFocus}
       >
         {local.children}
         <Show when={local.closeButton !== false}>
+          {/* The close action opts into the tab order explicitly. Engines that
+              derive tabbability from the DOM instead of the host (Playwright's
+              WebKit walks only explicit tabindex and form controls) would skip
+              an implicitly-tabbable button and jump past the sheet's end. */}
           <KobalteDialog.CloseButton
             aria-label="Close"
+            tabindex="0"
             class="absolute top-3.5 end-3.5 rounded-md p-1 text-muted-foreground transition-colors ease-out outline-none hover:bg-surface-hover hover:text-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-primary-subtle"
           >
             {local.closeButton ?? <X class="size-4" />}