cms-renderer 0.0.0 → 0.1.1

package/dist/lib/data-utils.js

@@ -0,0 +1,247 @@
+import {
+  err,
+  ok
+} from "../chunk-HVKFEZBT.js";
+
+// lib/data-utils.ts
+var FetchErrorCode = {
+  INVALID_SLUG: "INVALID_SLUG",
+  NOT_FOUND: "NOT_FOUND",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  TIMEOUT: "TIMEOUT",
+  PARSE_ERROR: "PARSE_ERROR",
+  SERVER_ERROR: "SERVER_ERROR",
+  RETRY_EXHAUSTED: "RETRY_EXHAUSTED"
+};
+var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_RETRIES = 3;
+var DEFAULT_RETRY_DELAY = 1e3;
+var TRANSIENT_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+var mockPages = {
+  demo: {
+    slug: "demo",
+    title: "Demo Page",
+    blocks: [
+      {
+        id: "mock-header-1",
+        type: "header",
+        content: {
+          headline: "Welcome",
+          alignment: "center"
+        }
+      },
+      {
+        id: "mock-article-1",
+        type: "article",
+        content: {
+          headline: "Getting Started",
+          body: "## Introduction\n\nThis is a demo article."
+        }
+      }
+    ]
+  },
+  about: {
+    slug: "about",
+    title: "About Us",
+    blocks: [
+      {
+        id: "mock-header-2",
+        type: "header",
+        content: {
+          headline: "About Our Company",
+          alignment: "left"
+        }
+      }
+    ]
+  }
+};
+function createFetchError(code, message, options = {}) {
+  return { code, message, ...options };
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function exponentialBackoff(baseDelay, attempt) {
+  const jitter = Math.random() * 100;
+  return baseDelay * 2 ** attempt + jitter;
+}
+function isTransientError(error) {
+  if (error instanceof Error) {
+    if (error.name === "TypeError" && error.message.includes("fetch")) {
+      return true;
+    }
+    for (const code of TRANSIENT_STATUS_CODES) {
+      if (error.message.includes(String(code))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+async function simulateFetch(slug, signal) {
+  await delay(50 + Math.random() * 100);
+  if (signal?.aborted) {
+    throw new Error("Request aborted");
+  }
+  const page = mockPages[slug];
+  if (!page) {
+    const error = new Error(`Page not found: ${slug}`);
+    error.name = "NotFoundError";
+    throw error;
+  }
+  return page;
+}
+async function fetchPageV1(slug) {
+  return simulateFetch(slug);
+}
+async function fetchPageV2(slug) {
+  try {
+    if (!slug || typeof slug !== "string") {
+      return null;
+    }
+    return await simulateFetch(slug);
+  } catch {
+    return null;
+  }
+}
+async function fetchPageV3(slug, options = {}) {
+  const {
+    timeout = DEFAULT_TIMEOUT,
+    retries = DEFAULT_RETRIES,
+    retryDelay = DEFAULT_RETRY_DELAY,
+    signal: externalSignal
+  } = options;
+  if (slug === null || slug === void 0) {
+    return err(
+      createFetchError(
+        FetchErrorCode.INVALID_SLUG,
+        `Slug must be a string, received ${slug === null ? "null" : "undefined"}`
+      )
+    );
+  }
+  if (typeof slug !== "string") {
+    return err(
+      createFetchError(
+        FetchErrorCode.INVALID_SLUG,
+        `Slug must be a string, received ${typeof slug}`
+      )
+    );
+  }
+  const trimmedSlug = slug.trim();
+  if (trimmedSlug.length === 0) {
+    return err(createFetchError(FetchErrorCode.INVALID_SLUG, "Slug cannot be empty"));
+  }
+  const controller = new AbortController();
+  const { signal } = controller;
+  if (externalSignal) {
+    externalSignal.addEventListener("abort", () => controller.abort());
+  }
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  let lastError;
+  let attempt = 0;
+  try {
+    while (attempt <= retries) {
+      try {
+        const page = await simulateFetch(trimmedSlug, signal);
+        clearTimeout(timeoutId);
+        return ok(page);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (signal.aborted) {
+          clearTimeout(timeoutId);
+          return err(
+            createFetchError(FetchErrorCode.TIMEOUT, `Request timed out after ${timeout}ms`, {
+              cause: lastError
+            })
+          );
+        }
+        if (lastError.name === "NotFoundError") {
+          clearTimeout(timeoutId);
+          return err(
+            createFetchError(FetchErrorCode.NOT_FOUND, `Page "${trimmedSlug}" not found`, {
+              cause: lastError
+            })
+          );
+        }
+        if (attempt < retries && isTransientError(lastError)) {
+          attempt++;
+          const backoff = exponentialBackoff(retryDelay, attempt);
+          if (process.env.NODE_ENV === "development") {
+            console.warn(
+              `[fetchPageV3] Retry ${attempt}/${retries} for "${trimmedSlug}" after ${Math.round(backoff)}ms`
+            );
+          }
+          await delay(backoff);
+          continue;
+        }
+        break;
+      }
+    }
+    clearTimeout(timeoutId);
+    if (attempt >= retries) {
+      return err(
+        createFetchError(FetchErrorCode.RETRY_EXHAUSTED, `Failed after ${retries} retry attempts`, {
+          cause: lastError,
+          retryCount: attempt
+        })
+      );
+    }
+    return err(
+      createFetchError(
+        FetchErrorCode.NETWORK_ERROR,
+        lastError?.message ?? "Unknown network error",
+        { cause: lastError }
+      )
+    );
+  } catch (error) {
+    clearTimeout(timeoutId);
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return err(
+      createFetchError(FetchErrorCode.SERVER_ERROR, `Unexpected error: ${cause.message}`, { cause })
+    );
+  }
+}
+var fetchPage = fetchPageV3;
+function isValidSlug(slug) {
+  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug);
+}
+function normalizeSlug(input) {
+  return input.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+async function prefetchPages(slugs, options) {
+  return Promise.all(slugs.map((slug) => fetchPageV3(slug, options)));
+}
+async function fetchPageWithSWR(slug, cache, options = {}) {
+  const { maxAge = 6e4 } = options;
+  const cached = cache.get(slug);
+  const now = Date.now();
+  if (cached && now - cached.timestamp < maxAge) {
+    return ok(cached.data);
+  }
+  const result = await fetchPageV3(slug, options);
+  if (result.ok) {
+    cache.set(slug, { data: result.value, timestamp: now });
+  }
+  if (!result.ok && cached) {
+    if (process.env.NODE_ENV === "development") {
+      console.warn(
+        `[fetchPageWithSWR] Returning stale cache for "${slug}" after fetch failure:`,
+        result.error.message
+      );
+    }
+    return ok(cached.data);
+  }
+  return result;
+}
+export {
+  FetchErrorCode,
+  fetchPage,
+  fetchPageV1,
+  fetchPageV2,
+  fetchPageV3,
+  fetchPageWithSWR,
+  isValidSlug,
+  normalizeSlug,
+  prefetchPages
+};
+//# sourceMappingURL=data-utils.js.map

package/dist/lib/data-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../lib/data-utils.ts"],"sourcesContent":["/**\n * Data Fetching Utilities\n *\n * Three implementations showing the progression from naive to production-ready:\n * - v1 (Naive): Direct await, crashes on any error\n * - v2 (Defensive): Try-catch with null fallback\n * - v3 (Robust): Result type, retry logic, timeout support\n *\n * The robust version (v3) is exported as the default `fetchPage`.\n */\n\nimport { err, ok, type Result } from './result';\nimport type { BlockData } from './types';\n\n// -----------------------------------------------------------------------------\n// Types\n// -----------------------------------------------------------------------------\n\n/**\n * Page structure returned by the tRPC API.\n */\nexport interface Page {\n  slug: string;\n  title: string;\n  blocks: BlockData[];\n}\n\n/**\n * Error codes for data fetching failures.\n */\nexport const FetchErrorCode = {\n  INVALID_SLUG: 'INVALID_SLUG',\n  NOT_FOUND: 'NOT_FOUND',\n  NETWORK_ERROR: 'NETWORK_ERROR',\n  TIMEOUT: 'TIMEOUT',\n  PARSE_ERROR: 'PARSE_ERROR',\n  SERVER_ERROR: 'SERVER_ERROR',\n  RETRY_EXHAUSTED: 'RETRY_EXHAUSTED',\n} as const;\n\nexport type FetchErrorCode = (typeof FetchErrorCode)[keyof typeof FetchErrorCode];\n\n/**\n * Structured error for data fetching failures.\n */\nexport interface FetchError {\n  code: FetchErrorCode;\n  message: string;\n  cause?: Error;\n  retryCount?: number;\n}\n\n/**\n * Options for robust data fetching.\n */\nexport interface FetchOptions {\n  /**\n   * Timeout in milliseconds.\n   * @default 10000 (10 seconds)\n   */\n  timeout?: number;\n\n  /**\n   * Number of retry attempts for transient failures.\n   * @default 3\n   */\n  retries?: number;\n\n  /**\n   * Base delay between retries in milliseconds.\n   * Uses exponential backoff: delay * 2^attempt\n   * @default 1000 (1 second)\n   */\n  retryDelay?: number;\n\n  /**\n   * AbortSignal for cancellation support.\n   */\n  signal?: AbortSignal;\n}\n\n// -----------------------------------------------------------------------------\n// Constants\n// -----------------------------------------------------------------------------\n\nconst DEFAULT_TIMEOUT = 10_000; // 10 seconds\nconst DEFAULT_RETRIES = 3;\nconst DEFAULT_RETRY_DELAY = 1_000; // 1 second\n\n/**\n * HTTP status codes that indicate transient failures (should retry).\n */\nconst TRANSIENT_STATUS_CODES = [408, 429, 500, 502, 503, 504] as const;\n\n// -----------------------------------------------------------------------------\n// Mock Data Store (for demonstration)\n// -----------------------------------------------------------------------------\n\n/**\n * Simulated data store.\n * In production, this would be replaced with actual tRPC/API calls.\n */\nconst mockPages: Record<string, Page> = {\n  demo: {\n    slug: 'demo',\n    title: 'Demo Page',\n    blocks: [\n      {\n        id: 'mock-header-1',\n        type: 'header',\n        content: {\n          headline: 'Welcome',\n          alignment: 'center',\n        },\n      },\n      {\n        id: 'mock-article-1',\n        type: 'article',\n        content: {\n          headline: 'Getting Started',\n          body: '## Introduction\\n\\nThis is a demo article.',\n        },\n      },\n    ],\n  },\n  about: {\n    slug: 'about',\n    title: 'About Us',\n    blocks: [\n      {\n        id: 'mock-header-2',\n        type: 'header',\n        content: {\n          headline: 'About Our Company',\n          alignment: 'left',\n        },\n      },\n    ],\n  },\n};\n\n// -----------------------------------------------------------------------------\n// Helper Functions\n// -----------------------------------------------------------------------------\n\n/**\n * Creates a FetchError with the given code and message.\n */\nfunction createFetchError(\n  code: FetchErrorCode,\n  message: string,\n  options: { cause?: Error; retryCount?: number } = {}\n): FetchError {\n  return { code, message, ...options };\n}\n\n/**\n * Delays execution for the specified duration.\n */\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Calculates exponential backoff delay.\n */\nfunction exponentialBackoff(baseDelay: number, attempt: number): number {\n  // Add jitter to prevent thundering herd\n  const jitter = Math.random() * 100;\n  return baseDelay * 2 ** attempt + jitter;\n}\n\n/**\n * Checks if an error represents a transient failure that should be retried.\n */\nfunction isTransientError(error: unknown): boolean {\n  if (error instanceof Error) {\n    // Network errors\n    if (error.name === 'TypeError' && error.message.includes('fetch')) {\n      return true;\n    }\n    // Check for HTTP status codes in error message\n    for (const code of TRANSIENT_STATUS_CODES) {\n      if (error.message.includes(String(code))) {\n        return true;\n      }\n    }\n  }\n  return false;\n}\n\n/**\n * Simulates a network request with configurable behavior.\n * In production, this would be an actual fetch/tRPC call.\n */\nasync function simulateFetch(slug: string, signal?: AbortSignal): Promise<Page> {\n  // Simulate network latency\n  await delay(50 + Math.random() * 100);\n\n  // Check for cancellation\n  if (signal?.aborted) {\n    throw new Error('Request aborted');\n  }\n\n  const page = mockPages[slug];\n  if (!page) {\n    const error = new Error(`Page not found: ${slug}`);\n    error.name = 'NotFoundError';\n    throw error;\n  }\n\n  return page;\n}\n\n// -----------------------------------------------------------------------------\n// V1: Naive Implementation\n// -----------------------------------------------------------------------------\n\n/**\n * Naive data fetcher - crashes on any error.\n *\n * DO NOT USE IN PRODUCTION. This is for demonstration only.\n *\n * Problems:\n * - No input validation\n * - No error handling\n * - Will crash the entire app on network failure\n * - No timeout protection\n * - No retry logic for transient failures\n *\n * @example\n * ```ts\n * // This throws if slug is invalid or network fails\n * const page = await fetchPageV1('demo');\n * ```\n */\nexport async function fetchPageV1(slug: string): Promise<Page> {\n  // Direct await - any error crashes the caller\n  return simulateFetch(slug);\n}\n\n// -----------------------------------------------------------------------------\n// V2: Defensive Implementation\n// -----------------------------------------------------------------------------\n\n/**\n * Defensive data fetcher - catches errors but loses context.\n *\n * Better than v1 but still problematic:\n * - Returns null on any error (loses error details)\n * - Caller can't distinguish between 404 and network failure\n * - No retry logic for transient failures\n * - No timeout protection\n *\n * @example\n * ```ts\n * const page = await fetchPageV2(slug);\n * if (!page) {\n *   // What went wrong? 404? Network? Timeout? We don't know.\n *   return <NotFound />;\n * }\n * ```\n */\nexport async function fetchPageV2(slug: string): Promise<Page | null> {\n  try {\n    // Basic validation\n    if (!slug || typeof slug !== 'string') {\n      return null;\n    }\n\n    return await simulateFetch(slug);\n  } catch {\n    // All errors become null - we lose valuable context\n    return null;\n  }\n}\n\n// -----------------------------------------------------------------------------\n// V3: Robust Implementation\n// -----------------------------------------------------------------------------\n\n/**\n * Robust data fetcher - production-ready with full error context.\n *\n * Features:\n * - Input validation with specific error codes\n * - Result type for explicit error handling\n * - Automatic retry with exponential backoff\n * - Timeout support via AbortController\n * - Distinguishes between error types (404 vs network vs timeout)\n * - Preserves error context for debugging\n *\n * @param slug - Page slug to fetch\n * @param options - Fetch options (timeout, retries, etc.)\n * @returns Result containing the page data or a structured error\n *\n * @example\n * ```ts\n * const result = await fetchPageV3('demo', {\n *   timeout: 5000,\n *   retries: 3,\n * });\n *\n * if (!result.ok) {\n *   switch (result.error.code) {\n *     case 'NOT_FOUND':\n *       return <NotFoundPage slug={slug} />;\n *     case 'TIMEOUT':\n *       return <TimeoutError onRetry={handleRetry} />;\n *     case 'NETWORK_ERROR':\n *       return <NetworkError message={result.error.message} />;\n *     case 'RETRY_EXHAUSTED':\n *       return <RetryExhausted attempts={result.error.retryCount} />;\n *     default:\n *       return <GenericError />;\n *   }\n * }\n *\n * return <PageRenderer page={result.value} />;\n * ```\n */\nexport async function fetchPageV3(\n  slug: string,\n  options: FetchOptions = {}\n): Promise<Result<Page, FetchError>> {\n  const {\n    timeout = DEFAULT_TIMEOUT,\n    retries = DEFAULT_RETRIES,\n    retryDelay = DEFAULT_RETRY_DELAY,\n    signal: externalSignal,\n  } = options;\n\n  // 1. Validate input\n  if (slug === null || slug === undefined) {\n    return err(\n      createFetchError(\n        FetchErrorCode.INVALID_SLUG,\n        `Slug must be a string, received ${slug === null ? 'null' : 'undefined'}`\n      )\n    );\n  }\n\n  if (typeof slug !== 'string') {\n    return err(\n      createFetchError(\n        FetchErrorCode.INVALID_SLUG,\n        `Slug must be a string, received ${typeof slug}`\n      )\n    );\n  }\n\n  const trimmedSlug = slug.trim();\n  if (trimmedSlug.length === 0) {\n    return err(createFetchError(FetchErrorCode.INVALID_SLUG, 'Slug cannot be empty'));\n  }\n\n  // 2. Create abort controller for timeout\n  const controller = new AbortController();\n  const { signal } = controller;\n\n  // Link external signal if provided\n  if (externalSignal) {\n    externalSignal.addEventListener('abort', () => controller.abort());\n  }\n\n  // 3. Set up timeout\n  const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n  // 4. Attempt fetch with retry logic\n  let lastError: Error | undefined;\n  let attempt = 0;\n\n  try {\n    while (attempt <= retries) {\n      try {\n        const page = await simulateFetch(trimmedSlug, signal);\n        clearTimeout(timeoutId);\n        return ok(page);\n      } catch (error) {\n        lastError = error instanceof Error ? error : new Error(String(error));\n\n        // Check for abort/timeout\n        if (signal.aborted) {\n          clearTimeout(timeoutId);\n          return err(\n            createFetchError(FetchErrorCode.TIMEOUT, `Request timed out after ${timeout}ms`, {\n              cause: lastError,\n            })\n          );\n        }\n\n        // Check for 404 (not retryable)\n        if (lastError.name === 'NotFoundError') {\n          clearTimeout(timeoutId);\n          return err(\n            createFetchError(FetchErrorCode.NOT_FOUND, `Page \"${trimmedSlug}\" not found`, {\n              cause: lastError,\n            })\n          );\n        }\n\n        // Check if we should retry\n        if (attempt < retries && isTransientError(lastError)) {\n          attempt++;\n          const backoff = exponentialBackoff(retryDelay, attempt);\n          if (process.env.NODE_ENV === 'development') {\n            console.warn(\n              `[fetchPageV3] Retry ${attempt}/${retries} for \"${trimmedSlug}\" after ${Math.round(backoff)}ms`\n            );\n          }\n          await delay(backoff);\n          continue;\n        }\n\n        // No more retries or non-transient error\n        break;\n      }\n    }\n\n    // 5. All retries exhausted\n    clearTimeout(timeoutId);\n\n    if (attempt >= retries) {\n      return err(\n        createFetchError(FetchErrorCode.RETRY_EXHAUSTED, `Failed after ${retries} retry attempts`, {\n          cause: lastError,\n          retryCount: attempt,\n        })\n      );\n    }\n\n    // Non-retryable error\n    return err(\n      createFetchError(\n        FetchErrorCode.NETWORK_ERROR,\n        lastError?.message ?? 'Unknown network error',\n        { cause: lastError }\n      )\n    );\n  } catch (error) {\n    clearTimeout(timeoutId);\n    const cause = error instanceof Error ? error : new Error(String(error));\n    return err(\n      createFetchError(FetchErrorCode.SERVER_ERROR, `Unexpected error: ${cause.message}`, { cause })\n    );\n  }\n}\n\n// -----------------------------------------------------------------------------\n// Default Export\n// -----------------------------------------------------------------------------\n\n/**\n * Production-ready page fetcher.\n *\n * This is an alias for `fetchPageV3` - the robust implementation\n * with validation, retry logic, and Result-based error handling.\n *\n * @example\n * ```ts\n * import { fetchPage } from '@/lib/data-utils';\n *\n * const result = await fetchPage('demo');\n * if (!result.ok) {\n *   // Handle error with full context\n *   console.error(`[${result.error.code}] ${result.error.message}`);\n *   return null;\n * }\n * return result.value;\n * ```\n */\nexport const fetchPage = fetchPageV3;\n\n// -----------------------------------------------------------------------------\n// Utility Functions\n// -----------------------------------------------------------------------------\n\n/**\n * Validates a page slug format.\n *\n * @param slug - Slug to validate\n * @returns true if slug is valid format\n */\nexport function isValidSlug(slug: string): boolean {\n  // Slugs should be lowercase, alphanumeric with hyphens\n  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug);\n}\n\n/**\n * Normalizes a slug (lowercase, trim, replace spaces with hyphens).\n *\n * @param input - Raw input to normalize\n * @returns Normalized slug\n */\nexport function normalizeSlug(input: string): string {\n  return input\n    .toLowerCase()\n    .trim()\n    .replace(/\\s+/g, '-')\n    .replace(/[^a-z0-9-]/g, '')\n    .replace(/-+/g, '-')\n    .replace(/^-|-$/g, '');\n}\n\n/**\n * Prefetches multiple pages in parallel with Result types.\n *\n * @param slugs - Array of page slugs to fetch\n * @param options - Fetch options applied to all requests\n * @returns Array of Results for each page\n *\n * @example\n * ```ts\n * const results = await prefetchPages(['home', 'about', 'blog']);\n * const errors = results.filter(r => !r.ok);\n * if (errors.length > 0) {\n *   console.warn(`${errors.length} pages failed to load`);\n * }\n * ```\n */\nexport async function prefetchPages(\n  slugs: string[],\n  options?: FetchOptions\n): Promise<Result<Page, FetchError>[]> {\n  return Promise.all(slugs.map((slug) => fetchPageV3(slug, options)));\n}\n\n/**\n * Fetches a page with stale-while-revalidate semantics.\n * Returns cached data immediately if available, then updates in background.\n *\n * @param slug - Page slug to fetch\n * @param cache - Cache storage (e.g., Map, localStorage wrapper)\n * @param options - Fetch options\n * @returns Cached data or fresh fetch result\n */\nexport async function fetchPageWithSWR(\n  slug: string,\n  cache: Map<string, { data: Page; timestamp: number }>,\n  options: FetchOptions & { maxAge?: number } = {}\n): Promise<Result<Page, FetchError>> {\n  const { maxAge = 60_000 } = options; // 1 minute default\n\n  const cached = cache.get(slug);\n  const now = Date.now();\n\n  // Return fresh cache immediately\n  if (cached && now - cached.timestamp < maxAge) {\n    return ok(cached.data);\n  }\n\n  // Fetch fresh data\n  const result = await fetchPageV3(slug, options);\n\n  // Update cache on success\n  if (result.ok) {\n    cache.set(slug, { data: result.value, timestamp: now });\n  }\n\n  // If fetch failed but we have stale cache, return it with warning\n  if (!result.ok && cached) {\n    if (process.env.NODE_ENV === 'development') {\n      console.warn(\n        `[fetchPageWithSWR] Returning stale cache for \"${slug}\" after fetch failure:`,\n        result.error.message\n      );\n    }\n    return ok(cached.data);\n  }\n\n  return result;\n}\n"],"mappings":"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","names":[]}

package/dist/lib/image/lazy-load.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Lazy Loading Utilities
+ *
+ * Reusable IntersectionObserver-based lazy loading with
+ * connection-aware quality adjustment.
+ *
+ * This module provides:
+ * - useLazyLoad: Hook for deferred loading when elements enter viewport
+ * - getConnectionAwareQuality: Adjusts image quality based on network speed
+ */
+interface LazyLoadOptions {
+    /** Root margin for early loading (default: "200px") */
+    rootMargin?: string;
+    /** Threshold for intersection (default: 0) */
+    threshold?: number;
+    /** Callback when element enters viewport */
+    onEnter?: () => void;
+}
+interface LazyLoadResult {
+    /** Callback ref to attach to the element */
+    ref: (node: HTMLElement | null) => void;
+    /** Whether the element has entered the viewport */
+    inView: boolean;
+}
+/**
+ * IntersectionObserver-based lazy loading hook.
+ *
+ * Triggers when an element approaches the viewport. Once triggered,
+ * the observer disconnects (one-shot behavior).
+ *
+ * @param options - Configuration options
+ * @returns Object with ref callback and inView state
+ *
+ * @example
+ * ```tsx
+ * function LazyComponent() {
+ *   const { ref, inView } = useLazyLoad({ rootMargin: '200px' });
+ *
+ *   return (
+ *     <div ref={ref}>
+ *       {inView && <ExpensiveContent />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useLazyLoad(options?: LazyLoadOptions): LazyLoadResult;
+/**
+ * Returns appropriate image quality based on network conditions.
+ *
+ * Uses the Network Information API when available to detect:
+ * - Data saver mode (returns lowest quality)
+ * - Effective connection type (slow-2g, 2g, 3g, 4g)
+ *
+ * Falls back to default quality (80) when:
+ * - Running on server (SSR)
+ * - Network Information API not supported
+ *
+ * @returns Quality value between 30-80
+ *
+ * @example
+ * ```typescript
+ * const quality = getConnectionAwareQuality();
+ * const imageUrl = `${baseUrl}?q=${quality}`;
+ * ```
+ */
+declare function getConnectionAwareQuality(): number;
+/**
+ * Check if the user prefers reduced data usage.
+ *
+ * @returns true if Save-Data is enabled or connection is slow
+ */
+declare function prefersReducedData(): boolean;
+
+export { type LazyLoadOptions, type LazyLoadResult, getConnectionAwareQuality, prefersReducedData, useLazyLoad };

package/dist/lib/image/lazy-load.js

@@ -0,0 +1,83 @@
+"use client";
+
+// lib/image/lazy-load.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+function useLazyLoad(options = {}) {
+  const { rootMargin = "200px", threshold = 0, onEnter } = options;
+  const [inView, setInView] = useState(false);
+  const observerRef = useRef(null);
+  const ref = useCallback(
+    (node) => {
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+        observerRef.current = null;
+      }
+      if (!node) return;
+      observerRef.current = new IntersectionObserver(
+        ([entry]) => {
+          if (entry?.isIntersecting) {
+            setInView(true);
+            onEnter?.();
+            observerRef.current?.disconnect();
+            observerRef.current = null;
+          }
+        },
+        { rootMargin, threshold }
+      );
+      observerRef.current.observe(node);
+    },
+    [rootMargin, threshold, onEnter]
+  );
+  useEffect(() => {
+    return () => {
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+        observerRef.current = null;
+      }
+    };
+  }, []);
+  return { ref, inView };
+}
+var QUALITY_PRESETS = {
+  "slow-2g": 30,
+  "2g": 50,
+  "3g": 65,
+  "4g": 80,
+  saveData: 40,
+  default: 80
+};
+function getConnectionAwareQuality() {
+  if (typeof navigator === "undefined") {
+    return QUALITY_PRESETS.default;
+  }
+  const nav = navigator;
+  const connection = nav.connection;
+  if (!connection) {
+    return QUALITY_PRESETS.default;
+  }
+  if (connection.saveData) {
+    return QUALITY_PRESETS.saveData;
+  }
+  const effectiveType = connection.effectiveType;
+  if (effectiveType && effectiveType in QUALITY_PRESETS) {
+    return QUALITY_PRESETS[effectiveType];
+  }
+  return QUALITY_PRESETS.default;
+}
+function prefersReducedData() {
+  if (typeof navigator === "undefined") {
+    return false;
+  }
+  const nav = navigator;
+  const connection = nav.connection;
+  if (!connection) {
+    return false;
+  }
+  return connection.saveData === true || connection.effectiveType === "slow-2g" || connection.effectiveType === "2g";
+}
+export {
+  getConnectionAwareQuality,
+  prefersReducedData,
+  useLazyLoad
+};
+//# sourceMappingURL=lazy-load.js.map

package/dist/lib/image/lazy-load.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../lib/image/lazy-load.ts"],"sourcesContent":["/**\n * Lazy Loading Utilities\n *\n * Reusable IntersectionObserver-based lazy loading with\n * connection-aware quality adjustment.\n *\n * This module provides:\n * - useLazyLoad: Hook for deferred loading when elements enter viewport\n * - getConnectionAwareQuality: Adjusts image quality based on network speed\n */\n\n'use client';\n\nimport { useCallback, useEffect, useRef, useState } from 'react';\n\n// =============================================================================\n// Types\n// =============================================================================\n\nexport interface LazyLoadOptions {\n  /** Root margin for early loading (default: \"200px\") */\n  rootMargin?: string;\n  /** Threshold for intersection (default: 0) */\n  threshold?: number;\n  /** Callback when element enters viewport */\n  onEnter?: () => void;\n}\n\nexport interface LazyLoadResult {\n  /** Callback ref to attach to the element */\n  ref: (node: HTMLElement | null) => void;\n  /** Whether the element has entered the viewport */\n  inView: boolean;\n}\n\n// =============================================================================\n// useLazyLoad Hook\n// =============================================================================\n\n/**\n * IntersectionObserver-based lazy loading hook.\n *\n * Triggers when an element approaches the viewport. Once triggered,\n * the observer disconnects (one-shot behavior).\n *\n * @param options - Configuration options\n * @returns Object with ref callback and inView state\n *\n * @example\n * ```tsx\n * function LazyComponent() {\n *   const { ref, inView } = useLazyLoad({ rootMargin: '200px' });\n *\n *   return (\n *     <div ref={ref}>\n *       {inView && <ExpensiveContent />}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useLazyLoad(options: LazyLoadOptions = {}): LazyLoadResult {\n  const { rootMargin = '200px', threshold = 0, onEnter } = options;\n  const [inView, setInView] = useState(false);\n  const observerRef = useRef<IntersectionObserver | null>(null);\n\n  const ref = useCallback(\n    (node: HTMLElement | null) => {\n      // Disconnect previous observer\n      if (observerRef.current) {\n        observerRef.current.disconnect();\n        observerRef.current = null;\n      }\n\n      // No node to observe\n      if (!node) return;\n\n      // Create new observer\n      observerRef.current = new IntersectionObserver(\n        ([entry]) => {\n          if (entry?.isIntersecting) {\n            setInView(true);\n            onEnter?.();\n            // Disconnect after first intersection (one-shot)\n            observerRef.current?.disconnect();\n            observerRef.current = null;\n          }\n        },\n        { rootMargin, threshold }\n      );\n\n      observerRef.current.observe(node);\n    },\n    [rootMargin, threshold, onEnter]\n  );\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      if (observerRef.current) {\n        observerRef.current.disconnect();\n        observerRef.current = null;\n      }\n    };\n  }, []);\n\n  return { ref, inView };\n}\n\n// =============================================================================\n// Connection-Aware Quality\n// =============================================================================\n\n/**\n * Network Information API types (not in standard TypeScript lib).\n * @see https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API\n */\ninterface NetworkInformation {\n  effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';\n  downlink?: number;\n  saveData?: boolean;\n}\n\ninterface NavigatorWithConnection extends Navigator {\n  connection?: NetworkInformation;\n}\n\n/**\n * Quality presets based on connection type.\n */\nconst QUALITY_PRESETS = {\n  'slow-2g': 30,\n  '2g': 50,\n  '3g': 65,\n  '4g': 80,\n  saveData: 40,\n  default: 80,\n} as const;\n\n/**\n * Returns appropriate image quality based on network conditions.\n *\n * Uses the Network Information API when available to detect:\n * - Data saver mode (returns lowest quality)\n * - Effective connection type (slow-2g, 2g, 3g, 4g)\n *\n * Falls back to default quality (80) when:\n * - Running on server (SSR)\n * - Network Information API not supported\n *\n * @returns Quality value between 30-80\n *\n * @example\n * ```typescript\n * const quality = getConnectionAwareQuality();\n * const imageUrl = `${baseUrl}?q=${quality}`;\n * ```\n */\nexport function getConnectionAwareQuality(): number {\n  // SSR fallback\n  if (typeof navigator === 'undefined') {\n    return QUALITY_PRESETS.default;\n  }\n\n  const nav = navigator as NavigatorWithConnection;\n  const connection = nav.connection;\n\n  // No Network Information API support\n  if (!connection) {\n    return QUALITY_PRESETS.default;\n  }\n\n  // User has enabled data saver - respect their preference\n  if (connection.saveData) {\n    return QUALITY_PRESETS.saveData;\n  }\n\n  // Adjust based on effective connection type\n  const effectiveType = connection.effectiveType;\n  if (effectiveType && effectiveType in QUALITY_PRESETS) {\n    return QUALITY_PRESETS[effectiveType];\n  }\n\n  return QUALITY_PRESETS.default;\n}\n\n/**\n * Check if the user prefers reduced data usage.\n *\n * @returns true if Save-Data is enabled or connection is slow\n */\nexport function prefersReducedData(): boolean {\n  if (typeof navigator === 'undefined') {\n    return false;\n  }\n\n  const nav = navigator as NavigatorWithConnection;\n  const connection = nav.connection;\n\n  if (!connection) {\n    return false;\n  }\n\n  return (\n    connection.saveData === true ||\n    connection.effectiveType === 'slow-2g' ||\n    connection.effectiveType === '2g'\n  );\n}\n"],"mappings":";;;AAaA,SAAS,aAAa,WAAW,QAAQ,gBAAgB;AAgDlD,SAAS,YAAY,UAA2B,CAAC,GAAmB;AACzE,QAAM,EAAE,aAAa,SAAS,YAAY,GAAG,QAAQ,IAAI;AACzD,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAS,KAAK;AAC1C,QAAM,cAAc,OAAoC,IAAI;AAE5D,QAAM,MAAM;AAAA,IACV,CAAC,SAA6B;AAE5B,UAAI,YAAY,SAAS;AACvB,oBAAY,QAAQ,WAAW;AAC/B,oBAAY,UAAU;AAAA,MACxB;AAGA,UAAI,CAAC,KAAM;AAGX,kBAAY,UAAU,IAAI;AAAA,QACxB,CAAC,CAAC,KAAK,MAAM;AACX,cAAI,OAAO,gBAAgB;AACzB,sBAAU,IAAI;AACd,sBAAU;AAEV,wBAAY,SAAS,WAAW;AAChC,wBAAY,UAAU;AAAA,UACxB;AAAA,QACF;AAAA,QACA,EAAE,YAAY,UAAU;AAAA,MAC1B;AAEA,kBAAY,QAAQ,QAAQ,IAAI;AAAA,IAClC;AAAA,IACA,CAAC,YAAY,WAAW,OAAO;AAAA,EACjC;AAGA,YAAU,MAAM;AACd,WAAO,MAAM;AACX,UAAI,YAAY,SAAS;AACvB,oBAAY,QAAQ,WAAW;AAC/B,oBAAY,UAAU;AAAA,MACxB;AAAA,IACF;AAAA,EACF,GAAG,CAAC,CAAC;AAEL,SAAO,EAAE,KAAK,OAAO;AACvB;AAuBA,IAAM,kBAAkB;AAAA,EACtB,WAAW;AAAA,EACX,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,UAAU;AAAA,EACV,SAAS;AACX;AAqBO,SAAS,4BAAoC;AAElD,MAAI,OAAO,cAAc,aAAa;AACpC,WAAO,gBAAgB;AAAA,EACzB;AAEA,QAAM,MAAM;AACZ,QAAM,aAAa,IAAI;AAGvB,MAAI,CAAC,YAAY;AACf,WAAO,gBAAgB;AAAA,EACzB;AAGA,MAAI,WAAW,UAAU;AACvB,WAAO,gBAAgB;AAAA,EACzB;AAGA,QAAM,gBAAgB,WAAW;AACjC,MAAI,iBAAiB,iBAAiB,iBAAiB;AACrD,WAAO,gBAAgB,aAAa;AAAA,EACtC;AAEA,SAAO,gBAAgB;AACzB;AAOO,SAAS,qBAA8B;AAC5C,MAAI,OAAO,cAAc,aAAa;AACpC,WAAO;AAAA,EACT;AAEA,QAAM,MAAM;AACZ,QAAM,aAAa,IAAI;AAEvB,MAAI,CAAC,YAAY;AACf,WAAO;AAAA,EACT;AAEA,SACE,WAAW,aAAa,QACxB,WAAW,kBAAkB,aAC7B,WAAW,kBAAkB;AAEjC;","names":[]}

package/dist/lib/markdown-utils.d.ts

@@ -0,0 +1,172 @@
+import { MDTree } from 'md4w';
+import { Result } from './result.js';
+
+/**
+ * Markdown Parsing Utilities
+ *
+ * Three implementations showing the progression from naive to production-ready:
+ * - v1 (Naive): Direct call, crashes on bad input
+ * - v2 (Defensive): Try-catch with null fallback
+ * - v3 (Robust): Result type, validation, sanitization
+ *
+ * The robust version (v3) is exported as the default `parseMarkdown`.
+ */
+
+/**
+ * Error codes for markdown parsing failures.
+ */
+declare const ParseErrorCode: {
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly EMPTY_CONTENT: "EMPTY_CONTENT";
+    readonly PARSE_FAILED: "PARSE_FAILED";
+    readonly CONTENT_TOO_LONG: "CONTENT_TOO_LONG";
+    readonly NESTED_TOO_DEEP: "NESTED_TOO_DEEP";
+};
+type ParseErrorCode = (typeof ParseErrorCode)[keyof typeof ParseErrorCode];
+/**
+ * Structured error for markdown parsing failures.
+ */
+interface ParseError {
+    code: ParseErrorCode;
+    message: string;
+    cause?: Error;
+}
+/**
+ * Options for robust markdown parsing.
+ */
+interface ParseOptions {
+    /**
+     * Maximum content length in characters.
+     * @default 500000 (500KB of text, ~100K words)
+     */
+    maxLength?: number;
+    /**
+     * Whether to sanitize XSS attempts in the output.
+     * @default true
+     */
+    sanitize?: boolean;
+    /**
+     * Whether to allow empty content.
+     * @default false
+     */
+    allowEmpty?: boolean;
+}
+/**
+ * Naive markdown parser - crashes on bad input.
+ *
+ * DO NOT USE IN PRODUCTION. This is for demonstration only.
+ *
+ * Problems:
+ * - No input validation
+ * - No error handling
+ * - Will crash the entire app on malformed input
+ * - No protection against XSS
+ * - No content limits
+ *
+ * @example
+ * ```ts
+ * // This crashes if content is null, undefined, or malformed
+ * const ast = parseMarkdownV1(userInput);
+ * ```
+ */
+declare function parseMarkdownV1(content: string): MDTree;
+/**
+ * Defensive markdown parser - catches errors but loses context.
+ *
+ * Better than v1 but still problematic:
+ * - Returns null on any error (loses error details)
+ * - Caller can't distinguish between empty content and parse failure
+ * - Still no XSS protection
+ * - Still no content limits
+ *
+ * @example
+ * ```ts
+ * const ast = parseMarkdownV2(userInput);
+ * if (!ast) {
+ *   // What went wrong? We don't know.
+ *   return <ErrorFallback />;
+ * }
+ * ```
+ */
+declare function parseMarkdownV2(content: string): MDTree | null;
+/**
+ * Robust markdown parser - production-ready with full error context.
+ *
+ * Features:
+ * - Input validation with specific error codes
+ * - Result type for explicit error handling
+ * - XSS pattern detection and optional sanitization
+ * - Content length limits
+ * - Preserves error context for debugging
+ *
+ * @param content - Markdown string to parse
+ * @param options - Parsing options
+ * @returns Result containing the AST or a structured error
+ *
+ * @example
+ * ```ts
+ * const result = parseMarkdownV3(userInput);
+ *
+ * if (!result.ok) {
+ *   switch (result.error.code) {
+ *     case 'INVALID_INPUT':
+ *       return <InvalidInputError message={result.error.message} />;
+ *     case 'CONTENT_TOO_LONG':
+ *       return <ContentTooLongError />;
+ *     case 'PARSE_FAILED':
+ *       console.error('Parse error:', result.error.cause);
+ *       return <ParseError />;
+ *     default:
+ *       return <GenericError />;
+ *   }
+ * }
+ *
+ * return <MarkdownRenderer ast={result.value} />;
+ * ```
+ */
+declare function parseMarkdownV3(content: string, options?: ParseOptions): Result<MDTree, ParseError>;
+/**
+ * Production-ready markdown parser.
+ *
+ * This is an alias for `parseMarkdownV3` - the robust implementation
+ * with validation, sanitization, and Result-based error handling.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown } from '@/lib/markdown-utils';
+ *
+ * const result = parseMarkdown(content);
+ * if (!result.ok) {
+ *   // Handle error with full context
+ *   console.error(`[${result.error.code}] ${result.error.message}`);
+ *   return null;
+ * }
+ * return result.value;
+ * ```
+ */
+declare const parseMarkdown: typeof parseMarkdownV3;
+/**
+ * Checks if content is safe markdown (no XSS patterns detected).
+ *
+ * @param content - Markdown string to check
+ * @returns true if no XSS patterns detected
+ */
+declare function isSafeMarkdown(content: string): boolean;
+/**
+ * Estimates the word count of markdown content.
+ * Useful for content length limits and reading time estimates.
+ *
+ * @param content - Markdown string to count
+ * @returns Estimated word count
+ */
+declare function estimateWordCount(content: string): number;
+/**
+ * Estimates reading time for markdown content.
+ *
+ * @param content - Markdown string
+ * @param wordsPerMinute - Reading speed (default 200 WPM)
+ * @returns Reading time in minutes
+ */
+declare function estimateReadingTime(content: string, wordsPerMinute?: number): number;
+
+export { type ParseError, ParseErrorCode, type ParseOptions, estimateReadingTime, estimateWordCount, isSafeMarkdown, parseMarkdown, parseMarkdownV1, parseMarkdownV2, parseMarkdownV3 };