@xpufx/paseo-x-comms 0.3.0

package/client/vendor/paseo-plugin-helper/shared-settings.ts

@@ -0,0 +1,46 @@
+import type { SettingsContract } from "../../../shared/vendor/paseo-plugin-helper/settings";
+import { SuiteSettingsContract, type SuiteSettings } from "../../../shared/vendor/paseo-plugin-helper/suite-settings";
+import {
+  usePluginSettings,
+  type UsePluginSettingsOptions,
+  type UsePluginSettingsResult,
+} from "./settings";
+
+export interface UseSharedPluginSettingsOptions<TSettings>
+  extends UsePluginSettingsOptions<TSettings> {
+  /**
+   * Background polling interval keeping sibling plugins in sync when one of
+   * them writes the shared file outside this client's RPC round-trip.
+   * Defaults to 2000ms. Pass `false` to disable polling.
+   */
+  pollIntervalMs?: number | false;
+}
+
+/**
+ * Reactive hook for suite-wide settings shared across independent sibling plugins.
+ * Wraps usePluginSettings with sync-friendly defaults: always re-verifies on
+ * mount and polls in the background so an update written by Plugin A appears
+ * in Plugin B without a manual refresh.
+ */
+export function useSharedPluginSettings<TSettings extends Record<string, any>>(
+  contract: SettingsContract<TSettings>,
+  options: UseSharedPluginSettingsOptions<TSettings> = {},
+): UsePluginSettingsResult<TSettings> {
+  const { pollIntervalMs = 2000, ...rest } = options;
+  return usePluginSettings(contract, {
+    staleTime: 0,
+    refetchOnMount: "always",
+    refetchOnWindowFocus: true,
+    ...rest,
+    refetchInterval: rest.refetchInterval ?? pollIntervalMs,
+  });
+}
+
+/**
+ * Convenience hook bound to the canonical xpufx suite settings contract.
+ */
+export function useSuiteSettings(
+  options: UseSharedPluginSettingsOptions<SuiteSettings> = {},
+): UsePluginSettingsResult<SuiteSettings> {
+  return useSharedPluginSettings(SuiteSettingsContract, options);
+}

package/client/vendor/paseo-plugin-helper/snapshot.ts

