@xpufx/paseo-top 0.4.0

package/shared/vendor/paseo-plugin-helper/highlight.ts

@@ -0,0 +1,184 @@
+/**
+ * Text-run splitting for search highlighting, shared by every helper surface
+ * that paints matched query text and by the forges search surfaces that scroll
+ * to a match. A query is matched literally via `indexOf` on lowercased strings —
+ * never compiled as a regular expression — so user input cannot inject a
+ * pattern.
+ *
+ * Remote forge search is fuzzy: a returned issue may match a query it does not
+ * contain verbatim. When the literal query is absent the splitter highlights
+ * the query's multi-character tokens at word starts, so a fuzzy result still
+ * reads. Callers on a single primary label may additionally opt into marking
+ * the whole field when not even a token hits (`fallbackToWholeField`); callers
+ * that paint many small runs leave it off. `hasFuzzyHighlight` is the
+ * whole-surface test for go-to-match.
+ *
+ * `normalizeSearchQuery` strips surrounding quotes and whitespace for the local
+ * filter/highlight paths; remote search keeps the raw query.
+ */
+
+export interface HighlightPart {
+  /** The run's source text, in its original casing. */
+  text: string;
+  /** True when this run is an occurrence of the (normalized) query. */
+  matched: boolean;
+}
+
+const TOKEN_PATTERN = /[^\p{L}\p{N}]+/u;
+
+/**
+ * Normalize a search query for local matching and highlighting: trim, then peel
+ * any surrounding pair of matching single/double quotes (`"meta"`, `'meta'`,
+ * `""meta""`). Remote forge search keeps the raw query — Forgejo treats quotes
+ * as a phrase operator — so only the local paths normalize, letting quoted and
+ * unquoted input filter and paint identically. A lone quote is left intact.
+ */
+export function normalizeSearchQuery(query: string): string {
+  let value = query.trim();
+  while (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first !== '"' && first !== "'") || first !== last) break;
+    value = value.slice(1, -1).trim();
+  }
+  return value;
+}
+
+export interface HighlightOptions {
+  /**
+   * When true and neither a literal nor a token hit exists, the whole text is
+   * returned as a single matched run so a fuzzy search result is still visibly
+   * marked. Off by default: callers that paint many small runs (label chips,
+   * markdown spans) must not light every one of them up.
+   */
+  fallbackToWholeField?: boolean;
+}
+
+/**
+ * Query pieces used for the token fallback. A query with no literal hit is
+ * split on non-alphanumeric boundaries; single-character tokens are dropped so
+ * a fuzzy query cannot paint a stray letter in every result.
+ */
+function queryTokens(needle: string): string[] {
+  return needle.split(TOKEN_PATTERN).filter((token) => token.length >= 2);
+}
+
+/** True when `index` begins a word (a word-start query token may prefix it). */
+function isWordStartAt(haystack: string, index: number): boolean {
+  return index === 0 || TOKEN_PATTERN.test(haystack[index - 1]);
+}
+
+/** Earliest word-start occurrence of `token` in `haystack` at or after `from`. */
+function firstTokenStart(haystack: string, token: string, from: number): number {
+  let index = haystack.indexOf(token, from);
+  while (index !== -1) {
+    if (isWordStartAt(haystack, index)) return index;
+    index = haystack.indexOf(token, index + 1);
+  }
+  return -1;
+}
+
+/**
+ * Split `text` into alternating unmatched/matched runs for every
+ * case-insensitive occurrence of `query`. Surrounding whitespace and matching
+ * surrounding quotes on the query are ignored; an empty or whitespace-only
+ * query (or empty text) yields the whole text as a single unmatched run.
+ *
+ * When the literal query is absent the splitter highlights the query's
+ * multi-character tokens at word starts. If no token hits either, the text is
+ * left unmatched unless the caller opted into `fallbackToWholeField`, which
+ * marks the whole field so a fuzzy result is never silently unmarked.
+ */
+export function splitHighlightParts(
+  text: string,
+  query: string,
+  options: HighlightOptions = {},
+): HighlightPart[] {
+  const needle = normalizeSearchQuery(query).toLowerCase();
+  if (!needle || !text) return [{ text, matched: false }];
+  const haystack = text.toLowerCase();
+  if (haystack.includes(needle)) return splitLiteralParts(text, haystack, needle);
+  const tokens = queryTokens(needle);
+  const tokenParts = tokens.length ? splitTokenParts(text, haystack, tokens) : null;
+  if (tokenParts) return tokenParts;
+  // Whole-field fallback: a fuzzy result may match on text the query never
+  // contains, so paint the field rather than leave the row unmarked.
+  return options.fallbackToWholeField ? [{ text, matched: true }] : [{ text, matched: false }];
+}
+
+/** Runs for every non-overlapping literal occurrence of `needle`. */
+function splitLiteralParts(text: string, haystack: string, needle: string): HighlightPart[] {
+  const parts: HighlightPart[] = [];
+  let cursor = 0;
+  while (cursor < text.length) {
+    const hit = haystack.indexOf(needle, cursor);
+    if (hit === -1) {
+      parts.push({ text: text.slice(cursor), matched: false });
+      break;
+    }
+    if (hit > cursor) parts.push({ text: text.slice(cursor, hit), matched: false });
+    parts.push({ text: text.slice(hit, hit + needle.length), matched: true });
+    cursor = hit + needle.length;
+  }
+  return parts.length > 0 ? parts : [{ text, matched: false }];
+}
+
+/**
+ * Runs matching any `token` beginning at a word boundary, so a fuzzy query
+ * paints the token that prefixes a word (`meta` inside `metadata`) and never a
+ * fragment mid-word (`eta` inside `metadata`). The longest token wins a shared
+ * start; ties fall to the earliest occurrence. Returns null when no token is
+ * found, letting the caller apply its whole-field policy.
+ */
+function splitTokenParts(
+  text: string,
+  haystack: string,
+  tokens: string[],
+): HighlightPart[] | null {
+  const sorted = [...tokens].sort((a, b) => b.length - a.length);
+  const parts: HighlightPart[] = [];
+  let matchedAny = false;
+  let cursor = 0;
+  while (cursor < text.length) {
+    let best: { index: number; token: string } | null = null;
+    for (const token of sorted) {
+      const index = firstTokenStart(haystack, token, cursor);
+      if (index === -1) continue;
+      if (best === null || index < best.index) best = { index, token };
+    }
+    if (best === null) {
+      parts.push({ text: text.slice(cursor), matched: false });
+      break;
+    }
+    if (best.index > cursor) parts.push({ text: text.slice(cursor, best.index), matched: false });
+    parts.push({ text: text.slice(best.index, best.index + best.token.length), matched: true });
+    matchedAny = true;
+    cursor = best.index + best.token.length;
+  }
+  return matchedAny ? parts : null;
+}
+
+/**
+ * Whether `text` contains the literal trimmed query (case-insensitively) —
+ * the precise, pre-fuzzy test callers use to tell a true hit from the token
+ * fallback.
+ */
+export function hasHighlightMatch(text: string, query: string): boolean {
+  const needle = normalizeSearchQuery(query).toLowerCase();
+  return needle.length > 0 && text.toLowerCase().includes(needle);
+}
+
+/**
+ * Whether `text` highlights at all for the trimmed `query`: a literal hit or,
+ * failing that, a word-start hit for any of the query's multi-character tokens.
+ * Unlike `splitHighlightParts` this never reports the whole-field fallback, so
+ * it pinpoints the result/section that genuinely mentions a fuzzy query rather
+ * than every field.
+ */
+export function hasFuzzyHighlight(text: string, query: string): boolean {
+  const needle = normalizeSearchQuery(query).toLowerCase();
+  if (!needle || !text) return false;
+  const haystack = text.toLowerCase();
+  if (haystack.includes(needle)) return true;
+  return queryTokens(needle).some((token) => firstTokenStart(haystack, token, 0) !== -1);
+}

