feat: introduce citation components from tool-ui with hover popover functionality and schema validation for enhanced citation management

surfsense_web/components/tool-ui/shared/contract.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { parseWithSchema, safeParseWithSchema } from "./parse";
+
+export interface ToolUiContract<T> {
+  schema: z.ZodType<T>;
+  parse: (input: unknown) => T;
+  safeParse: (input: unknown) => T | null;
+}
+
+export function defineToolUiContract<T>(
+  componentName: string,
+  schema: z.ZodType<T>,
+): ToolUiContract<T> {
+  return {
+    schema,
+    parse: (input: unknown) => parseWithSchema(schema, input, componentName),
+    safeParse: (input: unknown) => safeParseWithSchema(schema, input),
+  };
+}

surfsense_web/components/tool-ui/shared/media/aspect-ratio.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+export const AspectRatioSchema = z
+  .enum(["auto", "1:1", "4:3", "16:9", "9:16"])
+  .default("auto");
+
+export type AspectRatio = z.infer<typeof AspectRatioSchema>;
+
+export const MediaFitSchema = z.enum(["cover", "contain"]).default("cover");
+
+export type MediaFit = z.infer<typeof MediaFitSchema>;
+
+export const RATIO_CLASS_MAP: Record<AspectRatio, string> = {
+  auto: "",
+  "1:1": "aspect-square",
+  "4:3": "aspect-[4/3]",
+  "16:9": "aspect-video",
+  "9:16": "aspect-[9/16]",
+};
+
+export function getRatioClass(ratio: AspectRatio): string {
+  return RATIO_CLASS_MAP[ratio];
+}
+
+export function getFitClass(fit: MediaFit): string {
+  return fit === "cover" ? "object-cover" : "object-contain";
+}

surfsense_web/components/tool-ui/shared/media/format-utils.ts

