Utilities and Types Reference

Utilities and Types Reference

This page documents Mosaic's utility functions, type definitions, and helper modules.

---

Types (src/types/index.ts)

Node Types

type NodeType = 'root' | 'branch' | 'response' | 'suggestion' | 'distillation';
type EdgeType = 'liquidEdge' | 'tendrilEdge' | 'distillEdge';

NodeData

interface NodeData {
  label: string;
  nodeType: NodeType;
  collapsed?: boolean;
  bookmarked?: boolean;
  confidence?: number;       // 0-100, only for response nodes
  isStreaming?: boolean;
  error?: string;            // Error message if streaming failed
}

EdgeData

interface EdgeData {
  edgeType: EdgeType;
}

CanvasData

interface CanvasData {
  nodes: Node[];
  edges: Edge[];
  viewport?: { x: number; y: number; zoom: number };
  bookmarkedIds?: string[];
}

Model Types

interface ModelOption {
  id: string;                // Model identifier (e.g., 'mistral-large-latest')
  name: string;              // Display name
  provider: ProviderType;
  providerLabel: string;     // Human-readable provider name
  color: string;             // Provider color for UI
}

type ProviderType = 'mistral' | 'openai' | 'anthropic' | 'gemini' | 'ollama';

interface ProviderConfig {
  name: string;
  models: ModelOption[];
  requiresKey: boolean;
  color: string;
}

RAG Types

interface RagDocument {
  id: string;
  filename: string;
  size: number;              // File size in bytes
  chunks: RagChunk[];
}

interface RagChunk {
  id: string;
  text: string;
  embedding?: number[];      // Optional embedding vector
  metadata: {
    documentId: string;
    chunkIndex: number;
  };
}

interface RagSearchResult {
  chunk: RagChunk;
  score: number;             // Cosine similarity score (0-1)
}

Analytics Types

interface CanvasStats {
  totalTokens: number;
  totalCost: number;
  modelBreakdown: Record<string, {
    tokens: number;
    cost: number;
    count: number;
  }>;
  completions: Array<{
    model: string;
    tokens: number;
    cost: number;
    timestamp: number;
  }>;
}

interface NodeStats {
  totalNodes: number;
  branchNodes: number;
  responseNodes: number;
  rootNodes: number;
  totalMessages: number;
  depth: number;              // Maximum conversation tree depth
  branchCount: number;        // Number of branching points
}

Glass UI Types

type SurfaceProfile = 'convex_squircle' | 'convex_circle' | 'concave' | 'lip';
type GlassVariant = 'regular' | 'clear';

interface LensParams {
  width: number;
  height: number;
  surface: SurfaceProfile;
  variant: GlassVariant;
  interactive?: boolean;
}

interface DisplacementMap {
  canvas: HTMLCanvasElement;
  scale: number;
  updatedAt: number;
}

Toast Types

interface Toast {
  id: string;
  type: 'info' | 'success' | 'error';
  message: string;
}

Prune Types

interface PruneState {
  pruneActive: boolean;
  pruneGoal: string;
  isPruning: boolean;
}

---

Code Runner (src/utils/codeRunner.ts)

The code runner manages a Web Worker for sandboxed code execution.

interface CodeResult {
  output: string;             // stdout + returned value
  error?: string;             // Error message if execution failed
  executionTime?: number;     // Execution time in ms
}

Functions

runCode(lang: 'javascript' | 'python', code: string): Promise<CodeResult>

Executes code in the sandboxed worker. Creates the worker on first call.

import { runCode } from '@/utils/codeRunner';

const result = await runCode('javascript', 'console.log("Hello!")');
console.log(result.output); // "Hello!"

Timeout: 30 seconds. Throws on timeout.

replExec(code: string): Promise<CodeResult>

Executes code in the persistent Python REPL environment. Variables persist between calls.

await replExec('x = 42');
const result = await replExec('print(x * 2)');
// result.output === "84"

replReset(): Promise<void>

Resets the Python REPL environment (clears all variables).

terminateWorker(): void

Terminates the Web Worker for cleanup. Called on component unmount.

Worker Communication Protocol

Main Thread → Worker:    { exec_id: string, lang: string, code: string }
Worker → Main Thread:    { exec_id: string, type: 'stdout' | 'result' | 'error', data: string }

---

Validation (src/utils/validation.ts)

function validateNodeData(data: unknown): data is NodeData
function validateImportedCanvas(data: unknown): data is CanvasData
function validateCanvasData(data: unknown): data is CanvasData
function validateRagDocs(data: unknown): data is RagDocument[]
function validateUIState(data: unknown): data is { theme: string; temperature: number; [key: string]: unknown }

All validation functions:

1. Check that input is an object
2. Check required fields exist and have correct types
3. Return true if valid, false otherwise
4. Used by stores on localStorage load to prevent corrupted data from crashing the app

---

Deep Clone (src/utils/deepClone.ts)

function deepClone<T>(obj: T): T

Uses structuredClone() when available (modern browsers) with a manual JSON-based fallback. Used by the undo system to capture state snapshots.

---

Auto-Layout (src/utils/layout.ts)

interface LayoutResult {
  nodes: Node[];
  edges: Edge[];
}

function autoLayout(nodes: Node[], edges: Edge[], startNodeId?: string): LayoutResult

Algorithm: BFS radial tree layout:

1. Find root node (or start node)
2. BFS traversal to determine tree depth and child relationships
3. Position root at center
4. Position children in concentric rings with angular spacing
5. Angular spacing = 2π / childCount at each level
6. Returns new positions for all nodes

---

Encryption (src/utils/encryption.ts)

const SALT = 'MosaicKeySalt';

function encrypt(text: string): string {
  // XOR each character with salt character (cycling)
  // Base64-encode the result
}

function decrypt(encoded: string): string {
  // Base64-decode
  // XOR each character with salt character (cycling)
}

Used for API key storage in localStorage. Not production-grade encryption — prevents casual exposure. API keys are decrypted for use and cached in memory.

---

Provider Config (src/api/config.ts)

const PROVIDERS: Record<string, ProviderConfig> = {
  mistral: {
    name: 'Mistral AI',
    baseUrl: 'https://api.mistral.ai/v1',
    models: [
      { id: 'mistral-large-latest', name: 'Mistral Large', ... },
      { id: 'mistral-small-latest', name: 'Mistral Small', ... },
    ],
    requiresKey: true,
    color: '#3B82F6',
  },
  openai: { ... },
  anthropic: { ... },
  gemini: { ... },
  ollama: {
    name: 'Ollama',
    baseUrl: '',  // Configurable
    models: [],   // Auto-detected
    requiresKey: false,
    color: '#A855F7',
  },
};

API Key Storage

// Store keys in localStorage
const STORAGE_KEYS = {
  mistral: 'mosaic-api-key-mistral',
  openai: 'mosaic-api-key-openai',
  anthropic: 'mosaic-api-key-anthropic',
  gemini: 'mosaic-api-key-gemini',
};
// Ollama has no API key

Keys are XOR-encrypted before storage and decrypted on read. Cached in a runtime Map for performance.

---

Provider Router (src/api/providers.ts)

function streamProvider(
  model: string,
  messages: Message[],
  config: StreamConfig
): Promise<ReadableStreamDefaultReader>

function embedTexts(texts: string[]): Promise<number[][]>

StreamConfig

interface StreamConfig {
  temperature?: number;
  systemPrompt?: string;
  signal?: AbortSignal;      // For cancellation
  onChunk?: (chunk: string) => void;  // Streaming callback
}

Model Routing

Model prefix pattern	Provider function
mistral-*	streamMistral()
gpt-*	streamOpenAI()
claude-*	streamAnthropic()
gemini-*	streamGemini()
anything else	streamOllama()

---

Constants

// File size limits
const MAX_DOCUMENTS = 50;
const MAX_TOTAL_SIZE = 50 * 1024 * 1024;     // 50 MB
const MAX_FILE_SIZE = 10 * 1024 * 1024;       // 10 MB

// Chunking
const CHUNK_SIZE = 800;
const CHUNK_OVERLAP = 100;

// Undo
const MAX_UNDO_HISTORY = 50;

// Code execution
const EXECUTION_TIMEOUT = 30000;              // 30 seconds

// Pruning
const PRUNE_THRESHOLD = 40;

// Streaming
const CONFIDENCE_TIMEOUT = 8000;              // 8 seconds
const TENDRILL_AUTO_DISMISS = 30000;          // 30 seconds

// Analytics
const MAX_COMPLETIONS = 100;
const DEFAULT_TOKEN_RATE = 0.25;              // chars per token

// Pricing
const PRICING: Record<string, { input: number; output: number }> = {
  'mistral-large-latest': { input: 2.00, output: 6.00 },
  'mistral-small-latest': { input: 0.20, output: 0.60 },
  // Other models use defaults
};

// Canvas
const DEFAULT_VIEWPORT = { x: 0, y: 0, zoom: 1 };
const MIN_ZOOM = 0.05;
const MAX_ZOOM = 3;
const SAVE_DEBOUNCE = 300;                    // ms

---

Next Steps

• Store API Reference — All Zustand stores
• Hook API Reference — All custom hooks
• Code Sandbox Architecture — Deep dive into code execution