package/shared/vendor/paseo-plugin-helper/index.ts

@@ -0,0 +1,10 @@
+export * from "./types";
+export * from "./rpc";
+export * from "./formatters";
+export * from "./settings";
+export * from "./suite-settings";
+export * from "./async";
+export * from "./suppressed";
+export * from "./custom-pills";
+export * from "./forge";
+export * from "./highlight";

package/shared/vendor/paseo-plugin-helper/rpc.ts

@@ -0,0 +1,72 @@
+import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
+
+export interface PluginRpcContract<
+  InputSchema extends ZodType = ZodType,
+  OutputSchema extends ZodType = ZodType,
+> {
+  name: string;
+  input: InputSchema;
+  output: OutputSchema;
+}
+
+const RPC_NAME = /^[a-z][a-z0-9._-]*$/;
+
+/**
+ * Define a typed Paseo RPC contract conforming to the Paseo RPC protocol.
+ * Implemented locally without a runtime dependency on the Paseo SDK.
+ */
+export function defineRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
+  definition: { name: string; input: InputSchema; output: OutputSchema },
+): PluginRpcContract<InputSchema, OutputSchema> {
+  const name = definition.name.trim();
+  if (!RPC_NAME.test(name)) {
+    throw new Error(`Invalid plugin RPC method: ${definition.name}`);
+  }
+  return { ...definition, name };
+}
+
+export type RpcInput<TContract> = TContract extends PluginRpcContract<infer TInput, any>
+  ? ZodInput<TInput>
+  : unknown;
+
+export type RpcOutput<TContract> = TContract extends PluginRpcContract<any, infer TOutput>
+  ? ZodOutput<TOutput>
+  : unknown;
+
+export interface DefineRpcOptions<
+  TName extends string = string,
+  TInput extends ZodType = ZodType,
+  TOutput extends ZodType = ZodType,
+> {
+  name: TName;
+  input: TInput;
+  output: TOutput;
+  description?: string;
+}
+
+/**
+ * Enhanced helper for defining a typed Paseo RPC contract with optional description.
+ */
+export function defineContract<
+  TName extends string,
+  TInput extends ZodType,
+  TOutput extends ZodType,
+>(
+  options: DefineRpcOptions<TName, TInput, TOutput>,
+): PluginRpcContract<TInput, TOutput> & { readonly description?: string } {
+  const contract = defineRpc({
+    name: options.name,
+    input: options.input,
+    output: options.output,
+  });
+
+  if (options.description) {
+    Object.defineProperty(contract, "description", {
+      value: options.description,
+      enumerable: true,
+      writable: false,
+    });
+  }
+
+  return contract as PluginRpcContract<TInput, TOutput> & { readonly description?: string };
+}

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

