@xpufx/paseo-twofado 0.1.0

package/client/vendor/paseo-plugin-helper/query-refresh.ts

@@ -0,0 +1,79 @@
+import { useState, useMemo } from "react";
+import type { PluginRpcContract } from "../../../shared/vendor/paseo-plugin-helper/rpc";
+import { useRpcQuery, type RpcQueryOptions } from "./query";
+import type { RpcInput, RpcOutput } from "../../../shared/vendor/paseo-plugin-helper/rpc";
+
+export type RefreshRate =
+  | "1s"
+  | "2s"
+  | "5s"
+  | "10s"
+  | "15s"
+  | "30s"
+  | "60s"
+  | "5m"
+  | "paused";
+
+export const REFRESH_INTERVALS: Record<RefreshRate, number | false> = {
+  "1s": 1000,
+  "2s": 2000,
+  "5s": 5000,
+  "10s": 10000,
+  "15s": 15000,
+  "30s": 30000,
+  "60s": 60000,
+  "5m": 300000,
+  paused: false,
+};
+
+export interface UseAutoRefreshQueryOptions<TOutput> extends RpcQueryOptions<TOutput> {
+  defaultRate?: RefreshRate;
+  /**
+   * Custom interval in milliseconds (overrides preset rates when not paused).
+   */
+  customIntervalMs?: number;
+  /**
+   * Whether the containing modal or panel is actively open/visible.
+   * If false, background refetching is automatically paused to conserve mobile CPU and battery.
+   */
+  isOpen?: boolean;
+}
+
+/**
+ * Enhanced React Query hook for live polling metrics.
+ * Automatically halts background polling when modal/panel is closed (`isOpen === false`),
+ * and provides state controls for user-selectable refresh intervals ("1s", "5s", "30s", "paused", etc.).
+ */
+export function useAutoRefreshQuery<
+  TContract extends PluginRpcContract<any, any>,
+  TInput = RpcInput<TContract>,
+  TOutput = RpcOutput<TContract>,
+>(
+  contract: TContract,
+  input: TInput,
+  options?: UseAutoRefreshQueryOptions<TOutput>,
+) {
+  const { defaultRate = "2s", customIntervalMs, isOpen = true, ...queryOptions } = options ?? {};
+  const [rate, setRate] = useState<RefreshRate>(defaultRate);
+
+  const effectiveInterval = useMemo<number | false>(() => {
+    if (!isOpen || rate === "paused") return false;
+    if (typeof customIntervalMs === "number" && customIntervalMs > 0) {
+      return customIntervalMs;
+    }
+    return REFRESH_INTERVALS[rate] ?? false;
+  }, [isOpen, rate, customIntervalMs]);
+
+  const query = useRpcQuery(contract, input, {
+    ...queryOptions,
+    refetchInterval: effectiveInterval,
+  });
+
+  return {
+    ...query,
+    rate,
+    setRate,
+    isPolling: effectiveInterval !== false,
+    effectiveInterval,
+  };
+}

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

