@toolr/ui-design 0.1.0

package/components/sections/snapshot-browser/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Snapshot Browser — Shared type definitions
+ *
+ * Part of: Sections > Snapshot Browser
+ *
+ * These types define the CONTRACT between the UI layer (this package) and
+ * the Rust/Tauri backend that each app must implement. Every type here has
+ * a 1:1 mapping to a Rust struct returned by Tauri commands.
+ *
+ * IMPORTANT FOR AI AGENTS:
+ * When adding a new field here, the corresponding Rust struct must also be
+ * updated (and vice versa). The serde rename attributes in Rust use camelCase
+ * to match these TypeScript interfaces.
+ *
+ * Data hierarchy:
+ *   SnapshotScope → SnapshotCategory → SnapshotItem → SnapshotEntry
+ *
+ * Example:
+ *   Scope: "Settings (Prompts)"
+ *     Category: "Verifier Prompts"
+ *       Item: "system-prompt"
+ *         Entry: { content: "You are a...", savedAt: "2026-02-25T10:00:00Z" }
+ */
+
+// ---------------------------------------------------------------------------
+// Snapshot data hierarchy
+// ---------------------------------------------------------------------------
+
+/** A single snapshot — one saved version of content */
+export interface SnapshotEntry {
+  id: string
+  content: string
+  savedAt: string
+  label?: string
+}
+
+/** An item containing snapshots (e.g. a specific prompt or file) */
+export interface SnapshotItem {
+  id: string
+  name: string
+  snapshots: SnapshotEntry[]
+}
+
+/** A category containing items (e.g. "Verifier Prompts", "Skills") */
+export interface SnapshotCategory {
+  id: string
+  name: string
+  icon?: string
+  items: SnapshotItem[]
+}
+
+/** A top-level scope containing categories (e.g. "Settings", "Extensions") */
+export interface SnapshotScope {
+  id: string
+  name: string
+  categories: SnapshotCategory[]
+}
+
+// ---------------------------------------------------------------------------
+// API adapter interface
+// ---------------------------------------------------------------------------
+
+/**
+ * SnapshotBrowserApi — The callback interface that each app must implement.
+ *
+ * This is the bridge between the shared UI and the app-specific backend.
+ * Each function maps to a Tauri command (or any other backend).
+ *
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │ RUST BACKEND IMPLEMENTATION GUIDE                                   │
+ * │                                                                     │
+ * │ Each method below corresponds to a Tauri #[tauri::command].         │
+ * │ The Rust reference implementation lives in:                         │
+ * │   configr/main/src-tauri/src/commands/snapshots/                    │
+ * │                                                                     │
+ * │ REQUIRED Tauri commands:                                            │
+ * │                                                                     │
+ * │   delete_snapshot(scope, category, item, snapshot) → void           │
+ * │     Deletes a single snapshot entry by its composite key.           │
+ * │     The four IDs form a unique path to the snapshot.                │
+ * │                                                                     │
+ * │   clear_all_snapshots() → void                                      │
+ * │     Removes all snapshots across all scopes.                        │
+ * │     Should clear the backing store completely.                      │
+ * │                                                                     │
+ * │ STORAGE STRUCTURE (Rust backend must maintain):                     │
+ * │   Snapshots are stored as JSON in the app data directory:           │
+ * │   {app_data_dir}/                                                    │
+ * │   └── snapshots/                                                     │
+ * │       └── {scope}/                                                   │
+ * │           └── {category}/                                            │
+ * │               └── {item}.json  — SnapshotEntry[] serialized         │
+ * │                                                                     │
+ * │ KEY BEHAVIORS the Rust backend must implement:                      │
+ * │ 1. Pruning: when snapshot limit is reached, remove oldest entry     │
+ * │ 2. Atomic writes: use temp file + rename for crash safety           │
+ * │ 3. IDs should be stable (UUID or timestamp-based)                   │
+ * └─────────────────────────────────────────────────────────────────────┘
+ */
+export interface SnapshotBrowserApi {
+  /** Delete a single snapshot by its composite key */
+  deleteSnapshot: (scopeId: string, categoryId: string, itemId: string, snapshotId: string) => Promise<void>
+
+  /** Clear all snapshots across all scopes */
+  clearAllSnapshots: () => Promise<void>
+}