@@ -0,0 +1,30 @@
+export function formatDuration(durationMs: number): string {
+  const totalSeconds = Math.round(durationMs / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (hours > 0) {
+    return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds
+      .toString()
+      .padStart(2, "0")}`;
+  }
+  return `${minutes}:${seconds.toString().padStart(2, "0")}`;
+}
+
+/**
+ * Format file size in bytes to human-readable string.
+ * @example formatFileSize(1024) => "1 KB"
+ * @example formatFileSize(1536000) => "1.5 MB"
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB"];
+  let size = bytes / 1024;
+  let unit = 0;
+  while (size >= 1024 && unit < units.length - 1) {
+    size /= 1024;
+    unit += 1;
+  }
+  return `${size.toFixed(size >= 10 ? 0 : 1)} ${units[unit]}`;
+}

surfsense_web/components/tool-ui/shared/media/index.ts

@@ -0,0 +1,19 @@
+export {
+  AspectRatioSchema,
+  MediaFitSchema,
+  RATIO_CLASS_MAP,
+  getRatioClass,
+  getFitClass,
+  type AspectRatio,
+  type MediaFit,
+} from "./aspect-ratio";
+
+export { OVERLAY_GRADIENT } from "./overlay-gradient";
+
+export { formatDuration, formatFileSize } from "./format-utils";
+
+export { sanitizeHref } from "./sanitize-href";
+export {
+  resolveSafeNavigationHref,
+  openSafeNavigationHref,
+} from "./safe-navigation";

surfsense_web/components/tool-ui/shared/media/overlay-gradient.ts

@@ -0,0 +1,19 @@
+export const OVERLAY_GRADIENT = `linear-gradient(
+  to bottom,
+  hsl(0, 0%, 0%) 0%,
+  hsla(0, 0%, 0%, 0.987) 8.3%,
+  hsla(0, 0%, 0%, 0.951) 16.6%,
+  hsla(0, 0%, 0%, 0.896) 24.6%,
+  hsla(0, 0%, 0%, 0.825) 32.5%,
+  hsla(0, 0%, 0%, 0.741) 40.1%,
+  hsla(0, 0%, 0%, 0.648) 47.6%,
+  hsla(0, 0%, 0%, 0.55) 54.8%,
+  hsla(0, 0%, 0%, 0.45) 61.7%,
+  hsla(0, 0%, 0%, 0.352) 68.3%,
+  hsla(0, 0%, 0%, 0.259) 74.5%,
+  hsla(0, 0%, 0%, 0.175) 80.4%,
+  hsla(0, 0%, 0%, 0.104) 86%,
+  hsla(0, 0%, 0%, 0.049) 91.1%,
+  hsla(0, 0%, 0%, 0.013) 95.8%,
+  hsla(0, 0%, 0%, 0) 100%
+)` as const;

surfsense_web/components/tool-ui/shared/media/safe-navigation.ts

@@ -0,0 +1,23 @@
+import { sanitizeHref } from "./sanitize-href";
+
+export function resolveSafeNavigationHref(
+  ...candidates: Array<string | null | undefined>
+): string | undefined {
+  for (const candidate of candidates) {
+    const safeHref = sanitizeHref(candidate ?? undefined);
+    if (safeHref) {
+      return safeHref;
+    }
+  }
+
+  return undefined;
+}
+
+export function openSafeNavigationHref(href: string | undefined): boolean {
+  if (!href || typeof window === "undefined") {
+    return false;
+  }
+
+  window.open(href, "_blank", "noopener,noreferrer");
+  return true;
+}

surfsense_web/components/tool-ui/shared/media/sanitize-href.ts

@@ -0,0 +1,28 @@
+export function sanitizeHref(href?: string): string | undefined {
+  if (!href) return undefined;
+  const candidate = href.trim();
+  if (!candidate) return undefined;
+
+  if (
+    candidate.startsWith("/") ||
+    candidate.startsWith("./") ||
+    candidate.startsWith("../") ||
+    candidate.startsWith("?") ||
+    candidate.startsWith("#")
+  ) {
+    if (candidate.startsWith("//")) return undefined;
+    // eslint-disable-next-line no-control-regex -- intentionally matching control characters
+    if (/[\u0000-\u001F\u007F]/.test(candidate)) return undefined;
+    return candidate;
+  }
+
+  try {
+    const url = new URL(candidate);
+    if (url.protocol === "http:" || url.protocol === "https:") {
+      return url.toString();
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}

surfsense_web/components/tool-ui/shared/parse.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+function formatZodPath(path: Array<string | number | symbol>): string {
+  if (path.length === 0) return "root";
+  return path
+    .map((segment) =>
+      typeof segment === "number" ? `[${segment}]` : String(segment),
+    )
+    .join(".");
+}
+
+/**
+ * Format Zod errors into a compact `path: message` string.
+ */
+export function formatZodError(error: z.ZodError): string {
+  const parts = error.issues.map((issue) => {
+    const path = formatZodPath(issue.path);
+    return `${path}: ${issue.message}`;
+  });
+
+  return Array.from(new Set(parts)).join("; ");
+}
+
+/**
+ * Parse unknown input and throw a readable error.
+ */
+export function parseWithSchema<T>(
+  schema: z.ZodType<T>,
+  input: unknown,
+  name: string,
+): T {
+  const res = schema.safeParse(input);
+  if (!res.success) {
+    throw new Error(`Invalid ${name} payload: ${formatZodError(res.error)}`);
+  }
+  return res.data;
+}
+
+/**
+ * Parse unknown input, returning `null` instead of throwing on failure.
+ *
+ * Use this in assistant-ui `render` functions where `args` stream in
+ * incrementally and may be incomplete until the tool call finishes.
+ */
+export function safeParseWithSchema<T>(
+  schema: z.ZodType<T>,
+  input: unknown,
+): T | null {
+  const res = schema.safeParse(input);
+  return res.success ? res.data : null;
+}

surfsense_web/components/tool-ui/shared/schema.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+import type { ReactNode } from "react";
+
+/**
+ * Tool UI conventions:
+ * - Serializable schemas are JSON-safe (no callbacks/ReactNode/`className`).
+ * - Schema: `SerializableXSchema`
+ * - Parser: `parseSerializableX(input: unknown)` (throws on invalid)
+ * - Safe parser: `safeParseSerializableX(input: unknown)` (returns `null` on invalid)
+ * - Actions: `LocalActions` for non-receipt actions and `DecisionActions` for consequential actions
+ * - Root attrs: `data-tool-ui-id` + `data-slot`
+ */
+
+/**
+ * Schema for tool UI identity.
+ *
+ * Every tool UI should have a unique identifier that:
+ * - Is stable across re-renders
+ * - Is meaningful (not auto-generated)
+ * - Is unique within the conversation
+ *
+ * Format recommendation: `{component-type}-{semantic-identifier}`
+ * Examples: "data-table-expenses-q3", "option-list-deploy-target"
+ */
+export const ToolUIIdSchema = z.string().min(1);
+
+export type ToolUIId = z.infer<typeof ToolUIIdSchema>;
+
+/**
+ * Primary role of a Tool UI surface in a chat context.
+ */
+export const ToolUIRoleSchema = z.enum([
+  "information",
+  "decision",
+  "control",
+  "state",
+  "composite",
+]);
+
+export type ToolUIRole = z.infer<typeof ToolUIRoleSchema>;
+
+export const ToolUIReceiptOutcomeSchema = z.enum([
+  "success",
+  "partial",
+  "failed",
+  "cancelled",
+]);
+
+export type ToolUIReceiptOutcome = z.infer<typeof ToolUIReceiptOutcomeSchema>;
+
+/**
+ * Optional receipt metadata: a durable summary of an outcome.
+ */
+export const ToolUIReceiptSchema = z.object({
+  outcome: ToolUIReceiptOutcomeSchema,
+  summary: z.string().min(1),
+  identifiers: z.record(z.string(), z.string()).optional(),
+  at: z.string().datetime(),
+});
+
+export type ToolUIReceipt = z.infer<typeof ToolUIReceiptSchema>;
+
+/**
+ * Base schema for Tool UI payloads (id + optional role/receipt).
+ */
+export const ToolUISurfaceSchema = z.object({
+  id: ToolUIIdSchema,
+  role: ToolUIRoleSchema.optional(),
+  receipt: ToolUIReceiptSchema.optional(),
+});
+
+export type ToolUISurface = z.infer<typeof ToolUISurfaceSchema>;
+
+export const ActionSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  /**
+   * Canonical narration the assistant can use after this action is taken.
+   *
+   * Example: "I exported the table as CSV." / "I opened the link in a new tab."
+   */
+  sentence: z.string().optional(),
+  confirmLabel: z.string().optional(),
+  variant: z
+    .enum(["default", "destructive", "secondary", "ghost", "outline"])
+    .optional(),
+  icon: z.custom<ReactNode>().optional(),
+  loading: z.boolean().optional(),
+  disabled: z.boolean().optional(),
+  shortcut: z.string().optional(),
+});
+
+export type Action = z.infer<typeof ActionSchema>;
+export type LocalAction = Action;
+export type DecisionAction = Action;
+
+export const DecisionResultSchema = z.object({
+  kind: z.literal("decision"),
+  version: z.literal(1),
+  decisionId: z.string().min(1),
+  actionId: z.string().min(1),
+  actionLabel: z.string().min(1),
+  at: z.string().datetime(),
+  payload: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type DecisionResult<
+  TPayload extends Record<string, unknown> = Record<string, unknown>,
+> = Omit<z.infer<typeof DecisionResultSchema>, "payload"> & {
+  payload?: TPayload;
+};
+
+export function createDecisionResult<
+  TPayload extends Record<string, unknown> = Record<string, unknown>,
+>(args: {
+  decisionId: string;
+  action: { id: string; label: string };
+  payload?: TPayload;
+}): DecisionResult<TPayload> {
+  return {
+    kind: "decision",
+    version: 1,
+    decisionId: args.decisionId,
+    actionId: args.action.id,
+    actionLabel: args.action.label,
+    at: new Date().toISOString(),
+    payload: args.payload,
+  };
+}
+
+export const ActionButtonsPropsSchema = z.object({
+  actions: z.array(ActionSchema).min(1),
+  align: z.enum(["left", "center", "right"]).optional(),
+  confirmTimeout: z.number().positive().optional(),
+  className: z.string().optional(),
+});
+
+export const SerializableActionSchema = ActionSchema.omit({ icon: true });
+export const SerializableActionsSchema = ActionButtonsPropsSchema.extend({
+  actions: z.array(SerializableActionSchema),
+}).omit({ className: true });
+
+export interface ActionsConfig {
+  items: Action[];
+  align?: "left" | "center" | "right";
+  confirmTimeout?: number;
+}
+
+export const SerializableActionsConfigSchema = z.object({
+  items: z.array(SerializableActionSchema).min(1),
+  align: z.enum(["left", "center", "right"]).optional(),
+  confirmTimeout: z.number().positive().optional(),
+});
+
+export type SerializableActionsConfig = z.infer<
+  typeof SerializableActionsConfigSchema
+>;
+
+export type SerializableAction = z.infer<typeof SerializableActionSchema>;