Merge branch 'stack/agent-profiles-7-docs' into stack/agent-profiles-8-authoring

packages/client/ui-settings/src/client/SettingsRoot.module.css

@@ -222,33 +222,3 @@
   clip: rect(0 0 0 0);
   white-space: nowrap;
 }
-
-/* First-run stage: keep the product top bar visible, then let onboarding own
-   the complete workspace instead of presenting another settings modal. */
-.onboardingOverlay {
-  position: fixed;
-  inset: 0;
-  z-index: 1100;
-}
-
-/* Mask */
-.onboardingMask {
-  position: absolute;
-  left: 0px;
-  right: 0px;
-  top: 80px;
-  bottom: 0px;
-  background: rgba(0, 0, 0, 0.24);
-  /* Mask-blur */
-  backdrop-filter: blur(2px);
-}
-
-.onboardingStage {
-  position: absolute;
-  z-index: 1;
-  inset: 0;
-  display: flex;
-  justify-content: center;
-  overflow: hidden;
-  background: var(--dsw-alias-bg-layer-1);
-}

packages/client/ui-settings/src/client/SettingsRoot.tsx

@@ -7,10 +7,11 @@
  * aria-labelledby the title node; close: visually-hidden slot text). Modal
  * open state and the active section id are component-local viewing state;
  * the onboarding coordinator mounts exactly one ordered registrant while the
- * sessions-derived empty-Hero fact is active.
+ * sessions-derived empty-Hero fact is active — the takeover chrome
+ * (OnboardingSurface) belongs to the step, so a mounted-but-deciding step
+ * paints nothing here.
  */
 import { useCallback, useEffect, useId, useRef, useState } from 'react'
-import { createPortal } from 'react-dom'
 import clsx from 'clsx'
 import {
   IconCloseOutline16, IconDataOutline16, IconSettingsOutline16, IconThinkOutline16,
@@ -137,14 +138,6 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
     })
   }, [])
 
-  useEffect(() => {
-    if (onboardingStep === undefined) return
-    const appRoot = document.getElementById('root')
-    if (appRoot === null) return
-    appRoot.inert = true
-    return () => { appRoot.inert = false }
-  }, [onboardingStep])
-
   return (
     <>
       <button
@@ -165,18 +158,15 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
           onClose={close}
         />
       )}
-      {onboardingStep !== undefined && createPortal((
-        <div className={css.onboardingOverlay} role="presentation">
-          <div className={css.onboardingMask} aria-hidden="true" />
-          <div className={css.onboardingStage}>
-            {renderSlot('settings.onboarding', {
-              stepId: onboardingStep.id,
-              complete: () => { completeOnboardingStep(onboardingStep.id) },
-              openSection,
-            }, { only: onboardingStep.id })}
-          </div>
-        </div>
-      ), document.body)}
+      {/* The takeover chrome (OnboardingSurface: mask, opaque stage, `#root`
+          inert) lives inside the step component, wrapped around its visible
+          content — a step still deciding (private facts loading) renders
+          null, so nothing paints or blocks while it decides. */}
+      {onboardingStep !== undefined && renderSlot('settings.onboarding', {
+        stepId: onboardingStep.id,
+        complete: () => { completeOnboardingStep(onboardingStep.id) },
+        openSection,
+      }, { only: onboardingStep.id })}
     </>
   )
 }

packages/client/ui-settings/src/client/contract/slots.ts

@@ -57,7 +57,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * Root-scoped onboarding steps contributed by settings features. The
      * shell mounts one ordered step at a time; the active registrant either
      * completes itself or keeps ownership until the user completes its sole
-     * path. Registrants own readiness, copy, and dialog behavior.
+     * path. Registrants own readiness, copy, dialog behavior, AND the
+     * takeover chrome: a step wraps its visible content in the
+     * OnboardingSurface primitive (mask, opaque stage, `#root` inert) and
+     * renders null while its private facts are still loading — the shell
+     * paints no chrome of its own, so a mounted-but-deciding step shows and
+     * blocks nothing (the reload white-flash fix; a bare unwrapped step
+     * would render without mask or stage).
      */
     'settings.onboarding': { kind: 'list'; scope: 'root'; owner: SettingsOnboardingOwnerProps }
   }