package/components/sections/snapshot-browser/use-snapshot-browser.ts

@@ -0,0 +1,125 @@
+/**
+ * useSnapshotBrowser — State management hook for the snapshot tree browser
+ *
+ * Part of: Sections > Snapshot Browser
+ *
+ * Manages:
+ * - Tree expansion state (expanded scopes, categories, items)
+ * - Search filter with auto-expand on search
+ * - Expand all / collapse all
+ * - Total snapshot count computation
+ * - Delete operations with loading state
+ */
+
+import { useState, useMemo, useEffect, useRef, useCallback } from 'react'
+import type { SnapshotScope, SnapshotBrowserApi } from './types.ts'
+
+export interface UseSnapshotBrowserOptions {
+  scopes: SnapshotScope[]
+  api: SnapshotBrowserApi
+}
+
+export interface UseSnapshotBrowserReturn {
+  searchQuery: string
+  setSearchQuery: (query: string) => void
+  expandedPaths: Set<string>
+  toggleExpand: (path: string) => void
+  expandAll: () => void
+  collapseAll: () => void
+  allExpanded: boolean
+  totalSnapshotCount: number
+  allExpandablePaths: string[]
+  deleteSnapshot: (scopeId: string, categoryId: string, itemId: string, snapshotId: string) => Promise<void>
+  deletingSnapshotId: string | null
+}
+
+function collectExpandablePaths(scopes: SnapshotScope[]): string[] {
+  const paths: string[] = []
+  for (const scope of scopes) {
+    paths.push(scope.id)
+    for (const category of scope.categories) {
+      paths.push(`${scope.id}/${category.id}`)
+      for (const item of category.items) {
+        if (item.snapshots.length > 0) {
+          paths.push(`${scope.id}/${category.id}/${item.id}`)
+        }
+      }
+    }
+  }
+  return paths
+}
+
+function countSnapshots(scopes: SnapshotScope[]): number {
+  let count = 0
+  for (const scope of scopes) {
+    for (const category of scope.categories) {
+      for (const item of category.items) {
+        count += item.snapshots.length
+      }
+    }
+  }
+  return count
+}
+
+export function useSnapshotBrowser({ scopes, api }: UseSnapshotBrowserOptions): UseSnapshotBrowserReturn {
+  const [searchQuery, setSearchQuery] = useState('')
+  const [expandedPaths, setExpandedPaths] = useState<Set<string>>(() => new Set())
+  const [deletingSnapshotId, setDeletingSnapshotId] = useState<string | null>(null)
+  const prevSearchRef = useRef('')
+
+  const allExpandablePaths = useMemo(() => collectExpandablePaths(scopes), [scopes])
+  const totalSnapshotCount = useMemo(() => countSnapshots(scopes), [scopes])
+
+  const allExpanded = allExpandablePaths.length > 0 && allExpandablePaths.every((p: string) => expandedPaths.has(p))
+
+  // Auto-expand all when search query is entered
+  useEffect(() => {
+    if (searchQuery.trim() && !prevSearchRef.current.trim()) {
+      setExpandedPaths(new Set(allExpandablePaths))
+    }
+    prevSearchRef.current = searchQuery
+  }, [searchQuery, allExpandablePaths])
+
+  const toggleExpand = useCallback((path: string) => {
+    setExpandedPaths((prev: Set<string>) => {
+      const next = new Set(prev)
+      if (next.has(path)) {
+        next.delete(path)
+      } else {
+        next.add(path)
+      }
+      return next
+    })
+  }, [])
+
+  const expandAll = useCallback(() => {
+    setExpandedPaths(new Set(allExpandablePaths))
+  }, [allExpandablePaths])
+
+  const collapseAll = useCallback(() => {
+    setExpandedPaths(new Set())
+  }, [])
+
+  const deleteSnapshot = useCallback(async (scopeId: string, categoryId: string, itemId: string, snapshotId: string) => {
+    setDeletingSnapshotId(snapshotId)
+    try {
+      await api.deleteSnapshot(scopeId, categoryId, itemId, snapshotId)
+    } finally {
+      setDeletingSnapshotId(null)
+    }
+  }, [api])
+
+  return {
+    searchQuery,
+    setSearchQuery,
+    expandedPaths,
+    toggleExpand,
+    expandAll,
+    collapseAll,
+    allExpanded,
+    totalSnapshotCount,
+    allExpandablePaths,
+    deleteSnapshot,
+    deletingSnapshotId,
+  }
+}