@@ -0,0 +1,68 @@
+/**
+ * Generic workspace-scoped shared snapshot helpers.
+ *
+ * When several surfaces (composer pill, modal, dashboard) render different
+ * views of one host snapshot, they must share a single React Query cache
+ * identity per workspace. Field-specific query keys fragment that cache and
+ * let every visible pill start its own poller, so build one stable key per
+ * workspace scope and keep selective server-side field collection out of the
+ * client cache key.
+ *
+ * The no-op guards here keep settings listeners and live-label caches from
+ * emitting redundant updates: React Query hands out fresh object identities
+ * on every refetch, even when values are unchanged.
+ */
+
+/** Normalized workspace scope: trimmed directory, or "" for host-wide. */
+export function normalizeSnapshotScope(directory?: string | null): string {
+  if (typeof directory !== "string") return "";
+  return directory.trim();
+}
+
+/**
+ * Stable shared cache key for one RPC snapshot in one workspace scope.
+ * Scopes normalize so `undefined`, `null`, and `""` all map to the
+ * host-wide entry instead of three separate caches.
+ */
+export function sharedSnapshotKey(
+  contractName: string,
+  directory?: string | null,
+): readonly [string, { directory?: string }] {
+  const scope = normalizeSnapshotScope(directory);
+  return scope ? [contractName, { directory: scope }] : [contractName, {}];
+}
+
+/**
+ * Shallow record equality for plain settings/snapshot objects.
+ * Returns true when both sides hold the same keys with Object.is-equal
+ * values. Nested objects compare by reference, which is enough to detect
+ * refetch-fresh copies of unchanged flat settings.
+ */
+export function shallowEqualRecord(
+  a: Record<string, unknown> | null | undefined,
+  b: Record<string, unknown> | null | undefined,
+): boolean {
+  if (Object.is(a, b)) return true;
+  if (!a || !b) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * True when listeners should be notified: the snapshot reference changed
+ * and its shallow contents differ. Suppresses the no-op fan-out that
+ * otherwise fires on every background refetch.
+ */
+export function shouldEmitSnapshotUpdate(
+  prev: Record<string, unknown> | null | undefined,
+  next: Record<string, unknown> | null | undefined,
+): boolean {
+  if (Object.is(prev, next)) return false;
+  return !shallowEqualRecord(prev, next);
+}

package/client/vendor/paseo-plugin-helper/surface.tsx

@@ -0,0 +1,80 @@
+import React, { type ComponentType } from "react";
+import type { HostSurfaceProps as PluginSurfaceProps } from "./host";
+import { PluginThemeProvider } from "./theme/provider";
+import { ModalBodyScrollOwnerContext } from "./layout/ModalBody";
+import type { VisualFlair } from "./theme/flair";
+
+/**
+ * Structural registrar interface satisfied by both Paseo v0.7 PluginContext
+ * and Paseo v0.8 PluginClientContext.
+ */
+export interface SidebarSurfaceRegistrar {
+  addSurface(surfaceId: string, Component: ComponentType<PluginSurfaceProps>): any;
+  addSidebarItem(contribution: any): any;
+}
+
+export interface RegisterSidebarSurfaceOptions {
+  id: string;
+  title: string;
+  icon: string;
+  Component: ComponentType<PluginSurfaceProps>;
+  flair?: VisualFlair;
+}
+
+/**
+ * Registers a sidebar icon and corresponding full-page surface in a single call,
+ * automatically injecting `<PluginThemeProvider>` with custom visual flair.
+ * Works with both Paseo v0.7 PluginContext and Paseo v0.8 PluginClientContext.
+ *
+ * A sidebar surface is a full host page: Paseo routes to it directly and does
+ * NOT wrap the surface body in a host scroller (unlike `<Modal.Content>`, which
+ * bounds the dialog and supplies the outer scroll). Any `ModalBody` in the
+ * subtree would therefore pick the plain, non-scrolling branch on a
+ * non-compact desktop and clip overflowing content — the recurring
+ * "plugin page does not scroll" bug. Marking the subtree with the
+ * `"required"` scroll-owner context makes every `ModalBody` inside own the
+ * scroll on every surface, so plugins inherit working scroll with no
+ * per-plugin workaround.
+ *
+ * Returns an idempotent disposer that removes both the surface and the sidebar
+ * item, matching every other helper `add*` registration. Existing callers that
+ * ignore the return value are unaffected.
+ */
+export function registerSidebarSurface(
+  plugin: SidebarSurfaceRegistrar,
+  options: RegisterSidebarSurfaceOptions,
+): () => void {
+  const { id, title, icon, Component, flair } = options;
+
+  const WrappedComponent: ComponentType<PluginSurfaceProps> = (props) => (
+    <PluginThemeProvider theme={props.theme} layout={props.layout} flair={flair}>
+      <ModalBodyScrollOwnerContext.Provider value="required">
+        <Component {...props} />
+      </ModalBodyScrollOwnerContext.Provider>
+    </PluginThemeProvider>
+  );
+
+  const surfaceRegistration = plugin.addSurface(id, WrappedComponent);
+  const itemRegistration = plugin.addSidebarItem({
+    id,
+    title,
+    icon,
+    surface: id,
+  });
+
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    // Host registrations expose `remove()`; tolerate hosts that return a bare
+    // function or nothing so cleanup never throws.
+    for (const registration of [itemRegistration, surfaceRegistration]) {
+      if (!registration) continue;
+      if (typeof registration === "function") {
+        (registration as () => void)();
+      } else if (typeof registration.remove === "function") {
+        registration.remove();
+      }
+    }
+  };
+}

package/client/vendor/paseo-plugin-helper/theme/color-utils.ts

