@flamingo-stack/openframe-frontend-core 0.0.206 → 0.0.207-snapshot.20260526154403

package/src/components/shared/legal-document/use-legal-docs.ts

@@ -0,0 +1,123 @@
+'use client';
+
+/**
+ * useLegalDocs — fetches a legal document (privacy policy, terms of
+ * service, or any other markdown-backed legal page) from a hub API.
+ *
+ * Endpoint configuration — `apiEndpoint`:
+ *   Default `/api/legal/<docType>`. Reverse-proxy embedders override
+ *   with their proxied path (e.g. `/proxy/legal/privacy`).
+ *
+ * Data shape mirrors the hub's `lib/data/legal-utils.ts:LegalDocument`
+ * server type. The hook intentionally re-declares the type here so
+ * lib consumers don't need to import a server-side type.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+
+export interface LegalDocument {
+  title: string;
+  content: string;
+  sourceFile: string;
+  lastSynced: string | null;
+  githubSha: string | null;
+  sections: Array<{ id: string; title: string; level: number }>;
+  docType: string;
+  meta: {
+    sectionsCount: number;
+    contentLength: number;
+    lastSyncedAgo: string;
+  };
+}
+
+export interface UseLegalDocsReturn {
+  data: LegalDocument | null;
+  isLoading: boolean;
+  error: string | null;
+  refetch: () => void;
+}
+
+export interface UseLegalDocsOptions {
+  /** Optional pre-fetched payload from server (SSR / RSC). When set,
+   *  the hook skips the initial client fetch. */
+  initialData?: LegalDocument | null;
+  /** Full GET endpoint URL. Default `/api/legal/<docType>`. */
+  apiEndpoint?: string;
+}
+
+/**
+ * Hook to fetch a legal document.
+ * @param docType — short identifier for the document (drives the
+ *   default endpoint path AND the error-log prefix). Common values:
+ *   `'privacy'` (SECURITY.md), `'terms'` (LICENSE). Embedders may use
+ *   any string — the hook treats it as opaque.
+ */
+export function useLegalDocs(
+  docType: string,
+  options: UseLegalDocsOptions = {}
+): UseLegalDocsReturn {
+  const { initialData = null, apiEndpoint } = options;
+  const effectiveEndpoint = apiEndpoint ?? `/api/legal/${docType}`;
+
+  const [data, setData] = useState<LegalDocument | null>(initialData ?? null);
+  const [isLoading, setIsLoading] = useState(!initialData);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchDocument = useCallback(async () => {
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const response = await fetch(effectiveEndpoint);
+
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch ${docType} document: ${response.status} ${response.statusText}`
+        );
+      }
+
+      const result = await response.json();
+
+      // Validate the response has required fields
+      if (!result.content) {
+        throw new Error(`${docType} document content is empty`);
+      }
+
+      setData(result);
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error occurred';
+      console.error(`Error fetching ${docType} document:`, err);
+      setError(errorMessage);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [docType, effectiveEndpoint]);
+
+  // Reset cached data when docType changes — otherwise an embedder using
+  // the same hook instance for sequential docTypes (privacy → terms)
+  // would briefly render the OLD doc's content while the new fetch is
+  // in-flight. Not currently triggered by hub's per-route SSR (each
+  // docType mounts in a fresh component), but enforces the contract.
+  useEffect(() => {
+    setData(initialData ?? null);
+    setError(null);
+    setIsLoading(!initialData);
+  }, [docType, initialData]);
+
+  // Fetch on mount (only if we don't already have server-provided initialData)
+  useEffect(() => {
+    if (initialData) return;
+    fetchDocument();
+  }, [fetchDocument, initialData]);
+
+  const refetch = () => {
+    fetchDocument();
+  };
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch,
+  };
+}

package/src/components/shared/product-release/index.ts

@@ -8,8 +8,19 @@ export {
   type VideoDisplaySectionProps,
   type MarkdownRendererProps,
   type RoadmapItem,
-  type DeliveryResponse,
-  type RoadmapSectionProps,
-  type DeliverySectionProps
 } from './release-detail-page'
+// NOTE: `RoadmapSectionProps` / `DeliverySectionProps` (the injectable-
+// component slot types for ReleaseDetailPage) are intentionally NOT
+// re-exported from this barrel — they collide with the prop types of
+// the concrete `<RoadmapGrid>` / `<DeliverySection>` components in
+// `./shared/{roadmap,delivery}` (TS2308 ambiguous re-export at the
+// top-level `components/index.ts` barrel). The slot types remain
+// internal to `release-detail-page.tsx`; consumers needing them can
+// import directly from
+// `@flamingo-stack/openframe-frontend-core/components/shared/product-release/release-detail-page`.
+// DeliveryResponse re-sourced from the canonical types module so the
+// public deep-import path `@flamingo-stack/openframe-frontend-core/components`
+// keeps resolving (hub's components/releases/release-detail-page.tsx
+// imports it through this barrel).
+export type { DeliveryResponse } from '../../../types/delivery'
 export { ReleaseDetailSkeleton } from './release-detail-skeleton'

package/src/components/shared/product-release/release-detail-page.tsx

@@ -2,8 +2,10 @@
 
 import { useState, useEffect, ComponentType } from 'react';
 import Link from '../../../embed-shims/next-link';
+import { useRouter } from '../../../embed-shims/next-navigation';
 import { Card, CardContent } from '../../ui/card';
 import { ArticleDetailLayout } from '../../layout/article-detail-layout';
+import { BackButton } from '../../layout/back-button';
 import { ReleaseChangelogSection } from '../../ui/release-changelog-section';
 import { StatusBadge } from '../../ui/status-badge';
 import { SquareAvatar } from '../../ui/square-avatar';
@@ -29,13 +31,15 @@ export interface MarkdownRendererProps {
 // shape once the entities barrel was added; re-exporting the canonical
 // type fixes the collision while keeping the same import path for
 // downstream consumers of `./release-detail-page`.
-export type { RoadmapItem } from '../../chat/types/entities/roadmap-item';
 import type { RoadmapItem } from '../../chat/types/entities/roadmap-item';
-
-export interface DeliveryResponse {
-  completed: unknown[];
-  inProgress: unknown[];
-}
+import type { DeliveryResponse } from '../../../types/delivery';
+// Re-export both types for source-compat with consumers importing
+// through this module. Canonical sources:
+//   - RoadmapItem  → `../../chat/types/entities/roadmap-item`
+//   - DeliveryResponse → `../../../types/delivery` (single source of
+//     truth, shared with the lib `<DeliveryLists>` / `<DeliveryTable>`
+//     components and the new types barrel).
+export type { RoadmapItem, DeliveryResponse };
 
 export interface RoadmapSectionProps {
   items: RoadmapItem[];
@@ -91,6 +95,10 @@ export interface ReleaseDetailPageProps {
   // API endpoints for fetching linked tasks
   roadmapApiEndpoint?: string;
   deliveryApiEndpoint?: string;
+  /** Back-button config — same pattern as `DevSectionPage` /
+   *  `LegalDocumentPage`. Pass `false` to hide. Default
+   *  `{ label: 'Back to home', href: '/' }`. */
+  backButton?: { label?: string; href?: string } | false;
 }
 
 // Default simple markdown renderer (just renders as text)
@@ -108,14 +116,26 @@ export function ReleaseDetailPage({
   VideoSection,
   VideoDisplaySection,
   roadmapApiEndpoint = '/api/roadmap',
-  deliveryApiEndpoint = '/api/delivery'
+  deliveryApiEndpoint = '/api/delivery',
+  backButton
 }: ReleaseDetailPageProps) {
+  const router = useRouter();
   // Use pre-fetched data if provided (admin preview), otherwise fetch via hook (public)
   const { data: fetchedRelease, error, isLoading } = useRelease(initialData ? undefined : slug);
   const release = (initialData || fetchedRelease) as Record<string, unknown> | undefined;
   const [galleryOpen, setGalleryOpen] = useState(false);
   const [galleryIndex, setGalleryIndex] = useState(0);
 
+  // Back-button config — mirrors DevSectionPage / LegalDocumentPage.
+  // Default: { label: 'Back to home', href: '/' }. Pass `false` to hide
+  // (e.g. embed-mode where the host owns navigation chrome).
+  // Narrowing note: `backButton &&` already eliminates the `false` branch,
+  // so the inner expressions are typed as `{ label?, href? } | undefined`.
+  // Don't re-compare to `false` here — tsc TS2367s on the dead branch.
+  const showBackButton = backButton !== false;
+  const backLabel = (backButton ? backButton.label : undefined) ?? 'Back to home';
+  const backHref = (backButton ? backButton.href : undefined) ?? '/';
+
   // Fetch roadmap and delivery tasks if linked to this release
   const [roadmapTasks, setRoadmapTasks] = useState<RoadmapItem[]>([]);
   const [deliveryData, setDeliveryData] = useState<DeliveryResponse | null>(null);
@@ -201,6 +221,15 @@ export function ReleaseDetailPage({
 
   return (
     <ArticleDetailLayout>
+      {/* Back button — desktop-only, matches DevSectionPage / LegalDocumentPage
+          (TitleBlock renders the same `hidden md:inline-flex` BackButton). */}
+      {showBackButton && (
+        <BackButton
+          label={backLabel}
+          onClick={() => router.push(backHref)}
+          className="hidden md:inline-flex mb-4"
+        />
+      )}
       <div className="space-y-6 md:space-y-8">
         {/* Title Block */}
         <div className="flex flex-col md:flex-row md:items-end gap-4 w-full">
@@ -399,22 +428,31 @@ export function ReleaseDetailPage({
           icon={<AlertTriangle className="h-6 w-6" />}
           SimpleMarkdownRenderer={MarkdownRenderer}
         />
+        {/* Features / Bugs / Improvements use `previewFirst` — same
+            progressive-disclosure pattern as the investor-update detail
+            page's Key Highlights / Financial Notes sections. Shows the
+            first entry in full + fade-masks the rest, with a "Show N
+            more / Show less" toggle. Breaking Changes (above) stays
+            fully expanded — it's critical info, not skim-friendly. */}
         <ReleaseChangelogSection
           title="Features Added"
           entries={featuresAdded || []}
           icon={<Sparkles className="h-6 w-6" />}
+          previewFirst
           SimpleMarkdownRenderer={MarkdownRenderer}
         />
         <ReleaseChangelogSection
           title="Bugs Fixed"
           entries={bugFixed || []}
           icon={<Wrench className="h-6 w-6" />}
+          previewFirst
           SimpleMarkdownRenderer={MarkdownRenderer}
         />
         <ReleaseChangelogSection
           title="Improvements"
           entries={improvements || []}
           icon={<TrendingUp className="h-6 w-6" />}
+          previewFirst
           SimpleMarkdownRenderer={MarkdownRenderer}
         />
 

package/src/components/shared/roadmap/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared roadmap surface barrel.
+ *
+ * IMPORTANT: This barrel MUST NOT re-export `RoadmapItem`. The canonical
+ * type is exported via two paths already:
+ *   - `@flamingo-stack/openframe-frontend-core/components/chat`
+ *     (the source of truth at `chat/types/entities/roadmap-item.ts`)
+ *   - `@flamingo-stack/openframe-frontend-core/components` (via
+ *     `./shared/product-release` re-export)
+ *
+ * Adding a third re-export path here would trigger TypeScript's TS2308
+ * ambiguous re-export warning. Consumers needing the type should import
+ * it from one of the two existing paths.
+ */
+
+export { RoadmapGrid, type RoadmapGridProps } from './roadmap-grid';
+export { RoadmapGridSkeleton, type RoadmapGridSkeletonProps } from './roadmap-grid-skeleton';
+// `VoteType` deliberately NOT re-exported — `./chat` already exports
+// the same-shape `VoteType` from `roadmap-card.tsx`; a duplicate path
+// triggers TS2308 ambiguous re-export at the top-level
+// `components/index.ts` barrel. Consumers can import the canonical
+// `VoteType` from `@flamingo-stack/openframe-frontend-core/components/chat`.
+export { useRoadmapVoting, type VoteState, type UseRoadmapVotingOptions } from './use-roadmap-voting';

package/src/components/shared/roadmap/roadmap-grid-skeleton.tsx

@@ -0,0 +1,74 @@
+/**
+ * RoadmapGridSkeleton — loading state for the `/roadmap` grid view.
+ *
+ * Pure JSX (no hooks, no events) — `'use client'` not strictly required
+ * here; tsup's client-entry banner injects it automatically when this
+ * file is bundled into the client output. We match the playbook's
+ * skeleton-file convention (no directive when no hooks).
+ *
+ * NOTE: lib's `chat/entity-cards/roadmap-card.tsx` also exports a
+ * `RoadmapCardSkeleton` — that one is the COMPACT 56px chat-card
+ * variant. This file's internal card-skeleton (340px grid card)
+ * intentionally stays file-internal to avoid the naming collision;
+ * only `RoadmapGridSkeleton` is exported.
+ */
+
+function RoadmapCardSkeleton() {
+  return (
+    <div className="bg-ods-card border border-ods-border rounded-[6px] p-[24px] flex flex-col gap-[16px] min-h-[340px] relative">
+      {/* Status Badge Skeleton - Top Right */}
+      <div className="absolute top-[24px] right-[24px]">
+        <div className="h-[20px] w-[80px] bg-ods-border rounded animate-pulse"></div>
+      </div>
+
+      {/* Icon and title skeleton */}
+      <div className="flex items-center gap-[16px] pr-[120px]">
+        <div className="w-[80px] h-[80px] bg-ods-border rounded-lg flex-shrink-0 animate-pulse"></div>
+        <div className="flex-1 min-w-0 flex flex-col gap-1">
+          <div className="min-h-[48px] flex items-center">
+            <div className="h-[24px] w-full bg-ods-border rounded animate-pulse"></div>
+          </div>
+          <div className="min-h-[20px] flex items-center">
+            <div className="h-[14px] w-1/2 bg-ods-border rounded animate-pulse"></div>
+          </div>
+        </div>
+      </div>
+
+      {/* Description skeleton - exactly 3 lines */}
+      <div className="min-h-[72px] flex items-center">
+        <div className="w-full space-y-2">
+          <div className="h-[24px] bg-ods-border rounded animate-pulse"></div>
+          <div className="h-[24px] bg-ods-border rounded animate-pulse"></div>
+          <div className="h-[24px] w-4/5 bg-ods-border rounded animate-pulse"></div>
+        </div>
+      </div>
+
+      <div className="flex-1"></div>
+
+      {/* Bottom skeleton */}
+      <div className="flex items-center justify-between">
+        <div className="h-[48px] w-[120px] bg-ods-border rounded animate-pulse"></div>
+        <div className="h-[32px] w-[100px] bg-ods-border rounded animate-pulse"></div>
+      </div>
+    </div>
+  );
+}
+
+export interface RoadmapGridSkeletonProps {
+  /** Number of skeleton cards to show. Default 4. */
+  count?: number;
+  /** Show the desktop left margin (~120px) that aligns the grid with
+   *  the page hero's title block. Default `true`. Related-content rails
+   *  inside narrower surfaces (e.g. the release detail page) pass `false`. */
+  showLeftMargin?: boolean;
+}
+
+export function RoadmapGridSkeleton({ count = 4, showLeftMargin = true }: RoadmapGridSkeletonProps) {
+  return (
+    <div className={`grid grid-cols-1 md:grid-cols-2 gap-6 ${showLeftMargin ? 'md:ml-[120px]' : ''}`}>
+      {Array.from({ length: count }).map((_, i) => (
+        <RoadmapCardSkeleton key={i} />
+      ))}
+    </div>
+  );
+}

package/src/components/shared/roadmap/roadmap-grid.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+/**
+ * RoadmapGrid — full-page roadmap surface.
+ *
+ * Renders a responsive 2-col grid of `<RoadmapCard>`s (lib's chat-entity
+ * card, default density), threads voting state through `useRoadmapVoting`,
+ * and follows up a successful vote with a single-task refresh fetch so
+ * the displayed counts stay live.
+ *
+ * Endpoint configuration — `buildRefreshUrl`:
+ *   The single-task refresh hits a PATH-based endpoint
+ *   (`/api/roadmap/<taskId>` by default). A string-concat `refreshEndpoint`
+ *   would silently break embedders whose by-id route is shaped
+ *   differently (e.g. `/api/roadmap?id=…`), so this prop is a function
+ *   builder. The default matches the hub's pre-migration shape.
+ *
+ * Empty state — uses lib's `<EmptyState>` directly (identical API to
+ * hub's, lives in `src/components/empty-state.tsx`).
+ */
+
+import { useState } from 'react';
+import { RoadmapCard } from '../../chat/entity-cards/roadmap-card';
+import { useRoadmapVoting, type UseRoadmapVotingOptions } from './use-roadmap-voting';
+import { EmptyState } from '../../empty-state';
+import type { RoadmapItem } from '../../chat/types/entities/roadmap-item';
+
+const DEFAULT_BUILD_REFRESH_URL = (taskId: string) => `/api/roadmap/${taskId}`;
+
+export interface RoadmapGridProps {
+  items: RoadmapItem[];
+  onItemUpdate?: (updatedItem: RoadmapItem) => void;
+  /** Show the desktop left margin (~120px) that aligns the grid with
+   *  the page hero. Default `true`. Related-content rails pass `false`. */
+  showLeftMargin?: boolean;
+  /** URL builder for the per-task refresh call after a successful vote.
+   *  Function shape because the taskId sits in the URL path, not a
+   *  query param. Default `(t) => \`/api/roadmap/${t}\``. */
+  buildRefreshUrl?: (taskId: string) => string;
+  /** Voting hook options (vote endpoint + storage key) — see
+   *  `useRoadmapVoting`. */
+  votingOptions?: UseRoadmapVotingOptions;
+}
+
+export function RoadmapGrid({
+  items,
+  onItemUpdate,
+  showLeftMargin = true,
+  buildRefreshUrl = DEFAULT_BUILD_REFRESH_URL,
+  votingOptions,
+}: RoadmapGridProps) {
+  const { getVote, toggleVote } = useRoadmapVoting(votingOptions);
+  const [votingTasks, setVotingTasks] = useState<Set<string>>(new Set());
+
+  const handleVote = async (taskId: string, voteType: 'up' | 'down') => {
+    // Prevent double-clicking
+    if (votingTasks.has(taskId)) return;
+
+    setVotingTasks(prev => new Set(prev).add(taskId));
+
+    try {
+      const result = await toggleVote(taskId, voteType);
+
+      if (result.success) {
+        // Refresh the specific task from server
+        const response = await fetch(buildRefreshUrl(taskId));
+        if (response.ok) {
+          const data = await response.json();
+          if (data.item && onItemUpdate) {
+            onItemUpdate(data.item);
+          }
+        }
+      }
+    } finally {
+      setVotingTasks(prev => {
+        const next = new Set(prev);
+        next.delete(taskId);
+        return next;
+      });
+    }
+  };
+
+  if (items.length === 0) {
+    return (
+      <EmptyState
+        type="generic"
+        title="No roadmap items"
+        description="Check back soon for upcoming features and improvements!"
+      />
+    );
+  }
+
+  return (
+    <div className={`grid grid-cols-1 md:grid-cols-2 gap-6 ${showLeftMargin ? 'md:ml-[120px]' : ''}`}>
+      {items.map((item) => (
+        <RoadmapCard
+          key={item.id}
+          item={item}
+          userVote={getVote(item.id)}
+          onVote={(voteType) => handleVote(item.id, voteType)}
+          isVoting={votingTasks.has(item.id)}
+        />
+      ))}
+    </div>
+  );
+}

package/src/components/shared/roadmap/use-roadmap-voting.ts

@@ -0,0 +1,163 @@
+'use client';
+
+/**
+ * useRoadmapVoting — localStorage-backed optimistic voting for roadmap cards.
+ *
+ * One vote per task per user (storage key scoped per `storageKey` option,
+ * default `'roadmap_votes_v1'`). Toggling the same vote removes it;
+ * switching directions sends a remove + add pair so the server's running
+ * totals stay correct.
+ *
+ * Endpoint configuration — `voteApiEndpoint`:
+ *   The hook posts to ONE endpoint (default `/api/roadmap/vote`) for
+ *   BOTH the optimistic add AND the opposite-vote remove. Reverse-proxy
+ *   embedders override this with their proxied path; lib otherwise
+ *   matches the hub's pre-migration call shape.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+
+export type VoteType = 'up' | 'down' | null;
+
+export interface VoteState {
+  [taskId: string]: VoteType;
+}
+
+export interface UseRoadmapVotingOptions {
+  /** Vote endpoint URL. Default `/api/roadmap/vote`. */
+  voteApiEndpoint?: string;
+  /** localStorage key. Default `'roadmap_votes_v1'`. Embedders mounting
+   *  multiple roadmap surfaces in the same origin can scope per-surface
+   *  (e.g. `'roadmap_votes_v1_main'` vs `'roadmap_votes_v1_admin'`) so
+   *  votes don't cross-contaminate. */
+  storageKey?: string;
+}
+
+const DEFAULT_VOTE_ENDPOINT = '/api/roadmap/vote';
+const DEFAULT_STORAGE_KEY = 'roadmap_votes_v1';
+
+export function useRoadmapVoting(options: UseRoadmapVotingOptions = {}) {
+  const voteApiEndpoint = options.voteApiEndpoint ?? DEFAULT_VOTE_ENDPOINT;
+  const storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
+
+  const [votes, setVotes] = useState<VoteState>({});
+  const [isLoading, setIsLoading] = useState(true);
+
+  // Load votes from localStorage. Runs on mount AND whenever `storageKey`
+  // changes — when the key changes mid-lifecycle (e.g. an embedder
+  // remounts with a new namespace), we MUST reset state first so the
+  // save-effect below doesn't write the old key's data into the new
+  // key. We also re-enter the loading phase so the load completes
+  // before any save runs.
+  useEffect(() => {
+    setIsLoading(true);
+    setVotes({});
+    try {
+      const stored = localStorage.getItem(storageKey);
+      if (stored) {
+        setVotes(JSON.parse(stored));
+      }
+    } catch (error) {
+      console.error('[Voting] Error loading votes from localStorage:', error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [storageKey]);
+
+  // Save votes to localStorage whenever they change
+  useEffect(() => {
+    if (!isLoading) {
+      try {
+        localStorage.setItem(storageKey, JSON.stringify(votes));
+      } catch (error) {
+        console.error('[Voting] Error saving votes to localStorage:', error);
+      }
+    }
+  }, [votes, isLoading, storageKey]);
+
+  const getVote = useCallback(
+    (taskId: string): VoteType => {
+      return votes[taskId] || null;
+    },
+    [votes]
+  );
+
+  const toggleVote = useCallback(
+    async (
+      taskId: string,
+      voteType: 'up' | 'down'
+    ): Promise<{ success: boolean; newVote: VoteType; action: 'add' | 'remove' }> => {
+      const currentVote = votes[taskId];
+
+      let newVote: VoteType = null;
+      let action: 'add' | 'remove' = 'add';
+
+      if (currentVote === voteType) {
+        // User clicked same vote - remove it
+        newVote = null;
+        action = 'remove';
+      } else {
+        // User clicked different vote - set it. If they had an opposite
+        // vote, remove that first so the server totals stay consistent.
+        if (currentVote) {
+          await fetch(voteApiEndpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              taskId,
+              voteType: currentVote,
+              action: 'remove',
+            }),
+          }).catch(err => console.error('[Voting] Error removing opposite vote:', err));
+        }
+
+        newVote = voteType;
+        action = 'add';
+      }
+
+      // Optimistic update
+      setVotes(prev => ({
+        ...prev,
+        [taskId]: newVote,
+      }));
+
+      try {
+        const response = await fetch(voteApiEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ taskId, voteType, action }),
+        });
+
+        if (!response.ok) {
+          throw new Error('Vote API request failed');
+        }
+
+        return { success: true, newVote, action };
+      } catch (error) {
+        console.error('[Voting] API error:', error);
+
+        // Revert optimistic update on error
+        setVotes(prev => ({
+          ...prev,
+          [taskId]: currentVote,
+        }));
+
+        return { success: false, newVote: currentVote, action };
+      }
+    },
+    [votes, voteApiEndpoint]
+  );
+
+  const clearVotes = useCallback(() => {
+    setVotes({});
+    localStorage.removeItem(storageKey);
+  }, [storageKey]);
+
+  return {
+    votes,
+    isLoading,
+    getVote,
+    toggleVote,
+    clearVotes,
+  };
+}