package/components/sections/snippets-editor/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Snippets Editor — Section barrel export
+ *
+ * This section provides a complete, reusable snippets CRUD editor.
+ * Consuming apps provide data and an API adapter; the component handles
+ * the full UI including search, validation, and two-column layout.
+ *
+ * File structure:
+ * - snippets-editor.tsx     — Main two-column editor component (drop-in usage)
+ * - use-snippets-editor.ts  — Form state & CRUD hook (used by editor, also standalone)
+ * - types.ts                — Shared types and validation regex
+ *
+ * Quick start:
+ *   import { SnippetsEditor } from '@toolr/ui-design'
+ *
+ *   <SnippetsEditor
+ *     api={snippetsApi}
+ *     snippets={currentSnippets}
+ *     title="Skills Snippets"
+ *     description="Define snippets to reuse in skills prompts with {{SNIPPET_NAME}} syntax."
+ *   />
+ */
+
+// Main editor component
+export { SnippetsEditor, type SnippetsEditorProps } from './snippets-editor.tsx'
+
+// Hook for custom UIs
+export { useSnippetsEditor, type UseSnippetsEditorOptions, type UseSnippetsEditorReturn } from './use-snippets-editor.ts'
+
+// Types
+export { SNIPPET_NAME_REGEX, type SnippetData, type SnippetsEditorApi } from './types.ts'

package/components/sections/snippets-editor/snippets-editor.tsx