@@ -0,0 +1,138 @@
+import { z, type ZodType } from "zod";
+import { defineContract, type PluginRpcContract } from "./rpc";
+
+export const SettingsEmptyInputSchema = z
+  .union([z.void(), z.record(z.string(), z.unknown())])
+  .optional();
+export type SettingsEmptyInput = z.infer<typeof SettingsEmptyInputSchema>;
+
+export interface SettingsContract<TSettings extends Record<string, any>> {
+  readonly name: string;
+  readonly schema: ZodType<TSettings>;
+  readonly defaultSettings: TSettings;
+  readonly get: PluginRpcContract<ZodType<SettingsEmptyInput>, ZodType<TSettings>>;
+  readonly update: PluginRpcContract<ZodType<Partial<TSettings>>, ZodType<TSettings>>;
+  readonly reset: PluginRpcContract<ZodType<SettingsEmptyInput>, ZodType<TSettings>>;
+  readonly description?: string;
+}
+
+export interface DefineSettingsContractOptions<TSettings extends Record<string, any>> {
+  /**
+   * Unique name for the settings domain (e.g. "top.settings" or "myplugin.config").
+   * Automatically normalizes invalid RPC characters.
+   */
+  name: string;
+  /**
+   * Zod Object schema representing the full settings shape.
+   * Use `.default(...)` on fields to provide default values.
+   */
+  schema: ZodType<TSettings> & { partial?: () => ZodType<Partial<TSettings>> };
+  /**
+   * Optional default data override if schema fields do not all specify `.default()`.
+   */
+  defaultData?: Partial<TSettings>;
+  /**
+   * Optional human-readable description of the settings.
+   */
+  description?: string;
+}
+
+/**
+ * Strips `.default(...)` wrappers recursively from a Zod schema so that
+ * omitted fields remain undefined rather than being populated with default values
+ * during partial updates.
+ */
+function stripDefaults(schema: any): any {
+  if (!schema || typeof schema !== "object") {
+    return schema;
+  }
+  if (schema instanceof z.ZodDefault) {
+    return stripDefaults(schema._def.innerType);
+  }
+  if (schema instanceof z.ZodOptional) {
+    return stripDefaults(schema._def.innerType).optional();
+  }
+  if (schema instanceof z.ZodNullable) {
+    return stripDefaults(schema._def.innerType).nullable();
+  }
+  // Handle ZodEffects, ZodBranded, ZodReadonly, ZodCatch
+  if (schema._def && schema._def.schema) {
+    return stripDefaults(schema._def.schema);
+  }
+  if (schema instanceof z.ZodObject) {
+    const shape = schema.shape;
+    const newShape: Record<string, any> = {};
+    for (const key of Object.keys(shape)) {
+      newShape[key] = stripDefaults(shape[key]).optional();
+    }
+    let res = z.object(newShape);
+    const unknownKeys = (schema._def as any)?.unknownKeys;
+    if (unknownKeys === "passthrough") {
+      res = res.passthrough() as any;
+    } else if (unknownKeys === "strict") {
+      res = res.strict() as any;
+    }
+    return res;
+  }
+  return typeof schema.optional === "function" ? schema.optional() : schema;
+}
+
+/**
+ * Defines a pair of typed Paseo RPC contracts (get, update, reset) for plugin settings.
+ */
+export function defineSettingsContract<TSettings extends Record<string, any>>(
+  options: DefineSettingsContractOptions<TSettings>,
+): SettingsContract<TSettings> {
+  const { name, schema, defaultData, description } = options;
+
+  let computedDefaults: TSettings;
+  try {
+    computedDefaults = schema.parse(defaultData ?? {}) as TSettings;
+  } catch {
+    computedDefaults = (defaultData ?? {}) as TSettings;
+  }
+
+  const sanitizedName = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]/g, "_");
+
+  const partialSchema = (
+    schema instanceof z.ZodObject
+      ? stripDefaults(schema)
+      : typeof (schema as any).partial === "function"
+        ? (schema as any).partial()
+        : z.record(z.string(), z.unknown())
+  ) as ZodType<Partial<TSettings>>;
+
+  const getContract = defineContract({
+    name: `${sanitizedName}.get`,
+    input: SettingsEmptyInputSchema as ZodType<SettingsEmptyInput>,
+    output: schema,
+    description: description ? `Get ${description}` : `Get ${name} settings`,
+  });
+
+  const updateContract = defineContract({
+    name: `${sanitizedName}.update`,
+    input: partialSchema,
+    output: schema,
+    description: description ? `Update ${description}` : `Update ${name} settings`,
+  });
+
+  const resetContract = defineContract({
+    name: `${sanitizedName}.reset`,
+    input: SettingsEmptyInputSchema as ZodType<SettingsEmptyInput>,
+    output: schema,
+    description: description ? `Reset ${description}` : `Reset ${name} settings to defaults`,
+  });
+
+  return {
+    name: sanitizedName,
+    schema,
+    defaultSettings: computedDefaults,
+    get: getContract,
+    update: updateContract,
+    reset: resetContract,
+    ...(description !== undefined ? { description } : {}),
+  };
+}

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

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { defineSettingsContract } from "./settings";
+
+export const SuiteSettingsSchema = z.object({
+  suiteTitle: z.string().default("xpufx Suite"),
+  accentColor: z.string().default("#6366f1"),
+  density: z.enum(["compact", "comfortable", "spacious"]).default("comfortable"),
+  showSuiteTabs: z.boolean().default(true),
+});
+
+export type SuiteSettings = z.infer<typeof SuiteSettingsSchema>;
+
+export const SuiteSettingsContract = defineSettingsContract({
+  name: "xpufx.suite.settings",
+  schema: SuiteSettingsSchema,
+  description: "Shared xpufx suite settings",
+});

