@hydralms/components 0.2.0 → 0.3.1

package/src/curriculum/course-card.tsx

@@ -0,0 +1,199 @@
+import { memo } from "react";
+import { Clock, Lock, Users } from "lucide-react";
+import { Card, CardContent } from "../ui/card";
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import { UserAvatar } from "../social/user-avatar";
+import { ProgressRing } from "../progress/progress-ring";
+import { cn } from "../lib/utils";
+
+/**
+ * CourseCard displays course info in a card — thumbnail, title, instructor,
+ * progress, category, enrollment status, and CTA.
+ *
+ * @example
+ * <CourseCard
+ *   uid="course-1"
+ *   title="React Fundamentals"
+ *   description="Learn the basics of React."
+ *   instructor={{ displayName: "Jane Doe" }}
+ *   progress={65}
+ *   enrollmentStatus="enrolled"
+ *   onClick={() => navigate("/courses/course-1")}
+ * />
+ */
+export interface CourseCardProps {
+  /** Unique identifier */
+  uid: string;
+  /** Course title */
+  title: string;
+  /** Course description */
+  description?: string;
+  /** Thumbnail image URL */
+  thumbnailUrl?: string;
+  /** Instructor info */
+  instructor?: { displayName: string; avatarUrl?: string };
+  /** Category label */
+  category?: string;
+  /** Progress percentage (0-100), shown when enrolled/completed */
+  progress?: number;
+  /** Enrollment status */
+  enrollmentStatus?: "enrolled" | "completed" | "available" | "locked";
+  /** Number of enrolled students */
+  studentCount?: number;
+  /** Estimated duration (e.g. "12 hours") */
+  duration?: string;
+  /** Called when the card is clicked */
+  onClick?: () => void;
+  /** Called when the enroll button is clicked */
+  onEnroll?: () => void;
+  /** Layout orientation */
+  layout?: "vertical" | "horizontal";
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+const STATUS_BADGE: Record<string, { label: string; variant: "success" | "default" | "muted" | "destructive" }> = {
+  enrolled: { label: "Enrolled", variant: "default" },
+  completed: { label: "Completed", variant: "success" },
+  available: { label: "Available", variant: "muted" },
+  locked: { label: "Locked", variant: "destructive" },
+};
+
+export const CourseCard = memo(function CourseCard({
+  title,
+  description,
+  thumbnailUrl,
+  instructor,
+  category,
+  progress,
+  enrollmentStatus = "available",
+  studentCount,
+  duration,
+  onClick,
+  onEnroll,
+  layout = "vertical",
+  className,
+  style,
+}: CourseCardProps) {
+  const isHorizontal = layout === "horizontal";
+  const statusInfo = STATUS_BADGE[enrollmentStatus];
+  const showProgress = (enrollmentStatus === "enrolled" || enrollmentStatus === "completed") && progress != null;
+  const isLocked = enrollmentStatus === "locked";
+
+  function handleEnrollClick(e: React.MouseEvent) {
+    e.stopPropagation();
+    onEnroll?.();
+  }
+
+  return (
+    <Card
+      data-slot="course-card"
+      className={cn(
+        "overflow-hidden transition-colors",
+        onClick && "cursor-pointer hover:bg-muted/30",
+        isLocked && "opacity-70",
+        className,
+      )}
+      style={style}
+      onClick={onClick}
+    >
+      <div className={cn(isHorizontal ? "flex flex-row" : "flex flex-col")}>
+        {/* Thumbnail */}
+        {thumbnailUrl ? (
+          <div
+            className={cn(
+              "bg-muted bg-cover bg-center shrink-0",
+              isHorizontal ? "w-40 min-h-full" : "h-36 w-full",
+            )}
+            style={{ backgroundImage: `url(${thumbnailUrl})` }}
+          />
+        ) : (
+          <div
+            className={cn(
+              "bg-muted flex items-center justify-center shrink-0",
+              isHorizontal ? "w-40 min-h-full" : "h-36 w-full",
+            )}
+          >
+            <span className="text-3xl text-muted-foreground/40 font-bold">
+              {title.charAt(0)}
+            </span>
+          </div>
+        )}
+
+        {/* Content */}
+        <CardContent className={cn("flex-1 min-w-0", isHorizontal ? "py-3 px-4" : "pt-3 pb-4")}>
+          <div className="flex items-start justify-between gap-2 mb-1">
+            <h3 className="font-semibold text-foreground text-sm leading-tight line-clamp-2">
+              {title}
+            </h3>
+            {showProgress && (
+              <ProgressRing
+                value={progress}
+                size={32}
+                strokeWidth={3}
+                color={enrollmentStatus === "completed" ? "var(--success)" : "var(--primary)"}
+                className="shrink-0"
+              />
+            )}
+          </div>
+
+          {description && (
+            <p className="text-xs text-muted-foreground line-clamp-2 mb-2">
+              {description}
+            </p>
+          )}
+
+          {/* Meta row */}
+          <div className="flex items-center gap-2 flex-wrap mb-2">
+            {category && (
+              <Badge variant="outline" className="text-[10px] px-1.5 py-0">
+                {category}
+              </Badge>
+            )}
+            <Badge variant={statusInfo.variant} className="text-[10px] px-1.5 py-0">
+              {isLocked && <Lock className="size-2.5 mr-0.5" />}
+              {statusInfo.label}
+            </Badge>
+          </div>
+
+          {/* Footer */}
+          <div className="flex items-center justify-between gap-2">
+            <div className="flex items-center gap-3 text-xs text-muted-foreground">
+              {instructor && (
+                <span className="flex items-center gap-1">
+                  <UserAvatar
+                    displayName={instructor.displayName}
+                    avatarUrl={instructor.avatarUrl}
+                    size="small"
+                  />
+                  <span className="truncate max-w-24">{instructor.displayName}</span>
+                </span>
+              )}
+              {duration && (
+                <span className="flex items-center gap-0.5">
+                  <Clock className="size-3" />
+                  {duration}
+                </span>
+              )}
+              {studentCount != null && (
+                <span className="flex items-center gap-0.5">
+                  <Users className="size-3" />
+                  {studentCount}
+                </span>
+              )}
+            </div>
+
+            {onEnroll && enrollmentStatus === "available" && (
+              <Button size="xs" onClick={handleEnrollClick}>
+                Enroll
+              </Button>
+            )}
+          </div>
+        </CardContent>
+      </div>
+    </Card>
+  );
+});

package/src/curriculum/curriculum-item.tsx

@@ -30,10 +30,10 @@ export const CurriculumItemRow = memo(function CurriculumItemRow({
         isActive && "bg-secondary",
       )}
       style={{ paddingLeft: `${(level * 20) + 8}px` }}
-      onClick={onClick}
+      onClick={onClick ? () => onClick(item) : undefined}
       role={onClick ? "button" : undefined}
       tabIndex={onClick ? 0 : undefined}
-      onKeyDown={onClick ? (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onClick(); } } : undefined}
+      onKeyDown={onClick ? (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onClick(item); } } : undefined}
     >
       <div className="shrink-0 flex items-center justify-center size-5">
         {showProgress && isCompleted ? (
@@ -70,7 +70,7 @@ export const CurriculumItemRow = memo(function CurriculumItemRow({
           aria-label={isExpanded ? "Collapse" : "Expand"}
           onClick={(e) => {
             e.stopPropagation();
-            onToggleExpand?.();
+            onToggleExpand?.(item.uid);
           }}
         >
           {isExpanded ? (

package/src/curriculum/curriculum-tree.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { CurriculumItemRow } from "./curriculum-item";
 import type { CurriculumTreeProps, CurriculumItem } from "./types";
 
@@ -14,18 +14,25 @@ export const CurriculumTree = ({
 }: CurriculumTreeProps) => {
   const [expanded, setExpanded] = useState<Record<string, boolean>>({});
 
-  if (!items || items.length === 0) {
-    return null;
-  }
+  const completedUids = useMemo(() => {
+    if (!progress || !showProgress) return new Set<string>();
+    return new Set(
+      progress.filter((p) => p.isCompleted).map((p) => p.resourceUid),
+    );
+  }, [progress, showProgress]);
 
-  const handleToggleExpand = (uid: string) => {
+  const handleToggleExpand = useCallback((uid: string) => {
     setExpanded((prev) => ({ ...prev, [uid]: !prev[uid] }));
-  };
+  }, []);
 
-  const isItemCompleted = (uid: string): boolean => {
-    if (!progress || !showProgress) return false;
-    return progress.some((p) => p.resourceUid === uid && p.isCompleted);
-  };
+  const handleItemClick = useCallback(
+    (item: CurriculumItem) => { onItemClick?.(item); },
+    [onItemClick],
+  );
+
+  if (!items || items.length === 0) {
+    return null;
+  }
 
   const renderItems = (
     nodeItems: CurriculumItem[],
@@ -43,11 +50,11 @@ export const CurriculumTree = ({
                 item={item}
                 level={level}
                 isActive={activeItemUid === item.uid}
-                isCompleted={isItemCompleted(item.uid)}
+                isCompleted={completedUids.has(item.uid)}
                 isExpanded={isExpanded}
                 hasChildren={hasChildren}
-                onToggleExpand={() => handleToggleExpand(item.uid)}
-                onClick={readOnly ? undefined : () => onItemClick?.(item)}
+                onToggleExpand={handleToggleExpand}
+                onClick={readOnly ? undefined : handleItemClick}
                 showDuration={showDuration}
                 showIcon={showIcons}
                 showProgress={showProgress}

package/src/curriculum/index.ts

@@ -1,6 +1,7 @@
 export { CurriculumTree } from "./curriculum-tree";
 export { CurriculumItemRow } from "./curriculum-item";
 export { LearningObjectIcon } from "./learning-object-icon";
+export { CourseCard } from "./course-card";
 
 export type {
   CurriculumItem,
@@ -9,3 +10,4 @@ export type {
   CurriculumItemRowProps,
   LearningObjectIconProps,
 } from "./types";
+export type { CourseCardProps } from "./course-card";

package/src/curriculum/types.ts

@@ -47,8 +47,8 @@ export interface CurriculumItemRowProps {
   isCompleted?: boolean;
   isExpanded?: boolean;
   hasChildren: boolean;
-  onToggleExpand?: () => void;
-  onClick?: () => void;
+  onToggleExpand?: (uid: string) => void;
+  onClick?: (item: CurriculumItem) => void;
   showDuration?: boolean;
   showIcon?: boolean;
   showProgress?: boolean;

package/src/flashcards/flashcard.tsx

@@ -4,12 +4,12 @@ import type { FlashcardProps } from "./types";
 import { cn } from "../lib/utils";
 
 const COLOR_MAP: Record<string, { bg: string; border: string; accent: string }> = {
-  color1: { bg: "bg-blue-50 dark:bg-blue-950/40", border: "border-blue-200 dark:border-blue-800", accent: "bg-blue-200 dark:bg-blue-800" },
-  color2: { bg: "bg-violet-50 dark:bg-violet-950/40", border: "border-violet-200 dark:border-violet-800", accent: "bg-violet-200 dark:bg-violet-800" },
-  color3: { bg: "bg-emerald-50 dark:bg-emerald-950/40", border: "border-emerald-200 dark:border-emerald-800", accent: "bg-emerald-200 dark:bg-emerald-800" },
-  color4: { bg: "bg-amber-50 dark:bg-amber-950/40", border: "border-amber-200 dark:border-amber-800", accent: "bg-amber-200 dark:bg-amber-800" },
-  color5: { bg: "bg-rose-50 dark:bg-rose-950/40", border: "border-rose-200 dark:border-rose-800", accent: "bg-rose-200 dark:bg-rose-800" },
-  color6: { bg: "bg-green-50 dark:bg-green-950/40", border: "border-green-200 dark:border-green-800", accent: "bg-green-200 dark:bg-green-800" },
+  color1: { bg: "bg-palette-0/10", border: "border-palette-0/30", accent: "bg-palette-0/30" },
+  color2: { bg: "bg-palette-1/10", border: "border-palette-1/30", accent: "bg-palette-1/30" },
+  color3: { bg: "bg-palette-2/10", border: "border-palette-2/30", accent: "bg-palette-2/30" },
+  color4: { bg: "bg-palette-3/10", border: "border-palette-3/30", accent: "bg-palette-3/30" },
+  color5: { bg: "bg-info/10", border: "border-info/30", accent: "bg-info/30" },
+  color6: { bg: "bg-success/10", border: "border-success/30", accent: "bg-success/30" },
 };
 
 const SIZE_MAP: Record<string, { width: number; height: number; fontSize: string }> = {
@@ -43,11 +43,21 @@ export const Flashcard = ({
   const { width, height, fontSize } = SIZE_MAP[size];
   const colors = COLOR_MAP[card.color] || COLOR_MAP.color1;
 
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      handleClick();
+    }
+  };
+
   return (
     <div
       className="perspective-[1000px]"
       style={{ width: `${width}px`, height: `${height}px` }}
     >
+      <span className="sr-only" aria-live="polite">
+        {isFlipped ? "Answer revealed" : "Question shown"}
+      </span>
       <div
         className={cn(
           "relative size-full motion-safe:transition-transform motion-safe:duration-500 transform-3d",
@@ -61,8 +71,13 @@ export const Flashcard = ({
             colors.bg,
             colors.border,
             !readOnly && "cursor-pointer",
+            "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
           )}
           onClick={handleClick}
+          onKeyDown={readOnly ? undefined : handleKeyDown}
+          role="button"
+          tabIndex={readOnly ? -1 : 0}
+          aria-label="Flashcard — press Enter to reveal answer"
         >
           <div className="flex flex-1 items-center justify-center p-5 overflow-auto">
             <div
@@ -74,7 +89,7 @@ export const Flashcard = ({
           {!readOnly && (
             <div className="flex items-center justify-center gap-1 pb-3 text-muted-foreground">
               <RotateCcw size={12} />
-              <span className="text-xs">Tap to flip</span>
+              <span className="text-xs">Press Enter to flip</span>
             </div>
           )}
         </div>
@@ -84,8 +99,13 @@ export const Flashcard = ({
           className={cn(
             "absolute inset-0 flex flex-col rounded-lg border border-border bg-background backface-hidden transform-[rotateY(180deg)]",
             !readOnly && "cursor-pointer",
+            "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
           )}
           onClick={handleClick}
+          onKeyDown={readOnly ? undefined : handleKeyDown}
+          role="button"
+          tabIndex={readOnly ? -1 : 0}
+          aria-label="Flashcard answer — press Enter to flip back"
         >
           <div className={cn("h-1.5 rounded-t-lg", colors.accent)} />
           <div className="flex flex-1 items-start justify-center p-5 overflow-auto">
@@ -98,7 +118,7 @@ export const Flashcard = ({
           {!readOnly && (
             <div className="flex items-center justify-center gap-1 pb-3 text-muted-foreground">
               <RotateCcw size={12} />
-              <span className="text-xs">Tap to flip back</span>
+              <span className="text-xs">Press Enter to flip back</span>
             </div>
           )}
         </div>

package/src/index.ts

@@ -34,5 +34,8 @@ export * from "./provider";
 // UI primitives (shadcn/ui + Base UI)
 export * from "./ui";
 
+// License
+export * from "./license";
+
 // Utilities
 export { cn } from "./lib/utils";

package/src/license/HydraContext.tsx

@@ -0,0 +1,62 @@
+import { createContext, useState, useEffect, type ReactNode } from 'react';
+import { validateKey, type KeyResult } from './validate';
+
+export type HydraPlan = 'pro' | 'free' | 'validating' | 'invalid';
+
+export interface HydraLicenseContextValue {
+  plan: HydraPlan;
+  isPro: boolean;
+}
+
+export const HydraLicenseContext = createContext<HydraLicenseContextValue>({
+  plan: 'free',
+  isPro: false,
+});
+
+function keyResultToPlan(result: KeyResult): HydraPlan {
+  switch (result) {
+    case 'valid-pro':
+    case 'skip':
+      return 'pro';
+    case 'valid-free':
+    case 'no-key':
+      return 'free';
+    case 'invalid':
+      return 'invalid';
+  }
+}
+
+export interface HydraLicenseProviderProps {
+  licenseKey?: string;
+  validateUrl?: string;
+  children: ReactNode;
+}
+
+/** Provides license state to all HydraLMS components.
+ * When `validateUrl` is omitted or empty, all features are unlocked (dev mode).
+ */
+export function HydraLicenseProvider({ licenseKey, validateUrl = '', children }: HydraLicenseProviderProps) {
+  const [plan, setPlan] = useState<HydraPlan>(() => {
+    if (!validateUrl) return 'pro';
+    return licenseKey ? 'validating' : 'free';
+  });
+
+  useEffect(() => {
+    if (!validateUrl) {
+      setPlan('pro');
+      return;
+    }
+
+    let cancelled = false;
+    validateKey(licenseKey ?? null, validateUrl).then((result) => {
+      if (!cancelled) setPlan(keyResultToPlan(result));
+    });
+    return () => { cancelled = true; };
+  }, [licenseKey, validateUrl]);
+
+  return (
+    <HydraLicenseContext.Provider value={{ plan, isPro: plan === 'pro' }}>
+      {children}
+    </HydraLicenseContext.Provider>
+  );
+}

package/src/license/ProBadge.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+
+/** Wraps children with a subtle "HydraLMS Pro" upgrade badge when the module requires a pro license. */
+export function ProBadge({ children, feature }: { children: ReactNode; feature?: string }) {
+  return (
+    <div style={{ position: 'relative' }}>
+      {children}
+      <a
+        href="https://hydralms.com/pro"
+        target="_blank"
+        rel="noopener noreferrer"
+        style={{
+          position: 'absolute',
+          bottom: 14,
+          right: 16,
+          zIndex: 9999,
+          display: 'flex',
+          alignItems: 'center',
+          gap: 5,
+          padding: '4px 10px 4px 8px',
+          background: 'rgba(0,0,0,0.5)',
+          backdropFilter: 'blur(6px)',
+          borderRadius: 20,
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+          fontSize: 11,
+          fontWeight: 500,
+          color: 'rgba(255,255,255,0.85)',
+          letterSpacing: '0.01em',
+          whiteSpace: 'nowrap',
+          lineHeight: 1,
+          pointerEvents: 'auto',
+          textDecoration: 'none',
+        }}
+        title={feature ? `"${feature}" is a HydraLMS Pro module` : 'Upgrade to HydraLMS Pro'}
+      >
+        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" style={{ opacity: 0.8 }}>
+          <path d="M12 2.69l5.66 5.66a8 8 0 1 1-11.31 0z" />
+        </svg>
+        HydraLMS Pro
+      </a>
+    </div>
+  );
+}

package/src/license/index.ts

@@ -0,0 +1,7 @@
+export { HydraLicenseProvider, HydraLicenseContext } from './HydraContext';
+export type { HydraPlan, HydraLicenseContextValue, HydraLicenseProviderProps } from './HydraContext';
+export { useHydraLicense } from './useHydraLicense';
+export { isProModule, PRO_MODULES, isProSection, PRO_SECTIONS } from './tiers';
+export type { ProModuleName, ProSectionName } from './tiers';
+export { ProBadge } from './ProBadge';
+export { withProGate } from './withProGate';

package/src/license/tiers.ts

@@ -0,0 +1,34 @@
+// ─── HydraLMS Pro Tier Definitions ──────────────────────────────
+// All 12 modules and premium sections are Pro tier.
+// UI primitives, base components, and standard sections are free.
+
+export const PRO_MODULES = new Set([
+  'QuizModule',
+  'FlashcardLab',
+  'CoursePlayer',
+  'ExamModule',
+  'SurveyModule',
+  'GradeCenterModule',
+  'AssignmentModule',
+  'CertificateModule',
+  'DiscussionModule',
+  'StudentDashboardModule',
+  'CourseCatalogModule',
+  'StudentProfileModule',
+] as const);
+
+export type ProModuleName = typeof PRO_MODULES extends Set<infer T> ? T : never;
+
+export function isProModule(name: string): boolean {
+  return PRO_MODULES.has(name as any);
+}
+
+export const PRO_SECTIONS = new Set([
+  'ContentAuthoringStudio',
+] as const);
+
+export type ProSectionName = typeof PRO_SECTIONS extends Set<infer T> ? T : never;
+
+export function isProSection(name: string): boolean {
+  return PRO_SECTIONS.has(name as any);
+}

package/src/license/useHydraLicense.ts

@@ -0,0 +1,10 @@
+import { useContext } from 'react';
+import { HydraLicenseContext, type HydraLicenseContextValue } from './HydraContext';
+
+/** Returns the current HydraLMS license status. Pro modules render with a
+ * watermark badge when `isPro` is false. Wrap your app in `<HydraProvider>`
+ * with a valid license key to unlock all features.
+ */
+export function useHydraLicense(): HydraLicenseContextValue {
+  return useContext(HydraLicenseContext);
+}

package/src/license/validate.ts

@@ -0,0 +1,90 @@
+// ─── Shared License Validation ──────────────────────────────
+
+const CACHE_KEY = 'hydra_key_v';
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+export type KeyResult = 'valid-pro' | 'valid-free' | 'invalid' | 'no-key' | 'skip';
+
+export interface ValidationResponse {
+  valid: boolean;
+  plan: 'pro' | 'enterprise' | null;
+}
+
+/** Read a cached validation result from sessionStorage. */
+function readCache(rawKey: string): KeyResult | null {
+  try {
+    const cached = sessionStorage.getItem(CACHE_KEY);
+    if (cached) {
+      const { result, ts, key } = JSON.parse(cached) as { result: KeyResult; ts: number; key: string };
+      if (key === rawKey && Date.now() - ts < CACHE_TTL) return result;
+    }
+  } catch { /* sessionStorage unavailable */ }
+  return null;
+}
+
+/** Write a validation result to sessionStorage cache. */
+function writeCache(rawKey: string, result: KeyResult): void {
+  try {
+    sessionStorage.setItem(CACHE_KEY, JSON.stringify({ result, ts: Date.now(), key: rawKey }));
+  } catch { /* full or unavailable */ }
+}
+
+/** On network failure, trust a previously cached valid-pro result. */
+function fallbackFromCache(rawKey: string): KeyResult {
+  try {
+    const cached = sessionStorage.getItem(CACHE_KEY);
+    if (cached) {
+      const { result, key } = JSON.parse(cached) as { result: KeyResult; key: string };
+      if (key === rawKey && result === 'valid-pro') return 'valid-pro';
+    }
+  } catch { /* ignore */ }
+  return 'invalid';
+}
+
+/**
+ * Validate a license key against the validation endpoint.
+ * @param rawKey - The license key string, or null if not provided.
+ * @param validateUrl - The validation endpoint URL. Empty string skips validation (dev mode).
+ */
+export async function validateKey(rawKey: string | null, validateUrl: string): Promise<KeyResult> {
+  // No validation URL configured (local dev) — skip entirely
+  if (!validateUrl) return 'skip';
+
+  // No key provided
+  if (!rawKey) return 'no-key';
+
+  // Check sessionStorage cache
+  const cached = readCache(rawKey);
+  if (cached) return cached;
+
+  // Network validation
+  try {
+    const res = await fetch(`${validateUrl}?key=${encodeURIComponent(rawKey)}`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(4000),
+    });
+
+    if (!res.ok) return fallbackFromCache(rawKey);
+
+    const data = await res.json() as ValidationResponse;
+    let result: KeyResult;
+
+    if (!data.valid) {
+      result = 'invalid';
+    } else if (data.plan === 'pro' || data.plan === 'enterprise') {
+      result = 'valid-pro';
+    } else {
+      result = 'valid-free';
+    }
+
+    writeCache(rawKey, result);
+    return result;
+  } catch {
+    return fallbackFromCache(rawKey);
+  }
+}
+
+/** Whether a watermark should be shown for the given key result. */
+export function shouldShowWatermark(result: KeyResult): boolean {
+  return result === 'no-key' || result === 'invalid' || result === 'valid-free';
+}

package/src/license/withProGate.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import { useHydraLicense } from './useHydraLicense';
+import { ProBadge } from './ProBadge';
+
+/** Higher-order component that wraps a pro-tier module with ProBadge when unlicensed. */
+export function withProGate<P extends object>(
+  Component: React.ComponentType<P>,
+  moduleName: string,
+) {
+  const Gated = (props: P) => {
+    const { isPro } = useHydraLicense();
+    if (isPro) return <Component {...props} />;
+    return (
+      <ProBadge feature={moduleName}>
+        <Component {...props} />
+      </ProBadge>
+    );
+  };
+  Gated.displayName = `ProGated(${moduleName})`;
+  return Gated;
+}