@fullstackdatasolutions/articles 0.11.0 → 1.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ComponentType } from 'react';
+import { ComponentType, ReactNode } from 'react';
 
 interface TocItem {
     id: string;
@@ -22,9 +22,12 @@ interface Article {
     lastmod?: string;
     author: string;
     authors?: string[];
+    authorSlug?: string;
+    authorAvatar?: string;
     category: string;
     categories: string[];
     readTime: string;
+    wordCount?: number;
     featuredImage: string;
     tags?: string[];
     content?: string;
@@ -38,7 +41,65 @@ interface Article {
     canonicalUrl?: string;
     articleType?: string;
     series?: string;
+    /**
+     * Machine-safe series identifier (Phase 27F) - separate from the
+     * label-only `series` string, which stays supported unchanged for
+     * consumers who only set it. `seriesSlug`/`seriesOrder` turn `series` into
+     * a navigable reader journey via `getArticlesBySeries`/
+     * `getAdjacentArticlesInSeries`. Both optional; omitted on every article
+     * reproduces pre-27F behavior exactly.
+     */
+    seriesSlug?: string;
+    /** Position within `seriesSlug`, ascending. Ties/omissions fall back to date order (see `getArticlesBySeries`). */
+    seriesOrder?: number;
     aiCrawl?: boolean;
+    /**
+     * Discovery metadata overrides (Phase 27F), all optional and additive.
+     * `searchTitle`/`searchDescription` feed `generateArticleMetadata`'s
+     * `<title>`/meta description ONLY - canonical URLs, JSON-LD, RSS, and
+     * `ArticleCard` keep reading `title`/`excerpt` unchanged. `socialTitle`/
+     * `socialDescription`/`socialImage` feed Open Graph/Twitter Card output
+     * ONLY, falling back to `title`/`excerpt`/`featuredImage`. See
+     * `resolveSearchMetadata`/`resolveSocialMetadata` in `seoUtils.ts` for the
+     * exact fallback/sanitization rules.
+     */
+    searchTitle?: string;
+    searchDescription?: string;
+    socialTitle?: string;
+    socialDescription?: string;
+    socialImage?: string;
+    /**
+     * References an app-owned CTA/offer by opaque ID (Phase 27F). The package
+     * never interprets `actionId` - it doesn't know about forms, email
+     * providers, or analytics vendors. The consuming app looks `actionId` up
+     * in its own registry when rendering a detail-page slot (see
+     * `ArticleContent`'s `afterHero`/`afterIntro`/`midContent`/`afterContent`
+     * props); an unmatched ID must render nothing, never throw.
+     */
+    primaryAction?: {
+        actionId: string;
+    };
+}
+/**
+ * A "start here" curated reader journey that can cross series/categories -
+ * a distinct primitive from the label-only `series` field/`seriesSlug`
+ * pair (Phase 27F). Configured via `ArticlesConfig.paths`, keyed by an
+ * app-chosen path key. `articles` is an ordered list of slugs; every
+ * referenced slug must exist and not be `draft: true` - enforced by
+ * `validateArticles`, not silently at render time.
+ */
+interface PathDefinition {
+    /** Display name, e.g. "New GM Starter Path". */
+    name: string;
+    /** One-sentence value proposition shown on the path's landing/step UI. */
+    promise: string;
+    /** Ordered article slugs making up the journey. */
+    articles: string[];
+    /** The one next action offered once a reader completes the path. */
+    nextAction: {
+        label: string;
+        href: string;
+    };
 }
 interface CategoryInfo {
     name: string;
@@ -63,6 +124,23 @@ interface AuthorSocial {
     newsletter?: string;
     other?: Record<string, string>;
 }
+/**
+ * One headed block of structured long-form content (used by
+ * `AuthorProfile.originStory`). An array of these, not a single HTML blob,
+ * so consuming apps can render/style each block themselves rather than
+ * `dangerouslySetInnerHTML`-ing raw markup.
+ */
+interface RichTextSection {
+    heading?: string;
+    paragraphs: string[];
+}
+type RichText = RichTextSection[];
+/** A single sourceable claim used by `AuthorProfile.proof`. */
+interface ProofItem {
+    claim: string;
+    source?: string;
+    url?: string;
+}
 interface AuthorProfile {
     name: string;
     slug: string;
@@ -70,12 +148,81 @@ interface AuthorProfile {
     avatar?: string;
     url?: string;
     social?: AuthorSocial;
+    /** Short one-line audience promise, e.g. "Helping new GMs run confident first sessions." Optional, additive - omitted fields never change existing rendering. */
+    promise?: string;
+    /** Structured long-form origin story - see `RichText`/`RichTextSection`. */
+    originStory?: RichText;
+    /** Who this author's content/work is for, e.g. "New game masters", "Streaming DMs". */
+    servesWho?: string[];
+    /** Core beliefs/approach statements. */
+    principles?: string[];
+    /**
+     * Experience/credential claims (e.g. "10+ years running published campaigns").
+     * Intentionally never included in Person JSON-LD - unverifiable claims don't
+     * belong in structured data (see `getPersonSchema`/`getPersonSchemas`).
+     */
+    credentials?: string[];
+    /** Concrete, sourceable proof points. */
+    proof?: ProofItem[];
+    /** Primary call-to-action rendered on the author's page. */
+    primaryCta?: {
+        label: string;
+        href: string;
+    };
 }
 interface BreadcrumbItem {
     name: string;
     url?: string;
 }
 
+type ArticleEventName = 'article_viewed' | 'meaningful_read' | 'author_clicked' | 'cta_viewed' | 'cta_clicked' | 'shared' | 'related_article_clicked' | 'path_step_advanced';
+interface ArticleEventBase<Name extends ArticleEventName> {
+    name: Name;
+    /** `Date.now()` at emit time. */
+    timestamp: number;
+}
+interface ArticleViewedEvent extends ArticleEventBase<'article_viewed'> {
+    articleSlug: string;
+    category?: string;
+    seriesSlug?: string;
+}
+/** Fired once per view after the reader has spent roughly half the article's estimated read time on the page (see `ArticleViewTracker`). */
+interface MeaningfulReadEvent extends ArticleEventBase<'meaningful_read'> {
+    articleSlug: string;
+}
+interface AuthorClickedEvent extends ArticleEventBase<'author_clicked'> {
+    articleSlug: string;
+    authorSlug: string;
+}
+/** `ctaId` is `primaryAction.actionId`, an `AuthorProfile.primaryCta` slug, or a `PathDefinition` key - always an app-chosen ID, never label text. */
+interface CtaViewedEvent extends ArticleEventBase<'cta_viewed'> {
+    ctaId: string;
+    articleSlug?: string;
+}
+interface CtaClickedEvent extends ArticleEventBase<'cta_clicked'> {
+    ctaId: string;
+    articleSlug?: string;
+}
+interface SharedEvent extends ArticleEventBase<'shared'> {
+    articleSlug: string;
+    /** Share channel key, e.g. `'linkedin'`, `'copy-link'` - never the shared URL/message text. */
+    channel: string;
+}
+interface RelatedArticleClickedEvent extends ArticleEventBase<'related_article_clicked'> {
+    fromSlug: string;
+    toSlug: string;
+    source: 'path' | 'series' | 'category';
+}
+interface PathStepAdvancedEvent extends ArticleEventBase<'path_step_advanced'> {
+    pathKey: string;
+    fromSlug: string;
+    toSlug: string;
+    direction: 'previous' | 'next';
+}
+type ArticleEvent = ArticleViewedEvent | MeaningfulReadEvent | AuthorClickedEvent | CtaViewedEvent | CtaClickedEvent | SharedEvent | RelatedArticleClickedEvent | PathStepAdvancedEvent;
+/** Register this on `ArticlesConfig.onEvent` to receive every emitted event and translate it to your own analytics stack. */
+type ArticleEventHandler = (event: ArticleEvent) => void;
+
 /** Keys for each renderable section of the articles listing page. */
 type ArticlesSection = 'hero' | 'search' | 'featured' | 'latest' | 'categories' | 'newsletter';
 /**
@@ -136,6 +283,18 @@ interface HeroConfig {
 }
 /** Controls how article body links set target/rel attributes. */
 type LinkTargetStrategy = 'external-new-tab' | 'all-new-tab' | 'same-tab';
+/**
+ * Controls how listing pages (the articles index, category pages, author
+ * pages) surface articles beyond the first `pageSize`.
+ * - `'load-more'` (default): client-only "Load more" button, no URL change.
+ *   Byte-for-byte identical to pre-27D behavior.
+ * - `'pages'`: real, directly-navigable paginated routes (`/articles/page/2`,
+ *   `/articles/category/[category]/page/2`, `/articles/authors/[author]/page/2`)
+ *   with SSR content, prev/next links, and per-page canonical metadata. The
+ *   route *files* live in the consuming app - see the pagination primitives
+ *   exported from `./server` and the `PaginationNav` component.
+ */
+type ListingPagination = 'load-more' | 'pages';
 /** React components that article MDX bodies can reference by JSX tag name. */
 type MdxComponents = Record<string, ComponentType<never>>;
 type ArticleBreadcrumbToken = 'home' | 'articles' | 'primaryCategory' | 'folderPath' | 'articleTitle';
@@ -218,6 +377,28 @@ interface ArticlesConfig {
     linkTargetStrategy?: LinkTargetStrategy;
     /** Extra components exposed to article MDX bodies by JSX tag name. */
     mdxComponents?: MdxComponents;
+    /**
+     * Chooses how listing pages surface articles beyond the first `pageSize`.
+     * Default: `'load-more'` (unchanged pre-27D behavior). Set to `'pages'` to
+     * opt into real, crawlable paginated routes instead.
+     */
+    listingPagination?: ListingPagination;
+    /**
+     * "Start here" curated reader journeys, keyed by an app-chosen path key.
+     * Distinct from the label-only `series` field/`seriesSlug` pair - a path
+     * can cross series and categories. Every `PathDefinition.articles` slug
+     * must exist and not be `draft: true`; validate with `validateArticles`
+     * before publishing, since a broken reference produces a dead journey
+     * step rather than a build-time failure otherwise.
+     */
+    paths?: Record<string, PathDefinition>;
+    /**
+     * Vendor-neutral event callback (Phase 27F). Fired by components/hooks at
+     * meaningful reader-journey moments (see `ArticleEvent` in `events.ts`).
+     * No PII in any payload. The package never talks to an analytics/email
+     * vendor directly - translate events to PostHog/etc. in this callback.
+     */
+    onEvent?: ArticleEventHandler;
 }
 declare const DEFAULT_PAGE_SIZE = 6;
 declare const DEFAULT_CATEGORIES_PAGE_SIZE = 8;
@@ -225,14 +406,34 @@ declare const DEFAULT_LAYOUT: ArticlesSection[];
 declare function breadcrumbsAreEnabled(config: ArticlesConfig): boolean;
 declare function getBreadcrumbsConfig(config: ArticlesConfig): BreadcrumbsConfig;
 
-declare function ArticlesPage({ config }: Readonly<{
+declare function ArticlesPage({ config, initialArticles, initialCategories, page, totalPages, totalCount, }: Readonly<{
     config: ArticlesConfig;
+    initialArticles?: Article[];
+    initialCategories?: CategoryInfo[];
+    /**
+     * Current page number in `listingPagination: 'pages'` mode. Ignored
+     * (along with `totalPages`/`totalCount`) unless `config.listingPagination
+     * === 'pages'` - the default `'load-more'` behavior never reads these.
+     * `initialArticles` should already be this page's slice (see
+     * `paginateArticles` from `./server`).
+     */
+    page?: number;
+    /** Total page count in `'pages'` mode, from `getTotalPages`. */
+    totalPages?: number;
+    /**
+     * True total article count across every page (not just `initialArticles`'
+     * length) - used for `CollectionPageSchema.articleCount`. Defaults to
+     * `state.articles.length`, matching prior behavior when omitted.
+     */
+    totalCount?: number;
 }>): react_jsx_runtime.JSX.Element;
 
 type ArticleCardProps = Readonly<{
     article: Article;
+    /** Optional (Phase 27F) - when passed with `config.onEvent`, clicking the author link fires an `author_clicked` event. Omitting it changes nothing. */
+    config?: ArticlesConfig;
 }>;
-declare function ArticleCard({ article }: ArticleCardProps): react_jsx_runtime.JSX.Element;
+declare function ArticleCard({ article, config }: ArticleCardProps): react_jsx_runtime.JSX.Element;
 
 type ArticleCategoryGridProps = Readonly<{
     categories: CategoryInfo[];
@@ -269,33 +470,107 @@ type FeaturedArticleProps = Readonly<{
 }>;
 declare function FeaturedArticle({ article, showAuthor }: FeaturedArticleProps): react_jsx_runtime.JSX.Element;
 
+/** Context threaded from a listing page component down into `LatestArticles`/`PaginationNav` in `'pages'` mode. */
+interface ListingPaginationContext {
+    page: number;
+    totalPages: number;
+    /** Un-paginated route path for this listing, e.g. `/articles` or `/articles/category/campaigns`. */
+    basePath: string;
+}
+
 interface LatestArticlesProps {
     readonly articles: Article[];
     readonly pageSize: number;
+    /**
+     * Switches from the default client-only "Load more" button to real
+     * paginated routes: renders every article in `articles` as-is (the caller
+     * has already sliced to the current page, e.g. via `paginateArticles`) and
+     * a `PaginationNav` instead of the button. Omit to keep the existing
+     * `listingPagination: 'load-more'` behavior, unchanged.
+     */
+    readonly pagination?: ListingPaginationContext;
 }
-declare function LatestArticles({ articles, pageSize }: Readonly<LatestArticlesProps>): react_jsx_runtime.JSX.Element;
+declare function LatestArticles({ articles, pageSize, pagination }: Readonly<LatestArticlesProps>): react_jsx_runtime.JSX.Element;
 
 interface LatestArticlesSectionProps {
     readonly articles: Article[];
     readonly searchQuery: string;
     readonly onClearSearch: () => void;
     readonly pageSize?: number;
+    /**
+     * `'pages'` mode pagination context. Ignored while `searchQuery` is set -
+     * search results stay unpaginated/client-only in both `listingPagination`
+     * modes (search URLs aren't meant to be indexed, so real pagination adds
+     * no SEO value there).
+     */
+    readonly pagination?: ListingPaginationContext;
 }
-declare function LatestArticlesSection({ articles, searchQuery, onClearSearch, pageSize, }: Readonly<LatestArticlesSectionProps>): react_jsx_runtime.JSX.Element;
+declare function LatestArticlesSection({ articles, searchQuery, onClearSearch, pageSize, pagination, }: Readonly<LatestArticlesSectionProps>): react_jsx_runtime.JSX.Element;
 
 type CategoryArticlesPageProps = Readonly<{
     category: string;
     articles: Article[];
     config: ArticlesConfig;
+    /** Current page number in `listingPagination: 'pages'` mode. Ignored (with `totalPages`/`totalCount`) unless `config.listingPagination === 'pages'`. `articles` should already be this page's slice. */
+    page?: number;
+    /** Total page count in `'pages'` mode, from `getTotalPages`. */
+    totalPages?: number;
+    /** True total article count across every page. Defaults to `articles.length`. */
+    totalCount?: number;
 }>;
-declare function CategoryArticlesPage({ category, articles, config }: CategoryArticlesPageProps): react_jsx_runtime.JSX.Element | null;
+declare function CategoryArticlesPage({ category, articles, config, page, totalPages, totalCount, }: CategoryArticlesPageProps): react_jsx_runtime.JSX.Element | null;
+
+type SeriesArticlesPageProps = Readonly<{
+    /** Machine-safe series identifier - matches `Article.seriesSlug`. */
+    seriesSlug: string;
+    /** Already resolved via `getArticlesBySeries` (seriesOrder-sorted). */
+    articles: Article[];
+    config: ArticlesConfig;
+}>;
+/**
+ * Lightweight series landing page (Phase 27F) - a thinner sibling of
+ * `CategoryArticlesPage` for a `seriesSlug`'s ordered reader journey rather
+ * than a category's chronological listing. Displays series position badges
+ * (1-indexed, following `getArticlesBySeries`' order) so a reader can see
+ * where in the journey each article sits; doesn't attempt real ('pages'
+ * mode) pagination - series are expected to be short, curated lists rather
+ * than open-ended listings, so `LatestArticles` is used purely for its
+ * card grid, sized to show every article without a "Load more" step.
+ */
+declare function SeriesArticlesPage({ seriesSlug, articles, config }: SeriesArticlesPageProps): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Ordered section keys for the composable author-page render API (Phase
+ * 27E). `'custom'` is the one consumer-supplied slot - pass its content via
+ * the `customSection` prop. Passing `sections` is fully opt-in: omitting it
+ * keeps `AuthorArticlesPage`'s original output (Person/CollectionPage JSON-LD
+ * + article list only, no hero) byte-for-byte unchanged.
+ */
+type AuthorPageSection = 'hero' | 'promise' | 'servesWho' | 'originStory' | 'principles' | 'proof' | 'cta' | 'articles' | 'custom';
 type AuthorArticlesPageProps = Readonly<{
     author: AuthorProfile;
     articles: Article[];
     config: ArticlesConfig;
+    /** Current page number in `listingPagination: 'pages'` mode. Ignored (with `totalPages`/`totalCount`) unless `config.listingPagination === 'pages'`. `articles` should already be this page's slice. */
+    page?: number;
+    /** Total page count in `'pages'` mode, from `getTotalPages`. */
+    totalPages?: number;
+    /** True total article count across every page. Defaults to `articles.length` (also used as the `Person` schema's `interactionStatistic` count). */
+    totalCount?: number;
+    /**
+     * Ordered list of sections to render (Phase 27E composable render API).
+     * When omitted, `AuthorArticlesPage` renders exactly as it did before this
+     * prop existed - the article list only, no hero and no rich-profile
+     * sections, even if `author` has the new optional fields populated.
+     * Include `'hero'` to render `AuthorDetailHero` here instead of composing
+     * it separately; each other section renders nothing when its backing
+     * field (`author.promise`, `author.servesWho`, etc.) is unset.
+     */
+    sections?: AuthorPageSection[];
+    /** Content for the one `'custom'` slot in `sections`. Ignored unless `sections` includes `'custom'`. */
+    customSection?: ReactNode;
 }>;
-declare function AuthorArticlesPage({ author, articles, config }: AuthorArticlesPageProps): react_jsx_runtime.JSX.Element;
+declare function AuthorArticlesPage({ author, articles, config, page, totalPages, totalCount, sections, customSection, }: AuthorArticlesPageProps): react_jsx_runtime.JSX.Element;
 
 type AuthorCardProps = Readonly<{
     author: AuthorProfile;
@@ -325,14 +600,6 @@ declare function BreadcrumbSchema({ items }: Readonly<{
     items: BreadcrumbItem[];
 }>): react_jsx_runtime.JSX.Element;
 
-type ArticleSchemaProps = Readonly<{
-    article: Article;
-    articleUrl: string;
-    siteName: string;
-    showAuthor?: boolean;
-    authors?: AuthorProfile[];
-}>;
-declare function ArticleSchema({ article, articleUrl, siteName, showAuthor, authors, }: ArticleSchemaProps): react_jsx_runtime.JSX.Element;
 type ArticleSEOProps = Readonly<{
     article: Article;
     articleUrl: string;
@@ -340,8 +607,9 @@ type ArticleSEOProps = Readonly<{
     siteLogo?: string;
     showAuthor?: boolean;
     authors?: AuthorProfile[];
+    config?: ArticlesConfig;
 }>;
-declare function ArticleSEO({ article, articleUrl, siteName, siteLogo, showAuthor, authors, }: ArticleSEOProps): react_jsx_runtime.JSX.Element;
+declare function ArticleSEO({ article, articleUrl, siteName, siteLogo, showAuthor, authors, config, }: ArticleSEOProps): react_jsx_runtime.JSX.Element;
 type FAQPageSchemaProps = Readonly<{
     items: ReadonlyArray<{
         question: string;
@@ -349,21 +617,31 @@ type FAQPageSchemaProps = Readonly<{
     }>;
 }>;
 declare function FAQPageSchema({ items }: FAQPageSchemaProps): react_jsx_runtime.JSX.Element;
+type CollectionPageItem = Readonly<{
+    position: number;
+    url: string;
+    name: string;
+}>;
 type CollectionPageSchemaProps = Readonly<{
     title: string;
     description: string;
     url: string;
     articleCount: number;
+    items?: CollectionPageItem[];
 }>;
-declare function CollectionPageSchema({ title, description, url, articleCount, }: CollectionPageSchemaProps): react_jsx_runtime.JSX.Element;
+declare function CollectionPageSchema({ title, description, url, articleCount, items, }: CollectionPageSchemaProps): react_jsx_runtime.JSX.Element;
 
 interface ArticleSocialShareProps {
     readonly title: string;
     readonly url: string;
     readonly excerpt?: string;
     readonly shareMessage?: string;
+    /** Optional (Phase 27F). Enables `shared` events - requires `articleSlug` too. */
+    readonly config?: ArticlesConfig;
+    /** The article slug being shared. Required to emit `shared`. */
+    readonly articleSlug?: string;
 }
-declare function ArticleSocialShare({ title, url, excerpt, shareMessage }: ArticleSocialShareProps): react_jsx_runtime.JSX.Element;
+declare function ArticleSocialShare({ title, url, excerpt, shareMessage, config, articleSlug, }: ArticleSocialShareProps): react_jsx_runtime.JSX.Element;
 
 interface ArticleNavigationProps {
     readonly previous: {
@@ -375,8 +653,33 @@ interface ArticleNavigationProps {
         title: string;
     } | null;
     readonly basePath: string;
+    /** The article slug this navigation is shown on. Combined with `pathKey`, enables `path_step_advanced` events. */
+    readonly fromSlug?: string;
+    /**
+     * Set when this navigation walks a configured `Path` (as opposed to plain
+     * chronological/series adjacency) - fires `path_step_advanced` on click.
+     * Omit for ordinary previous/next navigation; no event fires without it.
+     */
+    readonly pathKey?: string;
+    readonly config?: ArticlesConfig;
 }
-declare function ArticleNavigation({ previous, next, basePath }: ArticleNavigationProps): react_jsx_runtime.JSX.Element | null;
+declare function ArticleNavigation({ previous, next, basePath, fromSlug, pathKey, config, }: ArticleNavigationProps): react_jsx_runtime.JSX.Element | null;
+
+type RelatedContentSource = 'path' | 'series' | 'category';
+
+type RelatedArticlesSectionProps = Readonly<{
+    articles: Article[];
+    category: string;
+    /** Overrides the default "More in {category}" heading - used by `getRelatedContent` callers when `source` is `'path'`/`'series'`. Omit to keep the default category-based heading. */
+    heading?: string;
+    /** Optional (Phase 27F). Enables `related_article_clicked` events - requires `fromSlug` too. */
+    config?: ArticlesConfig;
+    /** The article slug this related section is shown on. Required to emit `related_article_clicked`. */
+    fromSlug?: string;
+    /** Selection source that produced `articles`, from `getRelatedContent`. Defaults to `'category'`. */
+    source?: RelatedContentSource;
+}>;
+declare function RelatedArticlesSection({ articles, category, heading, config, fromSlug, source, }: RelatedArticlesSectionProps): react_jsx_runtime.JSX.Element | null;
 
 type ArticleBackLinkProps = Readonly<{
     config: Pick<ArticlesConfig, 'showBackToArticles'>;
@@ -394,6 +697,57 @@ declare function ArticleTOC({ toc, className }: ArticleTOCProps): react_jsx_runt
 
 declare function ScrollToTop(): react_jsx_runtime.JSX.Element | null;
 
+interface PaginationNavProps {
+    readonly basePath: string;
+    readonly page: number;
+    readonly totalPages: number;
+}
+/**
+ * Renders real `<a href>` prev/next links between listing pages (used only
+ * in `listingPagination: 'pages'` mode), plus `<link rel="prev"/"next">`
+ * tags for crawlers/tools that still read them.
+ *
+ * Google stopped using rel=next/prev as an indexing signal in 2019 (Google
+ * Search Central's pagination guidance now recommends a unique
+ * self-referencing canonical per page - see `generateArticlesIndexPageMetadata`
+ * et al in seoUtils.ts - plus real crawlable links between pages, which is
+ * what this component's visible Previous/Next links provide). rel=next/prev
+ * remains valid HTML and is still read by Bing and some third-party tools,
+ * so it's emitted here for free: React 19 hoists `<link>`/`<meta>` elements
+ * rendered anywhere in a Server Component tree into `<head>` automatically
+ * (not just from layout.js/page.js directly), so no separate Head API call
+ * is needed.
+ */
+declare function PaginationNav({ basePath, page, totalPages }: PaginationNavProps): react_jsx_runtime.JSX.Element | null;
+
+type ArticleViewTrackerProps = Readonly<{
+    article: Pick<Article, 'slug'> & Partial<Pick<Article, 'category' | 'seriesSlug' | 'wordCount'>>;
+    config?: ArticlesConfig;
+}>;
+/**
+ * Renders nothing - fires `article_viewed` on mount and `meaningful_read`
+ * once, after roughly half the article's estimated read time has elapsed
+ * (a deterministic, testable timing approximation rather than scroll-depth
+ * tracking, which this package has no reliable cross-app way to measure
+ * since it doesn't own the article body's scroll container). Place once on
+ * the article detail page alongside `ArticleContent`.
+ */
+declare function ArticleViewTracker({ article, config }: ArticleViewTrackerProps): null;
+type CtaViewTrackerProps = Readonly<{
+    /** Opaque CTA/offer ID - never label text (no PII/marketing copy in event payloads). */
+    ctaId: string;
+    articleSlug?: string;
+    config?: ArticlesConfig;
+    children: ReactNode;
+}>;
+/**
+ * Wraps any CTA block and fires `cta_viewed` once, the first time at least
+ * half of it scrolls into the viewport (`IntersectionObserver`). Falls back
+ * to firing immediately when `IntersectionObserver` isn't available (older
+ * browsers, non-DOM test environments) rather than never firing.
+ */
+declare function CtaViewTracker({ ctaId, articleSlug, config, children }: CtaViewTrackerProps): react_jsx_runtime.JSX.Element;
+
 interface CommentsSectionProps {
     readonly articleSlug: string;
     readonly config: CommentsConfig;
@@ -447,6 +801,6 @@ interface UseArticlesReturn {
     error: string | null;
     handleSearch: (query: string) => void;
 }
-declare function useArticles(): UseArticlesReturn;
+declare function useArticles(initialArticles?: Article[], initialCategories?: CategoryInfo[]): UseArticlesReturn;
 
-export { type Article, ArticleBackLink, type ArticleBreadcrumbEntry, type ArticleBreadcrumbToken, ArticleCard, ArticleCategoryGrid, type ArticleComment, type ArticleCommentWithReplies, ArticleDetailHero, ArticleNavigation, ArticleSEO, ArticleSchema, ArticleSearchBar, ArticleSocialShare, ArticleTOC, type ArticlesConfig, ArticlesHero, ArticlesPage, type ArticlesSection, type ArticlesTheme, AuthorArticlesPage, type AuthorBreadcrumbEntry, type AuthorBreadcrumbToken, AuthorCard, AuthorDetailHero, type AuthorProfile, type AuthorSocial, AuthorSocialLinks, Breadcrumb, type BreadcrumbItem, type BreadcrumbLabels, BreadcrumbSchema, type BreadcrumbsConfig, CategoryArticlesPage, type CategoryBreadcrumbEntry, type CategoryBreadcrumbToken, type CategoryDescription, type CategoryInfo, CollectionPageSchema, CommentForm, CommentItem, CommentThread, type CommentsConfig, CommentsSection, type CustomBreadcrumbItem, DEFAULT_CATEGORIES_PAGE_SIZE, DEFAULT_LAYOUT, DEFAULT_PAGE_SIZE, FAQPageSchema, type FaqItem, FeaturedArticle, type HowToStep, LatestArticles, LatestArticlesSection, type LinkTargetStrategy, type MdxComponents, ScrollToTop, type TocItem, type UseArticlesReturn, breadcrumbsAreEnabled, getBreadcrumbsConfig, useArticles };
+export { type Article, ArticleBackLink, type ArticleBreadcrumbEntry, type ArticleBreadcrumbToken, ArticleCard, ArticleCategoryGrid, type ArticleComment, type ArticleCommentWithReplies, ArticleDetailHero, type ArticleEvent, type ArticleEventHandler, type ArticleEventName, ArticleNavigation, ArticleSEO, ArticleSearchBar, ArticleSocialShare, ArticleTOC, ArticleViewTracker, type ArticleViewedEvent, type ArticlesConfig, ArticlesHero, ArticlesPage, type ArticlesSection, type ArticlesTheme, AuthorArticlesPage, type AuthorBreadcrumbEntry, type AuthorBreadcrumbToken, AuthorCard, type AuthorClickedEvent, AuthorDetailHero, type AuthorPageSection, type AuthorProfile, type AuthorSocial, AuthorSocialLinks, Breadcrumb, type BreadcrumbItem, type BreadcrumbLabels, BreadcrumbSchema, type BreadcrumbsConfig, CategoryArticlesPage, type CategoryBreadcrumbEntry, type CategoryBreadcrumbToken, type CategoryDescription, type CategoryInfo, type CollectionPageItem, CollectionPageSchema, CommentForm, CommentItem, CommentThread, type CommentsConfig, CommentsSection, type CtaClickedEvent, CtaViewTracker, type CtaViewedEvent, type CustomBreadcrumbItem, DEFAULT_CATEGORIES_PAGE_SIZE, DEFAULT_LAYOUT, DEFAULT_PAGE_SIZE, FAQPageSchema, type FaqItem, FeaturedArticle, type HowToStep, LatestArticles, LatestArticlesSection, type LinkTargetStrategy, type ListingPagination, type ListingPaginationContext, type MdxComponents, type MeaningfulReadEvent, PaginationNav, type PathDefinition, type PathStepAdvancedEvent, type ProofItem, type RelatedArticleClickedEvent, RelatedArticlesSection, type RichText, type RichTextSection, ScrollToTop, SeriesArticlesPage, type SharedEvent, type TocItem, type UseArticlesReturn, breadcrumbsAreEnabled, getBreadcrumbsConfig, useArticles };