package/shared/vendor/paseo-plugin-helper/suppressed.ts

@@ -0,0 +1,31 @@
+export interface SuppressedSink {
+  debug?(message: string, data?: unknown): void;
+  warn?(message: string, data?: unknown): void;
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Surfaces a caught/suppressed error to the plugin log at debug level
+ * (warn when `level: "warn"`). Fire-and-forget `catch(() => undefined)`
+ * sites should route through here so `paseo plugin logs` shows them
+ * when dev debug logging is enabled.
+ */
+export function reportSuppressed(
+  sink: Pick<SuppressedSink, "debug" | "warn"> | undefined,
+  context: string,
+  error: unknown,
+  level: "debug" | "warn" = "debug",
+): void {
+  try {
+    if (level === "warn") {
+      sink?.warn?.(`${context}: ${messageOf(error)}`, error);
+    } else {
+      sink?.debug?.(`${context}: ${messageOf(error)}`, error);
+    }
+  } catch {
+    // Reporting must never throw.
+  }
+}

package/shared/vendor/paseo-plugin-helper/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Structural theme types for Paseo plugins.
+ *
+ * These interfaces mirror the Paseo host theme shapes without importing any
+ * Paseo SDK module, so `paseo-plugin-helper/shared` (and everything
+ * built on it) typechecks and bundles identically against Paseo v0.7 and
+ * Paseo v0.8 SDKs.
+ */
+export interface ThemeColors {
+  readonly surface0: string;
+  readonly surface1: string;
+  readonly surface2: string;
+  readonly border: string;
+  readonly foreground: string;
+  readonly foregroundMuted: string;
+  readonly accent: string;
+  readonly accentForeground: string;
+  readonly statusSuccess: string;
+  readonly statusWarning: string;
+  readonly statusDanger: string;
+}
+
+export interface PluginTheme {
+  readonly colors: ThemeColors;
+}
+
+export type PlatformType = "ios" | "android" | "web";
+
+export interface ResponsiveLayout {
+  compact: boolean;
+  platform: PlatformType;
+  width?: number;
+  height?: number;
+}
+
+export type StatusVariant = "neutral" | "success" | "warning" | "danger" | "accent" | "info";

package/shared/version.ts

@@ -0,0 +1,2 @@
+// Auto-generated by paseo-plugin-helper. Do not edit.
+export const PLUGIN_VERSION = "0.4.0+a50ea39";