@xpufx/paseo-top 0.4.3 → 0.4.5

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({