@@ -0,0 +1,66 @@
+import { getClientHost, type HostRpcContract } from "./host";
+import type { PluginRpcContract } from "../../../shared/vendor/paseo-plugin-helper/rpc";
+import type { RpcInput, RpcOutput } from "../../../shared/vendor/paseo-plugin-helper/rpc";
+import {
+  useQuery,
+  useMutation,
+  type UseQueryOptions,
+  type UseQueryResult,
+  type UseMutationOptions,
+  type UseMutationResult,
+} from "@tanstack/react-query";
+
+export type RpcQueryOptions<TOutput> = Omit<
+  UseQueryOptions<TOutput, Error, TOutput, readonly unknown[]>,
+  "queryKey" | "queryFn"
+>;
+
+/**
+ * Executes a Paseo RPC contract as a cached, reactive React Query.
+ * Automatically hashes contract name and input arguments into query keys.
+ */
+export function useRpcQuery<
+  TContract extends PluginRpcContract<any, any>,
+  TInput = RpcInput<TContract>,
+  TOutput = RpcOutput<TContract>,
+>(
+  contract: TContract,
+  input: TInput,
+  options?: RpcQueryOptions<TOutput>,
+): UseQueryResult<TOutput, Error> {
+  const { useRpc } = getClientHost();
+  const callRpc = useRpc(contract);
+
+  return useQuery({
+    queryKey: [contract.name, input],
+    queryFn: () => callRpc(input),
+    ...options,
+  });
+}
+
+export type RpcMutationOptions<TInput, TOutput> = UseMutationOptions<
+  TOutput,
+  Error,
+  TInput,
+  unknown
+>;
+
+/**
+ * Executes a Paseo RPC contract as a mutation (for state changes, write operations).
+ */
+export function useRpcMutation<
+  TContract extends PluginRpcContract<any, any>,
+  TInput = RpcInput<TContract>,
+  TOutput = RpcOutput<TContract>,
+>(
+  contract: TContract,
+  options?: RpcMutationOptions<TInput, TOutput>,
+): UseMutationResult<TOutput, Error, TInput, unknown> {
+  const { useRpc } = getClientHost();
+  const callRpc = useRpc(contract);
+
+  return useMutation({
+    mutationFn: (input: TInput) => callRpc(input),
+    ...options,
+  });
+}

package/client/vendor/paseo-plugin-helper/settings-screen.tsx