@@ -0,0 +1,118 @@
+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.
+ */
+export function alpha(color: string, opacity: number): string {
+  if (!color) return `rgba(0, 0, 0, ${opacity})`;
+  const clampedOpacity = Math.max(0, Math.min(1, opacity));
+
+  if (color.startsWith("#")) {
+    let cleanHex = color.replace("#", "");
+    if (cleanHex.length === 3) {
+      cleanHex = cleanHex
+        .split("")
+        .map((c) => c + c)
+        .join("");
+    } else if (cleanHex.length === 4) {
+      cleanHex = cleanHex
+        .slice(0, 3)
+        .split("")
+        .map((c) => c + c)
+        .join("");
+    } else if (cleanHex.length === 8) {
+      cleanHex = cleanHex.slice(0, 6);
+    }
+    const alphaHex = Math.round(clampedOpacity * 255)
+      .toString(16)
+      .padStart(2, "0");
+    return `#${cleanHex}${alphaHex}`;
+  }
+
+  if (color.startsWith("rgb")) {
+    const parts = color.replace(/[^\d,.]/g, "").split(",");
+    if (parts.length >= 3) {
+      return `rgba(${parts[0]}, ${parts[1]}, ${parts[2]}, ${clampedOpacity})`;
+    }
+  }
+
+  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.
+ */
+export function getStatusColor(
+  variant: StatusVariant,
+  colors: ThemeColors,
+  customAccent?: string,
+): string {
+  const accent = customAccent || colors.accent;
+  switch (variant) {
+    case "success":
+      return colors.statusSuccess;
+    case "warning":
+      return colors.statusWarning;
+    case "danger":
+      return colors.statusDanger;
+    case "accent":
+      return accent;
+    case "info":
+      return colors.accent;
+    case "neutral":
+    default:
+      return colors.foregroundMuted;
+  }
+}
+
+/**
+ * Returns background, text, and border styling colors for a given status variant.
+ */
+export function getVariantPalette(
+  variant: StatusVariant,
+  colors: ThemeColors,
+  customAccent?: string,
+): { bg: string; text: string; border: string } {
+  const base = getStatusColor(variant, colors, customAccent);
+  return {
+    bg: alpha(base, 0.12),
+    text: base,
+    border: alpha(base, 0.3),
+  };
+}

package/client/vendor/paseo-plugin-helper/theme/flair.ts

@@ -0,0 +1,76 @@
+export type RadiusStyle = "sharp" | "rounded" | "pill";
+export type DensityStyle = "compact" | "comfortable" | "spacious";
+export type SurfaceStyle = "flat" | "tinted" | "elevated";
+export type HeadingTransform = "none" | "uppercase";
+
+export interface VisualFlair {
+  /**
+   * Corner radius preset for interactive elements and containers.
+   * - "sharp": 2-3px (terminal / technical flair)
+   * - "rounded": 6-8px (default Paseo native flair)
+   * - "pill": 9999px (soft / playful flair)
+   */
+  radius: RadiusStyle;
+
+  /**
+   * Spacing and typography density.
+   * - "compact": tight padding and smaller fonts (the default — plugin UI is
+   *   dense by nature and generous padding wastes vertical space)
+   * - "comfortable": balanced, roomier defaults (opt in per plugin)
+   * - "spacious": generous breathing room
+   */
+  density: DensityStyle;
+
+  /**
+   * Surface background styling for cards, panels, and modal boxes.
+   * - "flat": pure surface0 with border
+   * - "tinted": subtle tinted foreground / accent wash
+   * - "elevated": uses surface1 / surface2 hierarchy
+   */
+  surfaceStyle: SurfaceStyle;
+
+  /**
+   * Optional custom brand accent color (e.g. "#10b981", "#3b82f6").
+   * Overrides Paseo's theme.colors.accent within this plugin.
+   */
+  accentColor?: string;
+
+  /**
+   * Default border width for cards and bordered elements (default: 1).
+   */
+  borderWidth: number;
+
+  /**
+   * Text transform for section headers and meta labels.
+   */
+  headingTransform: HeadingTransform;
+}
+
+export const defaultFlair: VisualFlair = {
+  radius: "rounded",
+  // Compact by default: plugin surfaces are information-dense, and the
+  // comfortable/spacious presets are opt-in per plugin. See xpufx-org/paseo#213.
+  density: "compact",
+  surfaceStyle: "flat",
+  borderWidth: 1,
+  headingTransform: "none",
+};
+
+export function resolveRadius(radius: RadiusStyle, size: "xs" | "sm" | "md" | "lg" | "pill" = "md"): number {
+  if (size === "pill" || radius === "pill") return 9999;
+  if (radius === "sharp") {
+    switch (size) {
+      case "xs": return 1;
+      case "sm": return 2;
+      case "md": return 3;
+      case "lg": return 4;
+    }
+  }
+  // "rounded"
+  switch (size) {
+    case "xs": return 4;
+    case "sm": return 6;
+    case "md": return 8;
+    case "lg": return 12;
+  }
+}

package/client/vendor/paseo-plugin-helper/theme/host-variables.ts

@@ -0,0 +1,121 @@
+import type { ThemeColors } from "../../../../shared/vendor/paseo-plugin-helper/types";
+
+/**
+ * Paseo 0.8 host theme variables. On web hosts the live theme is exposed as
+ * CSS custom properties on the document root; this map binds each variable
+ * to the semantic ThemeColors slot it feeds.
+ */
+export const PASEO_HOST_CSS_VARIABLES = {
+  "--background": "surface0",
+  "--foreground": "foreground",
+  "--muted": "foregroundMuted",
+  "--accent": "accent",
+  "--accent-foreground": "accentForeground",
+  "--border": "border",
+} as const satisfies Record<string, keyof ThemeColors>;
+
+export type PaseoHostCssVariable = keyof typeof PASEO_HOST_CSS_VARIABLES;
+
+export interface HostFontVariables {
+  sans?: string;
+  mono?: string;
+}
+
+export interface HostThemeVariables {
+  colors: Partial<ThemeColors>;
+  fonts: HostFontVariables;
+}
+
+interface StyleReader {
+  getPropertyValue(name: string): string;
+}
+
+interface DomRuntime {
+  document?: {
+    documentElement?: object;
+    defaultView?: {
+      getComputedStyle(target: object): StyleReader;
+    };
+  };
+  getComputedStyle?: (target: object) => StyleReader;
+}
+
+type MutableColors = { -readonly [K in keyof ThemeColors]: ThemeColors[K] };
+
+const HOST_FONT_VARIABLES: Record<"sans" | "mono", string[]> = {
+  sans: ["--font-sans", "--font-family"],
+  mono: ["--font-mono", "--font-family-monospace"],
+};
+
+function readVariable(names: string[]): string | undefined {
+  const runtime = globalThis as unknown as DomRuntime;
+  const doc = runtime.document;
+  if (!doc?.documentElement) return undefined;
+  const getStyle =
+    runtime.getComputedStyle ?? doc.defaultView?.getComputedStyle.bind(doc.defaultView);
+  if (!getStyle) return undefined;
+  try {
+    const computed = getStyle(doc.documentElement);
+    for (const name of names) {
+      const value = computed
+        .getPropertyValue(name)
+        .trim()
+        .replace(/^["']|["']$/g, "");
+      if (value) return value;
+    }
+  } catch {
+    // Non-DOM runtimes (native, tests) have no computed style to read.
+  }
+  return undefined;
+}
+
+/**
+ * Reads the live Paseo 0.8 host variables. Returns empty slots outside a DOM
+ * runtime so native callers merge to static defaults untouched.
+ */
+export function readHostThemeVariables(): HostThemeVariables {
+  const colors: Partial<MutableColors> = {};
+  for (const [variable, slot] of Object.entries(PASEO_HOST_CSS_VARIABLES)) {
+    const value = readVariable([variable]);
+    if (value) {
+      colors[slot] = value;
+    }
+  }
+  const fonts: HostFontVariables = {};
+  const sans = readVariable(HOST_FONT_VARIABLES.sans);
+  if (sans) fonts.sans = sans;
+  const mono = readVariable(HOST_FONT_VARIABLES.mono);
+  if (mono) fonts.mono = mono;
+  return { colors, fonts };
+}
+
+function definedValues<T extends object>(obj: T): Partial<T> {
+  const out: Partial<T> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) {
+      (out as Record<string, unknown>)[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Pure merge for the provider: static defaults lose to live host variables,
+ * which lose to the injected host theme, which loses to the flair accent.
+ * Runtime `undefined` slots are skipped so a partial host theme falls back
+ * instead of blanking a slot. Exported for tests; the provider applies it
+ * inside useMemo.
+ */
+export function mergeThemeColors(
+  defaults: ThemeColors,
+  hostVariables: Partial<ThemeColors>,
+  injected: ThemeColors,
+  accentOverride?: string,
+): ThemeColors {
+  return {
+    ...defaults,
+    ...definedValues(hostVariables),
+    ...definedValues(injected),
+    ...(accentOverride ? { accent: accentOverride } : {}),
+  };
+}

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

@@ -0,0 +1,7 @@
+export * from "./flair";
+export * from "./color-utils";
+export * from "./responsive";
+export * from "./tokens";
+export * from "./host-variables";
+export * from "./provider";
+export * from "./useResponsive";