@asteroidcms/core-utils 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -1,9 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as react from 'react';
-import { PropsWithChildren } from 'react';
-import * as _apollo_client from '@apollo/client';
 import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient, DocumentNode } from '@apollo/client';
-import { useMutation } from '@apollo/client/react';
 
 type AsteroidCMSConfig = {
     /** Base URL of the Asteroid CMS API (e.g. https://cms-api.example.com). */
@@ -30,25 +25,6 @@ type ResolvedAsteroidCMSConfig = Required<Pick<AsteroidCMSConfig, "cmsUrl" | "ap
     onError?: AsteroidCMSConfig["onError"];
 };
 
-type AsteroidCMSProviderProps = PropsWithChildren<AsteroidCMSConfig>;
-/**
- * Root provider for `@asteroidcms/core-utils`.
- *
- * Wrap your app once at the top level:
- *
- * ```tsx
- * <AsteroidCMSProvider cmsUrl="https://cms.example.com" apiKey="...">
- *   <App />
- * </AsteroidCMSProvider>
- * ```
- *
- * Everything below — `useCmsContent`, `useCmsMutate`, `useCmsImage`,
- * `<RichTextContent>` — picks up `cmsUrl` and `apiKey` from this provider.
- */
-declare function AsteroidCMSProvider({ children, ...config }: AsteroidCMSProviderProps): react_jsx_runtime.JSX.Element;
-
-declare function useAsteroidCMSConfig(): ResolvedAsteroidCMSConfig;
-
 declare module "@apollo/client" {
     namespace ApolloClient.DeclareDefaultOptions {
         interface WatchQuery {
@@ -65,146 +41,6 @@ declare module "@apollo/client" {
 }
 declare function createApolloClient(config: AsteroidCMSConfig): ApolloClient;
 
-type FieldSelector$2 = string | {
-    field: string;
-    as?: string;
-};
-type ReferenceExpansion$2 = {
-    field: string;
-    as?: string;
-    single?: boolean;
-    select?: readonly (FieldSelector$2 | ReferenceExpansion$2)[];
-};
-type ContentStatus$1 = "DRAFT" | "PUBLISHED" | "ARCHIVED";
-type CmsSearchCondition$1 = {
-    field: string;
-    value: string;
-    mode?: string;
-};
-type UseCmsContentOptions$1 = {
-    schema_slug: string;
-    entrySlug?: string;
-    select?: readonly (FieldSelector$2 | ReferenceExpansion$2)[];
-    fullData?: boolean;
-    limit?: number;
-    offset?: number;
-    status?: ContentStatus$1;
-    filter?: Record<string, string | number | boolean | null>;
-    search?: CmsSearchCondition$1[];
-    variables?: Record<string, any>;
-};
-/**
- * React hook for querying content from Asteroid CMS via a flexible GraphQL API.
- *
- * Supports single-entry fetches (`entrySlug`) and paginated/filtered lists,
- * with arbitrarily nested reference expansion and field aliasing.
- */
-declare function useCmsContent<T = unknown>({ schema_slug, entrySlug, select, fullData, limit, offset, status, filter, search, variables, }: UseCmsContentOptions$1): {
-    client: _apollo_client.ApolloClient;
-    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
-    previousData?: unknown;
-    networkStatus: _apollo_client.NetworkStatus;
-    startPolling: (pollInterval: number) => void;
-    stopPolling: () => void;
-    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
-    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
-    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
-        data: unknown;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    variables: _apollo_client.OperationVariables;
-    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
-        data: TFetchData | undefined;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    dataState: "empty";
-    loading: boolean;
-    error: _apollo_client.ErrorLike | undefined;
-    data: T | undefined;
-} | {
-    client: _apollo_client.ApolloClient;
-    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
-    previousData?: unknown;
-    networkStatus: _apollo_client.NetworkStatus;
-    startPolling: (pollInterval: number) => void;
-    stopPolling: () => void;
-    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
-    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
-    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
-        data: unknown;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    variables: _apollo_client.OperationVariables;
-    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
-        data: TFetchData | undefined;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    dataState: "complete";
-    loading: boolean;
-    error: _apollo_client.ErrorLike | undefined;
-    data: T | undefined;
-} | {
-    client: _apollo_client.ApolloClient;
-    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
-    previousData?: unknown;
-    networkStatus: _apollo_client.NetworkStatus;
-    startPolling: (pollInterval: number) => void;
-    stopPolling: () => void;
-    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
-    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
-    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
-        data: unknown;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    variables: _apollo_client.OperationVariables;
-    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
-        data: TFetchData | undefined;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    dataState: "streaming";
-    loading: boolean;
-    error: _apollo_client.ErrorLike | undefined;
-    data: T | undefined;
-};
-
-type FieldSelector$1 = string | {
-    field: string;
-    as?: string;
-    single?: boolean;
-    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
-};
-type ReferenceExpansion$1 = {
-    field: string;
-    as?: string;
-    single?: boolean;
-    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
-};
-type MutationType = "create" | "update" | "delete";
-type UseCmsMutateOptions = {
-    schema_slug: string;
-    entrySlug?: string;
-    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
-    fullData?: boolean;
-    mutationType?: MutationType;
-    entryId?: string;
-    variables?: Record<string, any>;
-};
-/**
- * React hook for mutating content in Asteroid CMS (`create` / `update` / `delete`).
- * Uses the same selection syntax as `useCmsContent`.
- */
-declare function useCmsMutate<TData = unknown>({ schema_slug, select, fullData, mutationType, entryId, variables: inputVariables, }: UseCmsMutateOptions): {
-    readonly data: TData | undefined;
-    readonly loading: boolean;
-    readonly called: boolean;
-    readonly client: _apollo_client.ApolloClient;
-    readonly reset: () => void;
-    readonly error: _apollo_client.ErrorLike | undefined;
-    readonly mutate: useMutation.MutationFunction<unknown, {
-        [x: string]: any;
-    }, _apollo_client.ApolloCache, "none">;
-};
-
 type FieldSelector = string | {
     field: string;
     as?: string;
@@ -250,8 +86,6 @@ declare function cmsImage(id: string | undefined, options: {
     cmsUrl: string;
     mediaPath?: string;
 }): string;
-/** Hook variant that pulls `cmsUrl`/`mediaPath` from the provider. */
-declare function useCmsImage(): (id?: string) => string;
 
 type ReadTimeUnit = "short" | "long";
 interface GetContentReadTimeOptions {
@@ -307,6 +141,12 @@ interface ParseRichTextOptions {
     classMap?: RichTextClassMap;
     /** Tag allowlist override. Defaults to a safe semantic set. */
     allowlist?: ReadonlyArray<string>;
+    /**
+     * When `true` (default), inject slugified `id` attributes on `<h1>`–`<h6>`
+     * tags that don't already have one. Lets ToC anchors resolve from the
+     * server-rendered markup without a client-side mutation step.
+     */
+    autoHeadingIds?: boolean;
 }
 declare function parseRichText(html: string, options?: ParseRichTextOptions): string;
 /**
@@ -316,19 +156,41 @@ declare function parseRichText(html: string, options?: ParseRichTextOptions): st
  */
 declare function removeEmptyParagraphs(html: string): string;
 
-interface RichTextContentProps {
-    html: string;
-    classMap?: RichTextClassMap;
-    /** Wrapper element. Defaults to `div`. Use `article` for blog content. */
-    as?: keyof React.JSX.IntrinsicElements;
-    className?: string;
+/**
+ * Heading extraction helpers used to build tables of contents (ToC) from
+ * rich-text HTML. Server-safe — no React, no DOM dependency in the HTML
+ * variant. The DOM variant assigns missing `id`s in-place so anchor links
+ * resolve immediately.
+ */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+interface ExtractedHeading {
+    id: string;
+    text: string;
+    level: HeadingLevel;
+}
+interface ExtractHeadingsOptions {
+    /** Levels to include. Defaults to `[2, 3]` — typical doc page outline. */
+    levels?: ReadonlyArray<HeadingLevel>;
+    /** Custom slug function. Defaults to a lowercase/kebab/diacritic-safe slug. */
+    slugify?: (text: string, index: number) => string;
 }
-declare function RichTextContent({ html, classMap, as, className, }: RichTextContentProps): react.DOMElement<{
-    ref: react.MutableRefObject<HTMLElement | null>;
-    className: string | undefined;
-    dangerouslySetInnerHTML: {
-        __html: string;
-    };
-}, HTMLElement>;
+declare function slugify(text: string): string;
+/**
+ * Parse headings out of a raw HTML string. Returns headings in document
+ * order with stable, de-duplicated IDs.
+ *
+ * If a heading already has an `id` attribute, it's preserved verbatim
+ * (and reserved so later slugs don't collide with it).
+ */
+declare function extractHeadingsFromHtml(html: string, options?: ExtractHeadingsOptions): ExtractedHeading[];
+/**
+ * Walk a rendered DOM subtree, collect headings, and assign missing `id`s
+ * in-place so anchor links resolve immediately. Also sets `scrollMarginTop`
+ * on each heading when `scrollMarginTop` is provided so navigation lands
+ * cleanly below a sticky header.
+ */
+declare function extractHeadingsFromElement(root: HTMLElement, options?: ExtractHeadingsOptions & {
+    scrollMarginTop?: number;
+}): ExtractedHeading[];
 
-export { type AsteroidCMSConfig, AsteroidCMSProvider, type AsteroidCMSProviderProps, type CmsSearchCondition, type ContentStatus, type FieldSelector, type ParseRichTextOptions, type ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, RichTextContent, type UseCmsContentOptions$1 as UseCmsContentOptions, type UseCmsMutateOptions, buildCmsQuery, cmsImage, createApolloClient, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };
+export { type AsteroidCMSConfig, type CmsSearchCondition, type ContentStatus, type ExtractHeadingsOptions, type ExtractedHeading, type FieldSelector, type HeadingLevel, type ParseRichTextOptions, type ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type UseCmsContentOptions, buildCmsQuery, cmsImage, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, slugify };

package/dist/index.d.ts

@@ -1,9 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as react from 'react';
-import { PropsWithChildren } from 'react';
-import * as _apollo_client from '@apollo/client';
 import { InMemoryCacheConfig, ApolloClientOptions, ApolloClient, DocumentNode } from '@apollo/client';
-import { useMutation } from '@apollo/client/react';
 
 type AsteroidCMSConfig = {
     /** Base URL of the Asteroid CMS API (e.g. https://cms-api.example.com). */
@@ -30,25 +25,6 @@ type ResolvedAsteroidCMSConfig = Required<Pick<AsteroidCMSConfig, "cmsUrl" | "ap
     onError?: AsteroidCMSConfig["onError"];
 };
 
-type AsteroidCMSProviderProps = PropsWithChildren<AsteroidCMSConfig>;
-/**
- * Root provider for `@asteroidcms/core-utils`.
- *
- * Wrap your app once at the top level:
- *
- * ```tsx
- * <AsteroidCMSProvider cmsUrl="https://cms.example.com" apiKey="...">
- *   <App />
- * </AsteroidCMSProvider>
- * ```
- *
- * Everything below — `useCmsContent`, `useCmsMutate`, `useCmsImage`,
- * `<RichTextContent>` — picks up `cmsUrl` and `apiKey` from this provider.
- */
-declare function AsteroidCMSProvider({ children, ...config }: AsteroidCMSProviderProps): react_jsx_runtime.JSX.Element;
-
-declare function useAsteroidCMSConfig(): ResolvedAsteroidCMSConfig;
-
 declare module "@apollo/client" {
     namespace ApolloClient.DeclareDefaultOptions {
         interface WatchQuery {
@@ -65,146 +41,6 @@ declare module "@apollo/client" {
 }
 declare function createApolloClient(config: AsteroidCMSConfig): ApolloClient;
 
-type FieldSelector$2 = string | {
-    field: string;
-    as?: string;
-};
-type ReferenceExpansion$2 = {
-    field: string;
-    as?: string;
-    single?: boolean;
-    select?: readonly (FieldSelector$2 | ReferenceExpansion$2)[];
-};
-type ContentStatus$1 = "DRAFT" | "PUBLISHED" | "ARCHIVED";
-type CmsSearchCondition$1 = {
-    field: string;
-    value: string;
-    mode?: string;
-};
-type UseCmsContentOptions$1 = {
-    schema_slug: string;
-    entrySlug?: string;
-    select?: readonly (FieldSelector$2 | ReferenceExpansion$2)[];
-    fullData?: boolean;
-    limit?: number;
-    offset?: number;
-    status?: ContentStatus$1;
-    filter?: Record<string, string | number | boolean | null>;
-    search?: CmsSearchCondition$1[];
-    variables?: Record<string, any>;
-};
-/**
- * React hook for querying content from Asteroid CMS via a flexible GraphQL API.
- *
- * Supports single-entry fetches (`entrySlug`) and paginated/filtered lists,
- * with arbitrarily nested reference expansion and field aliasing.
- */
-declare function useCmsContent<T = unknown>({ schema_slug, entrySlug, select, fullData, limit, offset, status, filter, search, variables, }: UseCmsContentOptions$1): {
-    client: _apollo_client.ApolloClient;
-    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
-    previousData?: unknown;
-    networkStatus: _apollo_client.NetworkStatus;
-    startPolling: (pollInterval: number) => void;
-    stopPolling: () => void;
-    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
-    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
-    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
-        data: unknown;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    variables: _apollo_client.OperationVariables;
-    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
-        data: TFetchData | undefined;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    dataState: "empty";
-    loading: boolean;
-    error: _apollo_client.ErrorLike | undefined;
-    data: T | undefined;
-} | {
-    client: _apollo_client.ApolloClient;
-    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
-    previousData?: unknown;
-    networkStatus: _apollo_client.NetworkStatus;
-    startPolling: (pollInterval: number) => void;
-    stopPolling: () => void;
-    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
-    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
-    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
-        data: unknown;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    variables: _apollo_client.OperationVariables;
-    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
-        data: TFetchData | undefined;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    dataState: "complete";
-    loading: boolean;
-    error: _apollo_client.ErrorLike | undefined;
-    data: T | undefined;
-} | {
-    client: _apollo_client.ApolloClient;
-    observable: _apollo_client.ObservableQuery<unknown, _apollo_client.OperationVariables>;
-    previousData?: unknown;
-    networkStatus: _apollo_client.NetworkStatus;
-    startPolling: (pollInterval: number) => void;
-    stopPolling: () => void;
-    subscribeToMore: _apollo_client.SubscribeToMoreFunction<unknown, _apollo_client.OperationVariables>;
-    updateQuery: (mapFn: _apollo_client.UpdateQueryMapFn<unknown, _apollo_client.OperationVariables>) => void;
-    refetch: (variables?: Partial<_apollo_client.OperationVariables> | undefined) => Promise<{
-        data: unknown;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    variables: _apollo_client.OperationVariables;
-    fetchMore: <TFetchData = unknown, TFetchVars extends _apollo_client.OperationVariables = _apollo_client.OperationVariables>(fetchMoreOptions: _apollo_client.ObservableQuery.FetchMoreOptions<unknown, _apollo_client.OperationVariables, TFetchData, TFetchVars>) => Promise<{
-        data: TFetchData | undefined;
-        error?: _apollo_client.ErrorLike;
-    }>;
-    dataState: "streaming";
-    loading: boolean;
-    error: _apollo_client.ErrorLike | undefined;
-    data: T | undefined;
-};
-
-type FieldSelector$1 = string | {
-    field: string;
-    as?: string;
-    single?: boolean;
-    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
-};
-type ReferenceExpansion$1 = {
-    field: string;
-    as?: string;
-    single?: boolean;
-    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
-};
-type MutationType = "create" | "update" | "delete";
-type UseCmsMutateOptions = {
-    schema_slug: string;
-    entrySlug?: string;
-    select?: readonly (FieldSelector$1 | ReferenceExpansion$1)[];
-    fullData?: boolean;
-    mutationType?: MutationType;
-    entryId?: string;
-    variables?: Record<string, any>;
-};
-/**
- * React hook for mutating content in Asteroid CMS (`create` / `update` / `delete`).
- * Uses the same selection syntax as `useCmsContent`.
- */
-declare function useCmsMutate<TData = unknown>({ schema_slug, select, fullData, mutationType, entryId, variables: inputVariables, }: UseCmsMutateOptions): {
-    readonly data: TData | undefined;
-    readonly loading: boolean;
-    readonly called: boolean;
-    readonly client: _apollo_client.ApolloClient;
-    readonly reset: () => void;
-    readonly error: _apollo_client.ErrorLike | undefined;
-    readonly mutate: useMutation.MutationFunction<unknown, {
-        [x: string]: any;
-    }, _apollo_client.ApolloCache, "none">;
-};
-
 type FieldSelector = string | {
     field: string;
     as?: string;
@@ -250,8 +86,6 @@ declare function cmsImage(id: string | undefined, options: {
     cmsUrl: string;
     mediaPath?: string;
 }): string;
-/** Hook variant that pulls `cmsUrl`/`mediaPath` from the provider. */
-declare function useCmsImage(): (id?: string) => string;
 
 type ReadTimeUnit = "short" | "long";
 interface GetContentReadTimeOptions {
@@ -307,6 +141,12 @@ interface ParseRichTextOptions {
     classMap?: RichTextClassMap;
     /** Tag allowlist override. Defaults to a safe semantic set. */
     allowlist?: ReadonlyArray<string>;
+    /**
+     * When `true` (default), inject slugified `id` attributes on `<h1>`–`<h6>`
+     * tags that don't already have one. Lets ToC anchors resolve from the
+     * server-rendered markup without a client-side mutation step.
+     */
+    autoHeadingIds?: boolean;
 }
 declare function parseRichText(html: string, options?: ParseRichTextOptions): string;
 /**
@@ -316,19 +156,41 @@ declare function parseRichText(html: string, options?: ParseRichTextOptions): st
  */
 declare function removeEmptyParagraphs(html: string): string;
 
-interface RichTextContentProps {
-    html: string;
-    classMap?: RichTextClassMap;
-    /** Wrapper element. Defaults to `div`. Use `article` for blog content. */
-    as?: keyof React.JSX.IntrinsicElements;
-    className?: string;
+/**
+ * Heading extraction helpers used to build tables of contents (ToC) from
+ * rich-text HTML. Server-safe — no React, no DOM dependency in the HTML
+ * variant. The DOM variant assigns missing `id`s in-place so anchor links
+ * resolve immediately.
+ */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+interface ExtractedHeading {
+    id: string;
+    text: string;
+    level: HeadingLevel;
+}
+interface ExtractHeadingsOptions {
+    /** Levels to include. Defaults to `[2, 3]` — typical doc page outline. */
+    levels?: ReadonlyArray<HeadingLevel>;
+    /** Custom slug function. Defaults to a lowercase/kebab/diacritic-safe slug. */
+    slugify?: (text: string, index: number) => string;
 }
-declare function RichTextContent({ html, classMap, as, className, }: RichTextContentProps): react.DOMElement<{
-    ref: react.MutableRefObject<HTMLElement | null>;
-    className: string | undefined;
-    dangerouslySetInnerHTML: {
-        __html: string;
-    };
-}, HTMLElement>;
+declare function slugify(text: string): string;
+/**
+ * Parse headings out of a raw HTML string. Returns headings in document
+ * order with stable, de-duplicated IDs.
+ *
+ * If a heading already has an `id` attribute, it's preserved verbatim
+ * (and reserved so later slugs don't collide with it).
+ */
+declare function extractHeadingsFromHtml(html: string, options?: ExtractHeadingsOptions): ExtractedHeading[];
+/**
+ * Walk a rendered DOM subtree, collect headings, and assign missing `id`s
+ * in-place so anchor links resolve immediately. Also sets `scrollMarginTop`
+ * on each heading when `scrollMarginTop` is provided so navigation lands
+ * cleanly below a sticky header.
+ */
+declare function extractHeadingsFromElement(root: HTMLElement, options?: ExtractHeadingsOptions & {
+    scrollMarginTop?: number;
+}): ExtractedHeading[];
 
-export { type AsteroidCMSConfig, AsteroidCMSProvider, type AsteroidCMSProviderProps, type CmsSearchCondition, type ContentStatus, type FieldSelector, type ParseRichTextOptions, type ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, RichTextContent, type UseCmsContentOptions$1 as UseCmsContentOptions, type UseCmsMutateOptions, buildCmsQuery, cmsImage, createApolloClient, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, useAsteroidCMSConfig, useCmsContent, useCmsImage, useCmsMutate };
+export { type AsteroidCMSConfig, type CmsSearchCondition, type ContentStatus, type ExtractHeadingsOptions, type ExtractedHeading, type FieldSelector, type HeadingLevel, type ParseRichTextOptions, type ReferenceExpansion, type ResolvedAsteroidCMSConfig, type RichTextClassKey, type RichTextClassMap, type UseCmsContentOptions, buildCmsQuery, cmsImage, createApolloClient, extractHeadingsFromElement, extractHeadingsFromHtml, fetchCmsContent, getContentReadTime, parseRichText, removeEmptyParagraphs, slugify };