@@ -0,0 +1,381 @@
+/**
+ * SnippetsEditor — Two-column CRUD editor for prompt snippets
+ *
+ * Part of: Sections > Snippets Editor
+ *
+ * Replicates the configr "Settings > Extensions > [type] > Snippets" page
+ * as a reusable, self-contained component. Left column shows the snippet
+ * list with search; right column shows the editor form.
+ *
+ * Usage:
+ *   <SnippetsEditor
+ *     api={snippetsApi}
+ *     snippets={currentSnippets}
+ *     title="Skills Snippets"
+ *     description="Define snippets to reuse in skills prompts with {{SNIPPET_NAME}} syntax."
+ *   />
+ *
+ * AI agent notes:
+ * - Uses a resizable divider between left sidebar and right editor
+ * - The component is self-contained — no Zustand, no Tauri dependencies
+ * - Consuming apps provide data + API callbacks; this component handles UI
+ * - Dark theme styling matches configr's Catppuccin-inspired palette
+ */
+
+import { useCallback, useRef, useState } from 'react'
+import { Plus, X, Braces, Trash2, RotateCcw, Save } from 'lucide-react'
+import { cn } from '../../lib/cn.ts'
+import { Input } from '../../ui/input.tsx'
+import { ResizableTextarea } from '../../ui/resizable-textarea.tsx'
+import { IconButton } from '../../ui/icon-button.tsx'
+import { useSnippetsEditor } from './use-snippets-editor.ts'
+import type { SnippetData, SnippetsEditorApi } from './types.ts'
+
+export interface SnippetsEditorProps {
+  api: SnippetsEditorApi
+  snippets: SnippetData[]
+  /** Section title, e.g. "Skills Snippets" */
+  title?: string
+  /** Section description, e.g. "Define snippets to reuse in skills prompts..." */
+  description?: string
+  className?: string
+}
+
+const MIN_SIDEBAR = 200
+const MAX_SIDEBAR = 350
+const DEFAULT_SIDEBAR = 260
+
+export function SnippetsEditor({
+  api,
+  snippets,
+  title = 'Snippets',
+  description = 'Define reusable snippets for prompts using {{SNIPPET_NAME}} syntax.',
+  className,
+}: SnippetsEditorProps) {
+  const {
+    selectedName,
+    selectSnippet,
+    searchQuery,
+    setSearchQuery,
+    filteredSnippets,
+    formData,
+    setFormField,
+    formError,
+    isEditing,
+    isAdding,
+    startAdd,
+    cancelForm,
+    save,
+    remove,
+    resetForm,
+    isSaving,
+  } = useSnippetsEditor({ api, snippets })
+
+  // Resizable sidebar
+  const [sidebarWidth, setSidebarWidth] = useState(DEFAULT_SIDEBAR)
+  const dragRef = useRef<{ startX: number; startW: number } | null>(null)
+
+  const onDividerMouseDown = useCallback((e: React.MouseEvent) => {
+    e.preventDefault()
+    dragRef.current = { startX: e.clientX, startW: sidebarWidth }
+    const onMove = (ev: MouseEvent) => {
+      if (!dragRef.current) return
+      const newW = Math.min(MAX_SIDEBAR, Math.max(MIN_SIDEBAR, dragRef.current.startW + ev.clientX - dragRef.current.startX))
+      setSidebarWidth(newW)
+    }
+    const onUp = () => {
+      dragRef.current = null
+      document.removeEventListener('mousemove', onMove)
+      document.removeEventListener('mouseup', onUp)
+    }
+    document.addEventListener('mousemove', onMove)
+    document.addEventListener('mouseup', onUp)
+  }, [sidebarWidth])
+
+  const hasSelection = isEditing || isAdding
+  const nameHasError = formError !== null && (
+    formError.includes('name') || formError.includes('Name') || formError.includes('uppercase') || formError.includes('exists')
+  )
+
+  return (
+    <div className={cn('flex flex-col bg-[#181825] border border-[#313244] rounded-lg overflow-hidden', className)}>
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-[#313244] bg-purple-500/5">
+        <div className="flex items-center gap-2">
+          <Braces className="w-4 h-4 text-purple-400" />
+          <h3 className="text-sm font-medium text-[#cdd6f4]">{title}</h3>
+          <span className="px-2 py-0.5 text-xs rounded-full bg-[#313244] text-[#a6adc8]">
+            {snippets.length}
+          </span>
+        </div>
+        <p className="text-xs text-[#6c7086] hidden sm:block">{description}</p>
+      </div>
+
+      {/* Body: two columns */}
+      <div className="flex flex-1 min-h-[400px]">
+        {/* Left: Snippet list */}
+        <div className="flex flex-col border-r border-[#313244]" style={{ width: sidebarWidth, minWidth: MIN_SIDEBAR }}>
+          {/* Search + Add */}
+          <div className="flex items-center gap-1.5 p-2 border-b border-[#313244]">
+            <div className="flex-1">
+              <Input
+                type="search"
+                value={searchQuery}
+                onChange={setSearchQuery}
+                placeholder="Search snippets..."
+                size="xs"
+              />
+            </div>
+            <IconButton
+              icon={<Plus className="w-3.5 h-3.5" />}
+              onClick={startAdd}
+              size="xs"
+              color="blue"
+              tooltip={{ title: 'Add Snippet', description: 'Create a new snippet' }}
+              disabled={isAdding}
+            />
+          </div>
+
+          {/* Snippet list */}
+          <div className="flex-1 overflow-y-auto">
+            {filteredSnippets.length === 0 && !isAdding && (
+              <div className="text-center py-10 px-4">
+                <Braces className="w-8 h-8 mx-auto text-purple-400/40 mb-3" />
+                <p className="text-xs text-[#6c7086] mb-1">
+                  {searchQuery ? 'No matching snippets' : 'No snippets defined'}
+                </p>
+                <p className="text-[10px] text-[#45475a]">
+                  {searchQuery ? 'Try a different search term' : 'Click + to add your first snippet'}
+                </p>
+              </div>
+            )}
+            {filteredSnippets.map((snippet) => (
+              <SnippetListItem
+                key={snippet.name}
+                snippet={snippet}
+                selected={selectedName === snippet.name}
+                onSelect={() => selectSnippet(snippet.name)}
+                onDelete={() => remove(snippet.name)}
+              />
+            ))}
+          </div>
+        </div>
+
+        {/* Resizable divider */}
+        <div
+          className="w-1 cursor-col-resize bg-transparent hover:bg-blue-500/30 transition-colors flex-shrink-0"
+          onMouseDown={onDividerMouseDown}
+        />
+
+        {/* Right: Editor */}
+        <div className="flex-1 flex flex-col min-w-0">
+          {hasSelection ? (
+            <SnippetForm
+              formData={formData}
+              setFormField={setFormField}
+              formError={formError}
+              nameHasError={nameHasError}
+              isEditing={isEditing}
+              isSaving={isSaving}
+              onSave={save}
+              onReset={resetForm}
+              onDelete={isEditing && selectedName ? () => remove(selectedName) : undefined}
+              onCancel={isAdding ? cancelForm : undefined}
+            />
+          ) : (
+            <div className="flex-1 flex items-center justify-center p-6">
+              <div className="text-center max-w-xs">
+                <Braces className="w-10 h-10 mx-auto text-purple-400/30 mb-4" />
+                <p className="text-sm text-[#6c7086] mb-2">Select a snippet to edit</p>
+                <p className="text-xs text-[#45475a] leading-relaxed">
+                  Choose a snippet from the list, or click{' '}
+                  <span className="text-blue-400">+</span> to create a new one.
+                  Reference snippets in prompts with{' '}
+                  <span className="font-mono text-purple-400">{'{{SNIPPET_NAME}}'}</span> syntax.
+                </p>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Snippet list item
+// ---------------------------------------------------------------------------
+
+interface SnippetListItemProps {
+  snippet: SnippetData
+  selected: boolean
+  onSelect: () => void
+  onDelete: () => void
+}
+
+function SnippetListItem({ snippet, selected, onSelect, onDelete }: SnippetListItemProps) {
+  return (
+    <div
+      className={cn(
+        'group flex items-start gap-2 px-3 py-2.5 cursor-pointer transition-colors border-l-2',
+        selected
+          ? 'bg-[#1e1e2e] border-l-[#89b4fa]'
+          : 'border-l-transparent hover:bg-[#1e1e2e]/50',
+      )}
+      onClick={onSelect}
+    >
+      <div className="flex-1 min-w-0">
+        <p className="text-xs font-mono font-medium text-[#cdd6f4] truncate">
+          {snippet.name}
+        </p>
+        <p className="text-[10px] text-[#6c7086] truncate mt-0.5">
+          {snippet.description}
+        </p>
+        {snippet.value && (
+          <p className="text-[10px] text-[#45475a] truncate mt-0.5 font-mono">
+            {snippet.value.slice(0, 80)}{snippet.value.length > 80 ? '...' : ''}
+          </p>
+        )}
+      </div>
+      <button
+        type="button"
+        onClick={(e) => { e.stopPropagation(); onDelete() }}
+        className="opacity-0 group-hover:opacity-100 mt-0.5 p-0.5 rounded text-[#6c7086] hover:text-red-400 hover:bg-red-500/10 transition-all"
+      >
+        <X className="w-3 h-3" />
+      </button>
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Snippet editor form
+// ---------------------------------------------------------------------------
+
+interface SnippetFormProps {
+  formData: { name: string; description: string; value: string }
+  setFormField: (field: 'name' | 'description' | 'value', value: string) => void
+  formError: string | null
+  nameHasError: boolean
+  isEditing: boolean
+  isSaving: boolean
+  onSave: () => void
+  onReset: () => void
+  onDelete?: () => void
+  onCancel?: () => void
+}
+
+function SnippetForm({
+  formData,
+  setFormField,
+  formError,
+  nameHasError,
+  isEditing,
+  isSaving,
+  onSave,
+  onReset,
+  onDelete,
+  onCancel,
+}: SnippetFormProps) {
+  return (
+    <div className="flex-1 flex flex-col">
+      <div className="flex-1 overflow-y-auto p-4 space-y-4">
+        {/* Name */}
+        <div>
+          <label className="block text-xs text-[#6c7086] mb-1.5">
+            Snippet Name <span className="text-red-400">*</span>
+          </label>
+          <Input
+            value={formData.name}
+            onChange={(val: string) => setFormField('name', val)}
+            placeholder="MY_SNIPPET"
+            error={nameHasError}
+            autoFocus={!isEditing}
+          />
+          <p className="mt-1 text-[10px] text-[#45475a]">
+            Use in prompts as <span className="font-mono text-purple-400">{'{{' + (formData.name || 'NAME') + '}}'}</span>
+          </p>
+        </div>
+
+        {/* Description */}
+        <div>
+          <label className="block text-xs text-[#6c7086] mb-1.5">
+            Description <span className="text-red-400">*</span>
+          </label>
+          <Input
+            value={formData.description}
+            onChange={(val: string) => setFormField('description', val)}
+            placeholder="Describe what this snippet is used for"
+          />
+        </div>
+
+        {/* Value */}
+        <div>
+          <label className="block text-xs text-[#6c7086] mb-1.5">Value</label>
+          <ResizableTextarea
+            mode="code"
+            language="markdown"
+            value={formData.value}
+            onChange={(val) => setFormField('value', val)}
+            minHeight={160}
+          />
+          <p className="mt-1 text-[10px] text-[#45475a]">
+            Can be a single value, multi-line text, or an entire document
+          </p>
+        </div>
+
+        {/* Error */}
+        {formError && (
+          <div className="px-3 py-2 bg-red-500/10 border border-red-500/30 rounded-lg">
+            <p className="text-xs text-red-400">{formError}</p>
+          </div>
+        )}
+      </div>
+
+      {/* Footer actions */}
+      <div className="flex items-center justify-between gap-2 border-t border-[#313244] px-4 py-3">
+        <div>
+          {onDelete && (
+            <IconButton
+              icon={<Trash2 className="w-3.5 h-3.5" />}
+              onClick={onDelete}
+              size="sm"
+              color="red"
+              disabled={isSaving}
+              tooltip={{ title: 'Delete', description: 'Remove this snippet' }}
+            />
+          )}
+        </div>
+        <div className="flex items-center gap-2">
+          {onCancel && (
+            <button
+              type="button"
+              onClick={onCancel}
+              disabled={isSaving}
+              className="rounded-md border border-[#313244] bg-transparent px-3 py-1.5 text-xs text-[#a6adc8] transition-colors hover:bg-[#313244] hover:text-[#cdd6f4] disabled:opacity-50"
+            >
+              Cancel
+            </button>
+          )}
+          <IconButton
+            icon={<RotateCcw className="w-3.5 h-3.5" />}
+            onClick={onReset}
+            size="sm"
+            color="neutral"
+            disabled={isSaving}
+            tooltip={{ title: 'Reset', description: 'Revert to saved values' }}
+          />
+          <button
+            type="button"
+            onClick={onSave}
+            disabled={isSaving}
+            className="flex items-center gap-1.5 rounded-md bg-blue-600 px-3 py-1.5 text-xs text-white transition-colors hover:bg-blue-500 disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <Save className="w-3 h-3" />
+            {isEditing ? 'Save' : 'Add'}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/components/sections/snippets-editor/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Snippets Editor — Shared type definitions
+ *
+ * Part of: Sections > Snippets Editor
+ *
+ * Snippets are reusable text blocks that can be referenced in prompts
+ * using the {{SNIPPET_NAME}} syntax. Each snippet has a name (uppercase
+ * with underscores), a description, and a value that gets substituted
+ * at render time.
+ *
+ * Example usage in a prompt:
+ *   "Follow the coding standards defined in {{CODE_STYLE}}"
+ *
+ * The consuming app is responsible for the actual template substitution.
+ * This UI only manages CRUD operations via the provided API.
+ */
+
+/** A single snippet definition */
+export interface SnippetData {
+  /** Snippet name — must match SNIPPET_NAME_REGEX (e.g., PROJECT_CONTEXT) */
+  name: string
+  /** Human-readable description of what this snippet contains */
+  description: string
+  /** The actual snippet content that gets substituted for {{NAME}} */
+  value: string
+}
+
+/**
+ * Validation regex for snippet names.
+ * Must start with an uppercase letter, followed by uppercase letters, digits, or underscores.
+ * Examples: MY_SNIPPET, CODE_STYLE, ERROR_HANDLING_V2
+ */
+export const SNIPPET_NAME_REGEX = /^[A-Z][A-Z0-9_]*$/
+
+/**
+ * SnippetsEditorApi — The callback interface that consuming apps must implement.
+ *
+ * Each method maps to a backend operation (Tauri command, API call, etc.).
+ * The UI calls these methods and awaits their completion before updating state.
+ */
+export interface SnippetsEditorApi {
+  /** Add a new snippet. Rejects if a snippet with the same name already exists. */
+  addSnippet: (snippet: SnippetData) => Promise<void>
+  /** Update an existing snippet. originalName is used to find the snippet to replace. */
+  updateSnippet: (originalName: string, snippet: SnippetData) => Promise<void>
+  /** Remove a snippet by name. */
+  removeSnippet: (name: string) => Promise<void>
+}