@@ -0,0 +1,372 @@
+import React, { type ComponentType, type ReactNode } from "react";
+import type { SettingsContract } from "../../../shared/vendor/paseo-plugin-helper/settings";
+import type { HostSurfaceProps, PluginCleanup } from "./host";
+import { usePluginSettings } from "./settings";
+
+export interface HelperSettingsCardProps {
+  children: ReactNode;
+  testID?: string;
+}
+
+export interface HelperSettingsSectionProps {
+  title: string;
+  info?: ReactNode;
+  trailing?: ReactNode;
+  children: ReactNode;
+  testID?: string;
+}
+
+export interface HelperSettingsRowBaseProps {
+  label: string;
+  hint?: string;
+  error?: string | null;
+  children?: ReactNode;
+  testID?: string;
+}
+
+export interface HelperSettingsSwitchProps extends HelperSettingsRowBaseProps {
+  value: boolean;
+  onValueChange(value: boolean): void;
+  disabled?: boolean;
+}
+
+export interface HelperSettingsSelectProps<Value extends string = string>
+  extends HelperSettingsRowBaseProps {
+  value: Value;
+  options: readonly { label: string; value: Value }[];
+  onValueChange(value: Value): void;
+  disabled?: boolean;
+}
+
+export interface HelperSettingsInputProps extends HelperSettingsRowBaseProps {
+  initialValue?: string;
+  onChangeText(text: string): void;
+  placeholder?: string;
+  disabled?: boolean;
+  secureTextEntry?: boolean;
+}
+
+export type HelperSettingsSelectComponent = <Value extends string = string>(
+  props: HelperSettingsSelectProps<Value>,
+) => ReactNode;
+
+export interface HelperSettingsUiBundle {
+  SettingsCard: ComponentType<HelperSettingsCardProps>;
+  SettingsSection: ComponentType<HelperSettingsSectionProps>;
+  SettingsSwitch: ComponentType<HelperSettingsSwitchProps>;
+  SettingsSelect: HelperSettingsSelectComponent;
+  SettingsInput: ComponentType<HelperSettingsInputProps>;
+}
+
+export interface HelperSettingsScreenContribution {
+  id: string;
+  title: string;
+  icon: string;
+  Component: ComponentType<HostSurfaceProps>;
+}
+
+export interface HelperSettingsScreenRegistrar {
+  addSettingsScreen(contribution: HelperSettingsScreenContribution): PluginCleanup;
+}
+
+export type HelperSettingsFieldKind = "boolean" | "enum" | "string" | "number";
+
+export interface HelperSettingsField {
+  key: string;
+  kind: HelperSettingsFieldKind;
+  label: string;
+  description?: string;
+  options?: string[];
+}
+
+export interface HelperSettingsFieldOverrides {
+  labels?: Record<string, string>;
+  descriptions?: Record<string, string>;
+}
+
+const WRAPPER_TYPES = new Set([
+  "default",
+  "ZodDefault",
+  "prefault",
+  "ZodPrefault",
+  "optional",
+  "ZodOptional",
+  "nullable",
+  "ZodNullable",
+  "readonly",
+  "ZodReadonly",
+  "catch",
+  "ZodCatch",
+  "nonoptional",
+  "ZodNonOptional",
+]);
+
+function readDescription(schema: any): string | undefined {
+  if (!schema || typeof schema !== "object") return undefined;
+  if (typeof schema.description === "string" && schema.description.length > 0) {
+    return schema.description;
+  }
+  const def = schema._def ?? schema._zod?.def;
+  if (def && typeof def.description === "string" && def.description.length > 0) {
+    return def.description;
+  }
+  return undefined;
+}
+
+function readInnerType(schema: any): any {
+  if (!schema || typeof schema !== "object") return undefined;
+  const def = schema._def ?? schema._zod?.def;
+  const inner = def?.innerType ?? schema._def?.innerType ?? schema._zod?.def?.innerType;
+  return inner;
+}
+
+function unwrapField(raw: any): { leaf: any; description?: string } {
+  let current = raw;
+  let description = readDescription(raw);
+  let guard = 0;
+  while (current && typeof current === "object" && guard++ < 20) {
+    const def = current._def ?? current._zod?.def;
+    const type = def?.type ?? def?.typeName;
+    const ctor = current.constructor?.name;
+    if (
+      (typeof type === "string" && WRAPPER_TYPES.has(type)) ||
+      (typeof ctor === "string" && WRAPPER_TYPES.has(ctor))
+    ) {
+      const inner = readInnerType(current);
+      if (!inner || inner === current) break;
+      current = inner;
+      if (!description) description = readDescription(current);
+      continue;
+    }
+    break;
+  }
+  if (!description) description = readDescription(current);
+  return { leaf: current, description };
+}
+
+function leafKind(leaf: any): HelperSettingsFieldKind | undefined {
+  if (!leaf || typeof leaf !== "object") return undefined;
+  const def = leaf._def ?? leaf._zod?.def ?? {};
+  const type = def.type ?? def.typeName;
+  const ctor = leaf.constructor?.name;
+  if (type === "enum" || type === "ZodEnum" || ctor === "ZodEnum") return "enum";
+  if (type === "boolean" || type === "ZodBoolean" || ctor === "ZodBoolean") return "boolean";
+  if (type === "number" || type === "ZodNumber" || ctor === "ZodNumber") return "number";
+  if (
+    type === "string" ||
+    type === "ZodString" ||
+    type === "string_format" ||
+    ctor === "ZodString" ||
+    (typeof ctor === "string" && ctor.startsWith("ZodString"))
+  ) {
+    return "string";
+  }
+  return undefined;
+}
+
+function enumValues(leaf: any): string[] | undefined {
+  const found: unknown[] = [];
+  const sources: any[] = [leaf?._def, leaf?._zod?.def, leaf];
+  for (const source of sources) {
+    if (!source || typeof source !== "object") continue;
+    if (Array.isArray(source.values)) found.push(...source.values);
+    if (Array.isArray(source.options)) {
+      for (const option of source.options) {
+        if (typeof option === "string") found.push(option);
+        else if (option && typeof option === "object" && typeof option.value === "string") {
+          found.push(option.value);
+        }
+      }
+    }
+    if (source.entries && typeof source.entries === "object") {
+      for (const value of Object.values(source.entries)) {
+        if (typeof value === "string") found.push(value);
+      }
+    }
+    if (source.enum && typeof source.enum === "object") {
+      for (const value of Object.values(source.enum)) {
+        if (typeof value === "string") found.push(value);
+      }
+    }
+  }
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const candidate of found) {
+    if (typeof candidate === "string" && !seen.has(candidate)) {
+      seen.add(candidate);
+      out.push(candidate);
+    }
+  }
+  return out.length > 0 ? out : undefined;
+}
+
+function getObjectShape(schema: any): Record<string, any> | undefined {
+  if (!schema || typeof schema !== "object") return undefined;
+  const direct = schema.shape;
+  if (direct && typeof direct === "object" && !Array.isArray(direct)) {
+    return direct as Record<string, any>;
+  }
+  const def = schema._def ?? schema._zod?.def;
+  if (def && def.shape && typeof def.shape === "object") {
+    return def.shape as Record<string, any>;
+  }
+  if (def && typeof def.shape === "function") {
+    try {
+      const resolved = def.shape();
+      if (resolved && typeof resolved === "object") return resolved as Record<string, any>;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+export function contractSchemaToFields(
+  schema: unknown,
+  overrides: HelperSettingsFieldOverrides = {},
+): HelperSettingsField[] {
+  const shape = getObjectShape(schema);
+  if (!shape) {
+    console.warn("paseo-plugin-helper: settings schema has no object shape, no fields mapped");
+    return [];
+  }
+  const fields: HelperSettingsField[] = [];
+  for (const key of Object.keys(shape)) {
+    try {
+      const { leaf, description } = unwrapField(shape[key]);
+      const kind = leafKind(leaf);
+      if (!kind) {
+        console.warn(`paseo-plugin-helper: skipping unsupported settings field "${key}"`);
+        continue;
+      }
+      let options: string[] | undefined;
+      if (kind === "enum") {
+        options = enumValues(leaf);
+        if (!options || options.length === 0) {
+          console.warn(`paseo-plugin-helper: skipping enum settings field "${key}" with no options`);
+          continue;
+        }
+      }
+      const label = overrides.labels?.[key] ?? description ?? key;
+      const hint = overrides.descriptions?.[key] ?? description;
+      fields.push({
+        key,
+        kind,
+        label,
+        ...(hint !== undefined ? { description: hint } : {}),
+        ...(options ? { options } : {}),
+      });
+    } catch {
+      console.warn(`paseo-plugin-helper: skipping unreadable settings field "${key}"`);
+    }
+  }
+  return fields;
+}
+
+export interface RegisterHelperSettingsScreenOptions {
+  ui: HelperSettingsUiBundle;
+  id?: string;
+  title?: string;
+  icon?: string;
+  labels?: Record<string, string>;
+  descriptions?: Record<string, string>;
+}
+
+function createSettingsScreenComponent<TSettings extends Record<string, any>>(
+  contract: SettingsContract<TSettings>,
+  ui: HelperSettingsUiBundle,
+  fields: HelperSettingsField[],
+  sectionTitle: string,
+): ComponentType<HostSurfaceProps> {
+  const Select = ui.SettingsSelect as unknown as ComponentType<
+    HelperSettingsSelectProps<string>
+  >;
+  return function HelperSettingsScreen(_props: HostSurfaceProps) {
+    const { settings, updateSettings } = usePluginSettings(contract);
+    return (
+      <ui.SettingsSection title={sectionTitle}>
+        <ui.SettingsCard>
+          {fields.map((field) => {
+            if (field.kind === "boolean") {
+              return (
+                <ui.SettingsSwitch
+                  key={field.key}
+                  label={field.label}
+                  hint={field.description}
+                  value={Boolean(settings[field.key])}
+                  onValueChange={(value: boolean) =>
+                    updateSettings({ [field.key]: value } as Partial<TSettings>)
+                  }
+                />
+              );
+            }
+            if (field.kind === "enum") {
+              const selectOptions = (field.options ?? []).map((value) => ({ label: value, value }));
+              const current = String(settings[field.key] ?? field.options?.[0] ?? "");
+              return (
+                <Select
+                  key={field.key}
+                  label={field.label}
+                  hint={field.description}
+                  value={current}
+                  options={selectOptions}
+                  onValueChange={(value: string) =>
+                    updateSettings({ [field.key]: value } as Partial<TSettings>)
+                  }
+                />
+              );
+            }
+            const raw = settings[field.key];
+            const currentText = raw === undefined || raw === null ? "" : String(raw);
+            if (field.kind === "number") {
+              return (
+                <ui.SettingsInput
+                  key={field.key}
+                  label={field.label}
+                  hint={field.description}
+                  initialValue={currentText}
+                  onChangeText={(text: string) => {
+                    if (text.trim() === "") return;
+                    const next = Number(text);
+                    if (Number.isNaN(next)) return;
+                    updateSettings({ [field.key]: next } as Partial<TSettings>);
+                  }}
+                />
+              );
+            }
+            return (
+              <ui.SettingsInput
+                key={field.key}
+                label={field.label}
+                hint={field.description}
+                initialValue={currentText}
+                onChangeText={(text: string) =>
+                  updateSettings({ [field.key]: text } as Partial<TSettings>)
+                }
+              />
+            );
+          })}
+        </ui.SettingsCard>
+      </ui.SettingsSection>
+    );
+  };
+}
+
+export function registerHelperSettingsScreen<TSettings extends Record<string, any>>(
+  client: HelperSettingsScreenRegistrar,
+  contract: SettingsContract<TSettings>,
+  options: RegisterHelperSettingsScreenOptions,
+): PluginCleanup {
+  const id = options.id ?? contract.name;
+  const rawDescription = (contract as { description?: unknown }).description;
+  const title =
+    options.title ??
+    (typeof rawDescription === "string" && rawDescription.length > 0 ? rawDescription : contract.name);
+  const icon = options.icon ?? "Settings";
+  const fields = contractSchemaToFields(contract.schema, {
+    labels: options.labels,
+    descriptions: options.descriptions,
+  });
+  const Component = createSettingsScreenComponent(contract, options.ui, fields, title);
+  return client.addSettingsScreen({ id, title, icon, Component });
+}

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

@@ -0,0 +1,181 @@
+import { getClientHost } from "./host";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import type { SettingsContract } from "../../../shared/vendor/paseo-plugin-helper/settings";
+
+export interface UsePluginSettingsOptions<TSettings> {
+  /**
+   * Optional initial settings data. Defaults to `contract.defaultSettings`.
+   */
+  initialData?: TSettings;
+  /**
+   * Whether to automatically refetch settings when the window/app regains focus.
+   * Defaults to true.
+   */
+  refetchOnWindowFocus?: boolean;
+  /**
+   * Stale time in milliseconds before settings are considered stale.
+   * Defaults to 0 so that newly opened modals/components always verify fresh
+   * state against the daemon without waiting.
+   */
+  staleTime?: number;
+  /**
+   * Whether to refetch settings every time a component mounts.
+   * Defaults to "always".
+   */
+  refetchOnMount?: boolean | "always";
+  /**
+   * Optional background polling interval in milliseconds.
+   * When specified, keeps multi-window and mobile/desktop clients automatically in sync.
+   */
+  refetchInterval?: number | false;
+  /**
+   * Callback invoked after a successful update.
+   */
+  onSuccess?: (updated: TSettings) => void;
+  /**
+   * Callback invoked when an update fails.
+   */
+  onError?: (error: Error, rollbackSettings?: TSettings) => void;
+}
+
+export interface UsePluginSettingsResult<TSettings> {
+  /**
+   * Current settings object. Never undefined (falls back to initialData or contract.defaultSettings).
+   */
+  settings: TSettings;
+  /**
+   * Triggers an optimistic update and persists via RPC.
+   */
+  updateSettings: (updates: Partial<TSettings>) => void;
+  /**
+   * Async version of updateSettings that returns a promise of the updated settings.
+   */
+  updateSettingsAsync: (updates: Partial<TSettings>) => Promise<TSettings>;
+  /**
+   * Resets settings back to their default values.
+   */
+  resetSettings: () => Promise<TSettings>;
+  /**
+   * Whether the initial query is loading.
+   */
+  isLoading: boolean;
+  /**
+   * Whether an update mutation is currently in-flight.
+   */
+  isUpdating: boolean;
+  /**
+   * Whether the last query or mutation encountered an error.
+   */
+  isError: boolean;
+  /**
+   * Error object if any error occurred.
+   */
+  error: Error | null;
+  /**
+   * Refetches settings from the server.
+   */
+  refetch: () => Promise<unknown>;
+}
+
+/**
+ * Reactive hook for managing plugin settings with optimistic updates,
+ * error rollbacks, and automatic caching via React Query.
+ */
+export function usePluginSettings<TSettings extends Record<string, any>>(
+  contract: SettingsContract<TSettings>,
+  options: UsePluginSettingsOptions<TSettings> = {},
+): UsePluginSettingsResult<TSettings> {
+  const { useRpc } = getClientHost();
+  const queryClient = useQueryClient();
+  const queryKey = ["plugin-settings", contract.name] as const;
+
+  const callGet = useRpc(contract.get);
+  const callUpdate = useRpc(contract.update);
+  const callReset = useRpc(contract.reset);
+
+  const query = useQuery({
+    queryKey,
+    queryFn: async () => {
+      const res = await callGet({} as any);
+      return res as TSettings;
+    },
+    // Use placeholderData so UI displays immediately without marking the cache as fresh forever
+    placeholderData: (options.initialData ?? contract.defaultSettings) as any,
+    // Ensure newly mounted components (e.g. Opening modal) immediately re-verify from daemon
+    staleTime: options.staleTime ?? 0,
+    refetchOnMount: options.refetchOnMount ?? "always",
+    refetchOnWindowFocus: options.refetchOnWindowFocus ?? true,
+    refetchInterval: options.refetchInterval,
+  });
+
+  const updateMutation = useMutation({
+    mutationFn: async (updates: Partial<TSettings>) => {
+      const res = await callUpdate(updates as any);
+      return res as TSettings;
+    },
+    onMutate: async (newUpdates: Partial<TSettings>) => {
+      await queryClient.cancelQueries({ queryKey });
+      const previousSettings =
+        queryClient.getQueryData<TSettings>(queryKey) ?? contract.defaultSettings;
+
+      const optimistic: TSettings = {
+        ...previousSettings,
+        ...newUpdates,
+      };
+
+      queryClient.setQueryData<TSettings>(queryKey, optimistic);
+      return { previousSettings };
+    },
+    onError: (err: unknown, _newUpdates, context) => {
+      if (context?.previousSettings) {
+        queryClient.setQueryData(queryKey, context.previousSettings);
+      }
+      const error = err instanceof Error ? err : new Error(String(err));
+      options.onError?.(error, context?.previousSettings);
+    },
+    onSuccess: (data: TSettings) => {
+      queryClient.setQueryData(queryKey, data);
+      options.onSuccess?.(data);
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey });
+    },
+  });
+
+  const resetMutation = useMutation({
+    mutationFn: async () => {
+      const res = await callReset({} as any);
+      return res as TSettings;
+    },
+    onSuccess: (data: TSettings) => {
+      queryClient.setQueryData(queryKey, data);
+      options.onSuccess?.(data);
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey });
+    },
+  });
+
+  const settings: TSettings = query.data ?? options.initialData ?? contract.defaultSettings;
+
+  return {
+    settings,
+    updateSettings: (updates: Partial<TSettings>) => {
+      updateMutation.mutate(updates);
+    },
+    updateSettingsAsync: (updates: Partial<TSettings>) => {
+      return updateMutation.mutateAsync(updates);
+    },
+    resetSettings: () => {
+      return resetMutation.mutateAsync();
+    },
+    isLoading: query.isLoading,
+    isUpdating: updateMutation.isPending || resetMutation.isPending,
+    isError: query.isError || updateMutation.isError || resetMutation.isError,
+    error:
+      (query.error as Error | null) ||
+      (updateMutation.error as Error | null) ||
+      (resetMutation.error as Error | null),
+    refetch: () => query.refetch(),
+  };
+}