@xpufx/paseo-top 0.4.4 → 0.4.7

package/client/vendor/paseo-plugin-helper/{theme/color-utils.ts → lifecycle/host-color.ts}

@@ -1,7 +1,63 @@
 import type { StatusVariant, ThemeColors } from "../../../../shared/vendor/paseo-plugin-helper/types";
 
 /**
- * Converts a hex color and opacity (0.0 to 1.0) into an 8-character hex or rgba string.
+ * The single host-color fallback owned by the helper.
+ *
+ * A host `theme` prop normally supplies every token, but a partial or older
+ * payload may omit some. Rather than each plugin inventing its own
+ * `colors.border || "#334155"` guard, the helper resolves a theme once, here,
+ * and every adapter reads the resolved token. Plugins may pass this palette to
+ * code that renders outside a provider (recipes, previews, tests); they must
+ * not define their own literal fallbacks.
+ */
+export const FALLBACK_COLORS: ThemeColors = {
+  surface0: "#18181b",
+  surface1: "#27272a",
+  surface2: "#3f3f46",
+  border: "#3f3f46",
+  foreground: "#fafafa",
+  foregroundMuted: "#a1a1aa",
+  accent: "#3b82f6",
+  accentForeground: "#ffffff",
+  statusSuccess: "#22c55e",
+  statusWarning: "#eab308",
+  statusDanger: "#ef4444",
+};
+
+/**
+ * The host theme carries no shadow token, so shadows use this documented
+ * overlay constant owned by the helper. It is not a `ThemeColors` token and is
+ * intentionally not part of the palette a render guard checks; it is the one
+ * allowed non-theme color.
+ */
+export const HOST_SHADOW_COLOR = "rgba(0, 0, 0, 0.4)";
+
+/**
+ * Fills a possibly-partial host `theme.colors` from {@link FALLBACK_COLORS}.
+ * This is the one place a missing token becomes a literal, so surfaces never
+ * need a per-property `|| "#hex"` guard.
+ */
+export function resolveHostColors(colors?: Partial<ThemeColors> | null): ThemeColors {
+  return { ...FALLBACK_COLORS, ...(colors ?? {}) };
+}
+
+/**
+ * Paseo Plugin Helper — UI color tokens (`paseo-plugin-helper/ui`).
+ *
+ * Pure color math for the ui/ adapter layer. These helpers are deliberately
+ * self-contained: they never read the DOM, never scrape CSS variables, and
+ * never import the frozen `client/` theme system. Colors arrive from the host
+ * `theme` prop via {@link HostThemeProvider} and are combined here.
+ */
+
+/**
+ * Converts a hex color and opacity (0.0 to 1.0) into an 8-character hex or
+ * rgba string.
+ *
+ * - `#rgb` / `#rrggbb` / `#rrggbbaa` → `#rrggbbaa` (alpha channel replaced)
+ * - `rgb()` / `rgba()` → `rgba(r, g, b, opacity)`
+ * - anything else is returned unchanged (named colors, `transparent`, …)
+ * - empty/invalid color degrades to `rgba(0, 0, 0, opacity)`
  */
 export function alpha(color: string, opacity: number): string {
   if (!color) return `rgba(0, 0, 0, ${opacity})`;
@@ -39,42 +95,6 @@ export function alpha(color: string, opacity: number): string {
   return color;
 }
 
-/**
- * Calculates relative luminance (WCAG 2.0 formula) from a hex color.
- */
-export function getLuminance(hexColor: string): number {
-  let hex = hexColor.replace("#", "");
-  if (hex.length === 3) {
-    hex = hex
-      .split("")
-      .map((c) => c + c)
-      .join("");
-  }
-  const r = parseInt(hex.slice(0, 2), 16) / 255;
-  const g = parseInt(hex.slice(2, 4), 16) / 255;
-  const b = parseInt(hex.slice(4, 6), 16) / 255;
-
-  const toLinear = (c: number) => (c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
-
-  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
-}
-
-/**
- * Returns either lightText or darkText depending on which has highest contrast against bgHex.
- */
-export function getContrastColor(
-  bgHex: string,
-  lightText = "#ffffff",
-  darkText = "#0f172a",
-): string {
-  try {
-    const lum = getLuminance(bgHex);
-    return lum > 0.45 ? darkText : lightText;
-  } catch {
-    return lightText;
-  }
-}
-
 /**
  * Resolves a StatusVariant to a corresponding theme color hex string.
  */
@@ -102,7 +122,8 @@ export function getStatusColor(
 }
 
 /**
- * Returns background, text, and border styling colors for a given status variant.
+ * Returns background, text, and border styling colors for a given status
+ * variant, derived from the host theme colors via {@link alpha}.
  */
 export function getVariantPalette(
   variant: StatusVariant,
@@ -116,3 +137,39 @@ export function getVariantPalette(
     border: alpha(base, 0.3),
   };
 }
+
+/**
+ * Calculates relative luminance (WCAG 2.0 formula) from a hex color.
+ */
+export function getLuminance(hexColor: string): number {
+  let hex = hexColor.replace("#", "");
+  if (hex.length === 3) {
+    hex = hex
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+  const r = parseInt(hex.slice(0, 2), 16) / 255;
+  const g = parseInt(hex.slice(2, 4), 16) / 255;
+  const b = parseInt(hex.slice(4, 6), 16) / 255;
+
+  const toLinear = (c: number) => (c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
+
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+/**
+ * Returns either lightText or darkText depending on which has highest contrast against bgHex.
+ */
+export function getContrastColor(
+  bgHex: string,
+  lightText = "#ffffff",
+  darkText = "#0f172a",
+): string {
+  try {
+    const lum = getLuminance(bgHex);
+    return lum > 0.45 ? darkText : lightText;
+  } catch {
+    return lightText;
+  }
+}

package/client/vendor/paseo-plugin-helper/lifecycle/host-theme.tsx

@@ -0,0 +1,109 @@
+import React, { createContext, useContext, type ReactNode } from "react";
+import type { PluginTheme, ResponsiveLayout, StatusVariant, ThemeColors } from "../../../../shared/vendor/paseo-plugin-helper/types";
+import { alpha, getStatusColor, getVariantPalette, FALLBACK_COLORS, resolveHostColors } from "./host-color";
+
+/**
+ * Paseo Plugin Helper — Host theme context (`paseo-plugin-helper/ui`).
+ *
+ * The ui/ adapter layer's ONLY source of color tokens. The host hands every
+ * surface a `theme` prop (`PluginTheme`); `HostThemeProvider` carries those
+ * colors to every ui/ adapter below it.
+ *
+ * Contract — what this context deliberately does NOT do:
+ * - No DOM CSS variable scraping. Colors come from the host `theme` prop only;
+ *   the removed legacy theme provider's `getComputedStyle` scraper is gone.
+ * - No flair, density, typography, or padding machinery. The host owns the
+ *   design language; ui/ only consumes its color tokens.
+ * - No scroll-ownership state machine. See `ui/modal.tsx`.
+ *
+ * Usage:
+ * ```tsx
+ * <HostThemeProvider theme={props.theme}>
+ *   <HostCard>…</HostCard>
+ * </HostThemeProvider>
+ * ```
+ */
+
+export interface HostTheme {
+  /** Host theme colors, straight from the host `theme` prop. */
+  colors: ThemeColors;
+  /** Color-token opacity helper bound to nothing but its arguments. */
+  alpha: (color: string, opacity: number) => string;
+  /** Status variant → host theme color. */
+  getStatusColor: (variant: StatusVariant) => string;
+  /** Status variant → { bg, text, border } palette derived via `alpha`. */
+  getVariantPalette: (variant: StatusVariant) => { bg: string; text: string; border: string };
+}
+
+/**
+ * Neutral fallback palette so ui/ adapters still render outside a provider
+ * (tests, previews, host surfaces that have not migrated yet). It is the single
+ * helper-owned fallback; see {@link FALLBACK_COLORS}. A supplied `theme` is
+ * merged over it, so a partial host payload never paints a raw literal.
+ */
+function createHostTheme(colors: ThemeColors): HostTheme {
+  return {
+    colors,
+    alpha,
+    getStatusColor: (variant) => getStatusColor(variant, colors),
+    getVariantPalette: (variant) => getVariantPalette(variant, colors),
+  };
+}
+
+const FALLBACK_HOST_THEME: HostTheme = createHostTheme(FALLBACK_COLORS);
+
+const HostThemeContext = createContext<HostTheme>(FALLBACK_HOST_THEME);
+
+export interface HostThemeProviderProps {
+  /** The host `theme` prop for this surface — the single source of colors. */
+  theme: PluginTheme;
+  children: ReactNode;
+}
+
+/**
+ * Provides host theme colors to every ui/ adapter in the subtree. Same `theme`
+ * prop shape the removed legacy `PluginThemeProvider` took, but no scraped
+ * variables and no flair.
+ */
+export function HostThemeProvider({ theme, children }: HostThemeProviderProps) {
+  const value = createHostTheme(resolveHostColors(theme.colors));
+  return <HostThemeContext.Provider value={value}>{children}</HostThemeContext.Provider>;
+}
+
+/**
+ * Reads the host theme provided by {@link HostThemeProvider}. Falls back to a
+ * static neutral palette when no provider is above — adapters never throw and
+ * never scrape.
+ */
+export function useHostTheme(): HostTheme {
+  return useContext(HostThemeContext);
+}
+
+// --- Host layout -----------------------------------------------------------
+
+const DEFAULT_LAYOUT: ResponsiveLayout = {
+  compact: false,
+  platform: "web",
+};
+
+const HostLayoutContext = createContext<ResponsiveLayout>(DEFAULT_LAYOUT);
+
+export interface HostLayoutProviderProps {
+  /** The host `layout` prop for this surface. */
+  layout: ResponsiveLayout;
+  children: ReactNode;
+}
+
+/**
+ * Provides the host layout descriptor (compact / platform / width) to ui/
+ * adapters that branch on it (e.g. `HostResponsive`). Optional: adapters
+ * fall back to a wide-web default when no provider is above.
+ */
+export function HostLayoutProvider({ layout, children }: HostLayoutProviderProps) {
+  return <HostLayoutContext.Provider value={layout}>{children}</HostLayoutContext.Provider>;
+}
+
+/** Reads the host layout descriptor. */
+export function useHostLayout(): ResponsiveLayout {
+  return useContext(HostLayoutContext);
+}

package/client/vendor/paseo-plugin-helper/lifecycle/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Paseo Plugin Helper — Lifecycle (headless, client-safe, UI-free).
+ *
+ * Import from `paseo-plugin-helper/lifecycle` for the host-registration
+ * engines — composer pills, sidebar surfaces, workspace/agent panels — plus
+ * clipboard and haptics helpers. These are client-bundle safe (React Native,
+ * no `node:*`) but intentionally separate from `paseo-plugin-helper/core`,
+ * whose purity contract forbids `react-native`.
+ *
+ * The bespoke `client/` design system was removed (#938); this entry mounts
+ * the host theme itself and imports only the headless host seam from `core`.
+ */
+export * from "./pill";
+export * from "./surface";
+export * from "./panel";
+export * from "./clipboard";
+export * from "./haptics";
+export * from "./scroll-owner";
+export * from "./host-theme";
+export * from "./host-color";
+export * from "./flair";
+export * from "./providers";
+export * from "./multi-host";

package/client/vendor/paseo-plugin-helper/lifecycle/multi-host.ts

@@ -0,0 +1,66 @@
+import * as pluginClient from "@getpaseo/plugin/client";
+import type { PluginHostSummary } from "@getpaseo/plugin/client";
+
+/**
+ * The desktop host bundle supplies `useHosts`/`getPaseoClient`; the mobile
+ * bundle omits them, so a direct named call throws `useHosts is not a
+ * function` and takes the whole surface with it (#1043, #1057-G). These seams
+ * reach the primitives through a feature-detected namespace so a surface
+ * degrades to "no hosts" instead of crashing the plugin.
+ */
+
+/** The host summary shape `useHosts()` returns (the SDK's `PluginHostSummary`). */
+export type OptionalHostSummary = PluginHostSummary;
+
+/** The borrowed per-host client `getPaseoClient(serverId)` returns. */
+export type OptionalPaseoClient = ReturnType<typeof pluginClient.getPaseoClient>;
+
+interface MultiHostPrimitives {
+  useHosts?: () => readonly PluginHostSummary[];
+  getPaseoClient?: (serverId: string) => OptionalPaseoClient;
+}
+
+/**
+ * Read a function export without tripping a test runner's module-mock `get`
+ * trap. A partial mock throws when an unlisted export is read; `Object.keys`
+ * only asks for the keys the module has, so an absent primitive reads as
+ * `undefined` on mock and real host alike.
+ */
+function readFunction<T>(source: unknown, key: string): T | undefined {
+  if (source === null || typeof source !== "object") return undefined;
+  if (!Object.keys(source).includes(key)) return undefined;
+  const value = (source as Record<string, unknown>)[key];
+  return typeof value === "function" ? (value as T) : undefined;
+}
+
+const hostPrimitives: MultiHostPrimitives = {
+  useHosts: readFunction(pluginClient, "useHosts"),
+  getPaseoClient: readFunction(pluginClient, "getPaseoClient"),
+};
+const EMPTY_HOSTS: readonly PluginHostSummary[] = [];
+const noHosts = () => EMPTY_HOSTS;
+
+// Hook identity is module-constant, so a given host calls the same function on
+// every render and the hook order never changes.
+const useHosts = hostPrimitives.useHosts ?? noHosts;
+
+/** True when the running host supplies the multi-host primitives. */
+export function isMultiHostSupported(): boolean {
+  return (
+    typeof hostPrimitives.useHosts === "function" &&
+    typeof hostPrimitives.getPaseoClient === "function"
+  );
+}
+
+/**
+ * `useHosts()` when the host supplies it, otherwise an empty host list, so a
+ * surface that enumerates hosts degrades instead of crashing the bundle.
+ */
+export function useOptionalHosts(): readonly PluginHostSummary[] {
+  return useHosts();
+}
+
+/** Borrow an online host's API, or `undefined` when the host omits the seam. */
+export function getOptionalPaseoClient(serverId: string): OptionalPaseoClient | undefined {
+  return hostPrimitives.getPaseoClient?.(serverId);
+}

package/client/vendor/paseo-plugin-helper/{panel.tsx → lifecycle/panel.tsx}

@@ -2,9 +2,9 @@ import React, { type ComponentType } from "react";
 import type {
   HostWorkspacePanelProps as PluginWorkspacePanelProps,
   HostAgentPanelProps as PluginAgentPanelProps,
-} from "./host";
-import { PluginThemeProvider } from "./theme/provider";
-import type { VisualFlair } from "./theme/flair";
+} from "../core/host";
+import type { VisualFlair } from "./flair";
+import { RegistrarThemeScope } from "./providers";
 
 /**
  * Structural registrar interface satisfied by both Paseo v0.7 PluginContext
@@ -43,9 +43,9 @@ export function registerWorkspacePanel(
   const { id, title, icon, Component, flair, locations } = options;
 
   const WrappedComponent: ComponentType<PluginWorkspacePanelProps> = (props) => (
-    <PluginThemeProvider theme={props.theme} layout={props.layout} flair={flair}>
+    <RegistrarThemeScope theme={props.theme} layout={props.layout} flair={flair}>
       <Component {...props} />
-    </PluginThemeProvider>
+    </RegistrarThemeScope>
   );
 
   const registration = plugin.addWorkspacePanel({
@@ -74,9 +74,9 @@ export function registerAgentPanel(
   const { id, title, icon, Component, flair } = options;
 
   const WrappedComponent: ComponentType<PluginAgentPanelProps> = (props) => (
-    <PluginThemeProvider theme={props.theme} layout={props.layout} flair={flair}>
+    <RegistrarThemeScope theme={props.theme} layout={props.layout} flair={flair}>
       <Component {...props} />
-    </PluginThemeProvider>
+    </RegistrarThemeScope>
   );
 
   plugin.addWorkspacePanel({

package/client/vendor/paseo-plugin-helper/{pill.tsx → lifecycle/pill.tsx}

@@ -14,16 +14,16 @@ import {
   type HostPillProps,
   type HostTheme,
   type PluginCleanup,
-} from "./host";
+} from "../core/host";
 import type {
   PluginButtonContentProps,
   PluginButtonIconProps,
   PluginButtonRegistration,
 } from "@getpaseo/plugin/client";
-import { PluginThemeProvider } from "./theme/provider";
-import type { VisualFlair } from "./theme/flair";
-import { ModalBodyScrollOwnerContext } from "./layout/ModalBody";
-import { reportSuppressed } from "../../../shared/vendor/paseo-plugin-helper/suppressed";
+import type { VisualFlair } from "./flair";
+import { ModalBodyScrollOwnerContext } from "./scroll-owner";
+import { RegistrarThemeScope } from "./providers";
+import { reportSuppressed } from "../../../../shared/vendor/paseo-plugin-helper/suppressed";
 
 export interface RenderModalProps<TPayload = any> extends HostPillProps {
   close: () => void;
@@ -423,9 +423,13 @@ export function registerComposerPill<TPayload = any>(
                     onStartShouldSetResponder={() => true}
                     onTouchEnd={stopBubbling}
                     {...(eventBoundaryProps as any)}
-                    style={{ flex: 1, minHeight: 0 }}
+                    style={
+                      resolvePillModalScrollable(options.hostScroll)
+                        ? { width: "100%" }
+                        : { flex: 1, minHeight: 0, width: "100%" }
+                    }
                   >
-                    <PluginThemeProvider theme={theme} layout={layout} flair={options.flair}>
+                    <RegistrarThemeScope theme={theme} layout={layout} flair={options.flair}>
                       <ModalBodyScrollOwnerContext.Provider
                         value={resolvePillModalScrollable(options.hostScroll) ? "host" : "required"}
                       >
@@ -438,7 +442,7 @@ export function registerComposerPill<TPayload = any>(
                           close: () => setCenteredOpen(agentId, false),
                         })}
                       </ModalBodyScrollOwnerContext.Provider>
-                    </PluginThemeProvider>
+                    </RegistrarThemeScope>
                   </View>
                 ) : null}
               </Modal.Content>
@@ -470,11 +474,14 @@ export function registerComposerPill<TPayload = any>(
       !props.layout.compact && options.popoverWidth
         ? Math.max(0, Math.min(options.popoverWidth, windowWidth - 24))
         : undefined;
-    // The host remains the scroll owner, but it needs a finite child extent to
-    // establish the popover viewport. Do not add overflow clipping or an inner
-    // ScrollView here: either would compete with the host's popover/sheet
-    // scroller.
-    const frameMaxHeight = Math.max(1, Math.min(560, windowHeight * 0.8));
+    // The host remains the scroll owner, but desktop needs a finite child extent to
+    // establish the popover viewport. Compact mobile presents a full-bleed sheet
+    // whose BottomSheetScrollView dynamically sizes and scrolls, so capping height
+    // here would clip long content instead of scrolling it.
+    const isMobile = props.layout.platform === "ios" || props.layout.platform === "android";
+    const frameMaxHeight = props.layout.compact && isMobile
+      ? undefined
+      : Math.max(1, Math.min(560, windowHeight * 0.8));
     // Layout effect, not effect: the flag must be set in the same commit the
     // popover mounts, before any label timer can interleave. An effect runs
     // after paint, leaving a window where one tick can still publish and
@@ -493,7 +500,7 @@ export function registerComposerPill<TPayload = any>(
       host: props.host ?? { id: "", label: "" },
     };
     return (
-      <PluginThemeProvider theme={props.theme} layout={props.layout} flair={options.flair}>
+      <RegistrarThemeScope theme={props.theme} layout={props.layout} flair={options.flair}>
         <View
           style={{
             ...styles.popoverContainer,
@@ -505,7 +512,7 @@ export function registerComposerPill<TPayload = any>(
             {options.renderModal?.({ ...pillProps, close: props.close })}
           </ModalBodyScrollOwnerContext.Provider>
         </View>
-      </PluginThemeProvider>
+      </RegistrarThemeScope>
     );
   }
 
@@ -632,6 +639,8 @@ export function registerComposerPill<TPayload = any>(
     syncSharedLabelTimer();
   }
 
+  const lifetime = new AbortController();
+
   const unsubscribe = client.paseo.agents.subscribe((update) => {
     if (disposed) return;
     if ("agentId" in update && update.kind === "remove") {
@@ -645,14 +654,37 @@ export function registerComposerPill<TPayload = any>(
   });
 
   client.paseo.agents
-    .list()
+    .list({ subscribe: {}, signal: lifetime.signal })
     .then((result) => {
       if (disposed) return;
-      for (const { agent } of result.entries) {
-        if (agent.workspaceId) addPill(agent.id, agent.workspaceId);
+      if (result.entries) {
+        for (const { agent } of result.entries) {
+          if (agent.workspaceId) addPill(agent.id, agent.workspaceId);
+        }
+      }
+      if (result.subscription) {
+        result.subscription.subscribe({
+          snapshot: ({ entries }: { entries: Array<{ agent: { id: string; workspaceId?: string | null } }> }) => {
+            if (disposed) return;
+            for (const { agent } of entries) {
+              if (agent.workspaceId) addPill(agent.id, agent.workspaceId);
+            }
+          },
+          update: (message: any) => {
+            if (disposed) return;
+            if (message?.type !== "agent_update") return;
+            const update = message.payload;
+            if ("agentId" in update && update.kind === "remove") {
+              removePill(update.agentId);
+            } else if ("agent" in update && update.agent?.workspaceId) {
+              addPill(update.agent.id, update.agent.workspaceId);
+            }
+          },
+        });
       }
     })
     .catch((error) => {
+      if (lifetime.signal.aborted || disposed) return;
       // Silently dropping this leaves a plugin with zero pills and no clue why.
       reportSuppressed(console, "registerComposerPill agents.list() failed", error, "warn");
     });
@@ -660,6 +692,7 @@ export function registerComposerPill<TPayload = any>(
   return () => {
     if (disposed) return;
     disposed = true;
+    lifetime.abort();
     unsubscribe();
     if (sharedLabelTimer) {
       clearInterval(sharedLabelTimer);

package/client/vendor/paseo-plugin-helper/lifecycle/providers.tsx

@@ -0,0 +1,46 @@
+import React, { type ComponentType, type ReactNode } from "react";
+import type { PluginTheme } from "../../../../shared/vendor/paseo-plugin-helper/types";
+import type { HostLayout } from "../core/host";
+import type { VisualFlair } from "./flair";
+import { HostThemeProvider } from "./host-theme";
+
+/**
+ * Presentational seam for the lifecycle registration engines.
+ *
+ * The bespoke `client/` design system was removed (#938), so no installer
+ * remains: `RegistrarThemeScope` mounts only `HostThemeProvider` (the host
+ * `theme` prop drives every ui/ adapter). The legacy-provider hook stays for
+ * callers that mounted their own theme provider before the removal.
+ */
+export interface RegistrarThemeProps {
+  theme: PluginTheme;
+  layout?: HostLayout;
+  flair?: Partial<VisualFlair>;
+  children: ReactNode;
+}
+
+export type RegistrarLegacyThemeProvider = ComponentType<RegistrarThemeProps>;
+
+let legacyThemeProvider: RegistrarLegacyThemeProvider | undefined;
+
+/**
+ * Installed once by a legacy theme shim. Keeping it out of the `lifecycle/`
+ * entry's runtime imports is what lets that entry stay free of any UI kit.
+ */
+export function setRegistrarLegacyThemeProvider(
+  provider: RegistrarLegacyThemeProvider | undefined,
+): void {
+  legacyThemeProvider = provider;
+}
+
+/** Mounts the host theme (always) and the legacy provider (when installed). */
+export function RegistrarThemeScope({ theme, layout, flair, children }: RegistrarThemeProps) {
+  const hostTheme = <HostThemeProvider theme={theme}>{children}</HostThemeProvider>;
+  const Legacy = legacyThemeProvider;
+  if (!Legacy) return hostTheme;
+  return (
+    <Legacy theme={theme} layout={layout} flair={flair}>
+      {hostTheme}
+    </Legacy>
+  );
+}

package/client/vendor/paseo-plugin-helper/lifecycle/scroll-owner.ts

@@ -0,0 +1,26 @@
+import { createContext } from "react";
+
+/**
+ * Scroll-ownership signal emitted by the lifecycle registration engines.
+ *
+ * - `"helper"` — the default; the content owns its own scrolling.
+ * - `"host"` — an ancestor host view already provides the one scroller
+ *   (0.8 composer popovers), so the content renders plain.
+ * - `"required"` — the ancestor has NO host scroller and the content is
+ *   host-sized, so it MUST own the scroll on every surface. Set by
+ *   `registerSidebarSurface` (a plugin surface is a full host page whose body
+ *   is not wrapped in a host scroller).
+ * - `"popover"` — the host anchored-popover already supplies the sole scroller.
+ *
+ * The context lives in `lifecycle/` so the registration engines can mark the
+ * subtrees they render without importing any UI kit. It survived the removal of
+ * the bespoke `ModalBody` reader (#938) as a signal plugins and the host can
+ * still consume.
+ */
+export type ModalBodyScrollOwner = "helper" | "host" | "required" | "popover";
+
+const SCROLL_OWNER_CONTEXT_KEY = Symbol.for("paseo.modalBodyScrollOwnerContext");
+
+export const ModalBodyScrollOwnerContext: React.Context<ModalBodyScrollOwner> =
+  ((globalThis as any)[SCROLL_OWNER_CONTEXT_KEY] ??= createContext<ModalBodyScrollOwner>("helper"));
+

package/client/vendor/paseo-plugin-helper/{surface.tsx → lifecycle/surface.tsx}

@@ -1,9 +1,9 @@
 import React, { type ComponentType } from "react";
 import { View } from "react-native";
-import type { HostSurfaceProps as PluginSurfaceProps } from "./host";
-import { PluginThemeProvider } from "./theme/provider";
-import { ModalBodyScrollOwnerContext } from "./layout/ModalBody";
-import type { VisualFlair } from "./theme/flair";
+import type { HostSurfaceProps as PluginSurfaceProps } from "../core/host";
+import type { VisualFlair } from "./flair";
+import { ModalBodyScrollOwnerContext } from "./scroll-owner";
+import { RegistrarThemeScope } from "./providers";
 
 /**
  * Structural registrar interface satisfied by both Paseo v0.7 PluginContext
@@ -101,7 +101,7 @@ export function registerSidebarSurface(
   } = options;
 
   const WrappedComponent: ComponentType<PluginSurfaceProps> = (props) => (
-    <PluginThemeProvider theme={props.theme} layout={props.layout} flair={flair}>
+    <RegistrarThemeScope theme={props.theme} layout={props.layout} flair={flair}>
       <ModalBodyScrollOwnerContext.Provider value="required">
         {maxContentWidth === false ? (
           <Component {...props} />
@@ -111,7 +111,7 @@ export function registerSidebarSurface(
           </SurfaceContentColumn>
         )}
       </ModalBodyScrollOwnerContext.Provider>
-    </PluginThemeProvider>
+    </RegistrarThemeScope>
   );
 
   const surfaceRegistration = plugin.addSurface(id, WrappedComponent);

package/client/vendor/paseo-plugin-helper/ui/color.ts

@@ -0,0 +1 @@
+export * from "../lifecycle/host-color";