@ox-content/napi 3.0.0-alpha.9 → 3.0.0-beta.0

package/index.d.ts

@@ -45,6 +45,9 @@ export declare class IncrementalMarkdownRenderer {
  */
 export declare function applyPendingHighlights(html: string, replacements: Array<string>): string
 
+/** Rewrites rendered article HTML with reader-chrome controls. */
+export declare function applySsgReaderChromeHtml(html: string, chrome?: JsReaderChrome | undefined | null): string
+
 /**
  * Builds a Markdown collection manifest directly from files on the Rust side.
  *
@@ -149,6 +152,12 @@ export declare function extractSsgTitle(content: string, frontmatterTitle?: stri
  */
 export declare function extractTranslationKeys(source: string, filePath: string, functionNames?: Array<string> | undefined | null): Array<I18NKeyUsage>
 
+/**
+ * Extracts a YouTube video id from a bare id or a watch / share / embed /
+ * shorts URL, returning `null` when the input names no video.
+ */
+export declare function extractYoutubeVideoId(input: string): string | null
+
 /** Formats a file or directory segment as an SSG title. */
 export declare function formatSsgTitle(name: string): string
 
@@ -172,6 +181,9 @@ export declare function generateDocsNavMetadata(files: Array<string>, basePath?:
  */
 export declare function generateDocsNavMetadataFromDocs(docs: Array<JsDocsMarkdownModule>, options?: JsDocsNavOptions | undefined | null): Array<JsDocsNavItem>
 
+/** Builds RSS / Atom / JSON Feed bodies without writing files. */
+export declare function generateFeedBodies(options: JsFeedsOptions, items: Array<JsFeedItem>): JsFeedsOutput
+
 /** Generates the `virtual:ox-content/i18n` runtime module. */
 export declare function generateI18nModule(dictDir: string, config: JsI18NRuntimeConfig): string
 
@@ -183,12 +195,18 @@ export declare function generateI18nModule(dictDir: string, config: JsI18NRuntim
  */
 export declare function generateOgImageSvg(data: JsOgImageData, config?: JsOgImageConfig | undefined | null): string
 
+/** Generates static OpenAPI reference Markdown pages from local JSON/YAML files. */
+export declare function generateOpenApiDocs(inputs: Array<JsOpenApiDocsInput>, options?: JsOpenApiDocsOptions | undefined | null): JsGeneratedOpenApiDocs
+
 /** Generates the client-side search runtime module. */
 export declare function generateSearchModule(optionsJson: string, indexPath: string): string
 
 /** Generates the client-side search runtime module from typed options. */
 export declare function generateSearchModuleFromOptions(options: JsSearchRuntimeOptions, indexPath: string): string
 
+/** Builds `sitemap.xml`, `robots.txt`, and `llms.txt` bodies without writing files. */
+export declare function generateSiteMapBodies(options: JsSiteMapsOptions, pages: Array<JsSiteMapPage>): JsSiteMapsOutput
+
 /** Generates a bare SSG HTML page without navigation or styles. */
 export declare function generateSsgBareHtml(content: string, title: string): string
 
@@ -216,6 +234,12 @@ export declare function getSsgOutputPath(inputPath: string, srcDir: string, outD
 /** Resolves a page locale from an SSG URL path and configured locale codes. */
 export declare function getSsgPageLocale(urlPath: string, defaultLocale: string, localeCodes: Array<string>): string | null
 
+/** CSS used by the built-in reader chrome and custom hosts. */
+export declare function getSsgReaderChromeCss(): string
+
+/** Auto-initializing browser script used by the built-in reader chrome. */
+export declare function getSsgReaderChromeScript(): string
+
 /** Converts a markdown file path to a relative SSG URL path. */
 export declare function getSsgUrlPath(inputPath: string, srcDir: string): string
 
@@ -329,12 +353,37 @@ export interface IncrementalMarkdownRenderResult {
   errors: Array<string>
 }
 
+/** Same-origin path check: leading `/`, not `//`, and no scheme. */
+export declare function isSafeRedirectDest(value: string): boolean
+
 /** Opt-in skip link and print styles. Presence of the object enables the feature. */
 export interface JsA11y {
   /** Override for the skip-link label. Empty / omitted uses "Skip to content". */
   skipLinkLabel?: string
 }
 
+/** Opt-in abbreviation and glossary expansion. */
+export interface JsAbbreviationsOptions {
+  /**
+   * Enable `*[TERM]: expansion` and config-term rewriting.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Central glossary terms. Keys are matched with Unicode word boundaries.
+   *
+   * Default: `{}`.
+   */
+  terms?: Record<string, string>
+  /**
+   * Wrap only the first occurrence of each term.
+   *
+   * Default: `false` (every occurrence).
+   */
+  firstUseOnly?: boolean
+}
+
 /** Attribute syntax transform options. */
 export interface JsAttrsOptions {
   /**
@@ -427,6 +476,16 @@ export interface JsCodeBlockLintOptions {
   trailingSpaces?: boolean
 }
 
+/** Opt-in `::: code-group` fence groups. */
+export interface JsCodeGroupOptions {
+  /**
+   * Enable VitePress-style `::: code-group` rewriting.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+}
+
 /** Code import / snippet injection options. */
 export interface JsCodeImportOptions {
   /**
@@ -452,6 +511,22 @@ export interface JsCollectionDefinition {
   include: Array<string>
 }
 
+/** Opt-in static `::: if` / `::: else` conditional blocks. */
+export interface JsConditionalBlockOptions {
+  /**
+   * Enable conditional block evaluation.
+   *
+   * Default: `true` when the options object is supplied.
+   */
+  enabled?: boolean
+  /**
+   * Build-time values available as `config.*` or bare identifiers.
+   *
+   * Default: `{}`.
+   */
+  values?: Record<string, any>
+}
+
 /** Opt-in `::: tip` custom containers. */
 export interface JsContainerOptions {
   /**
@@ -472,6 +547,81 @@ export interface JsContainerTypeOptions {
   tag?: string
 }
 
+/** One rule the document broke. */
+export interface JsCrossReferenceDiagnostic {
+  /** `"error"` or `"warn"`, as the options asked. */
+  policy: string
+  message: string
+}
+
+/** One numbered target the document defines. */
+export interface JsCrossReferenceEntry {
+  id: string
+  /** `"figure"`, `"table"`, or `"section"`. */
+  kind: string
+  number: string
+  label: string
+  text: string
+  href: string
+  title?: string
+}
+
+/** The word placed before each number, per kind. */
+export interface JsCrossReferenceLabels {
+  figure?: string
+  table?: string
+  section?: string
+}
+
+/** The annotated HTML, what it defined, and what it got wrong. */
+export interface JsCrossReferenceOutput {
+  html: string
+  references: Array<JsCrossReferenceEntry>
+  diagnostics: Array<JsCrossReferenceDiagnostic>
+}
+
+/** Switches and labels for the cross-reference pass. */
+export interface JsCrossReferencesOptions {
+  enabled: boolean
+  /** `"warn"` reports and carries on; anything else fails the build. */
+  missing?: string
+  duplicates?: string
+  mismatches?: string
+  labels?: JsCrossReferenceLabels
+}
+
+/** Opt-in static `csv-table` / `json-table` fences. */
+export interface JsDataTableOptions {
+  /**
+   * Enable `csv-table` and `json-table` fences.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Root directory used for `@/` and absolute data-table imports.
+   *
+   * Default: project root from the JavaScript caller.
+   */
+  rootDir?: string
+  /**
+   * What to do when an imported file is missing.
+   *
+   * Default: `"error"`.
+   */
+  missing?: string
+}
+
+/** Opt-in PHP Markdown Extra / mdBook-style definition lists. */
+export interface JsDefinitionListOptions {
+  /**
+   * Enable `Term` / `: definition` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+}
+
 /** Normalized documentation entry used by generated API docs. */
 export interface JsDocEntry {
   name: string
@@ -744,11 +894,35 @@ export interface JsEditThisPageOptions {
    */
   branch?: string
   /**
-   * Root directory used to relativize `sourcePath`.
+   * Where the source root sits inside the repository. Prefixed to the
+   * page path, which is then taken relative to `src_dir`.
    *
-   * Default: no extra root prefix.
+   * Default: no prefix, and the page path stays relative to the process's
+   * working directory.
    */
   rootDir?: string
+  /**
+   * Absolute path of the source root on disk, supplied by the build so
+   * `root_dir` can be joined with the page's path inside that root.
+   *
+   * Default: none, which makes `root_dir` inert.
+   */
+  srcDir?: string
+  /**
+   * Forge whose edit-URL shape to use: `github`, `gitlab`, `bitbucket`,
+   * or `gitea`.
+   *
+   * Default: inferred from the `repo_url` host, falling back to
+   * `github`. An unrecognized value is inferred the same way.
+   */
+  provider?: string
+  /**
+   * Edit-URL template, which wins over `provider`. Understands
+   * `{repoUrl}`, `{branch}`, and `{path}`; other braces stay literal.
+   *
+   * Default: the pattern for the resolved provider.
+   */
+  urlPattern?: string
   /**
    * Link label.
    *
@@ -757,6 +931,34 @@ export interface JsEditThisPageOptions {
   label?: string
 }
 
+/**
+ * Transform opt-in static media embed components in already-rendered HTML.
+ * One tag an enabled provider refused, and what the transform did instead.
+ */
+export interface JsEmbedDiagnostic {
+  /** Tag name as the provider registers it, for example `speakerdeck`. */
+  provider: string
+  /** The URL the tag carried, when it carried one worth naming. */
+  url?: string
+  /** 1-based line of the opening tag in the transformed HTML. */
+  line: number
+  /**
+   * `"linked"` when the tag became a plain link, `"kept"` when its markup
+   * was left as authored.
+   */
+  fallback: string
+}
+
+/** One provider tag as authors write it. */
+export interface JsEmbedTag {
+  name: string
+  /**
+   * True when only the PascalCase spelling is an embed, because the
+   * lowercase one is a real HTML element.
+   */
+  pascalOnly: boolean
+}
+
 /** Emoji-shortcode transform options. */
 export interface JsEmojiShortcodeOptions {
   /**
@@ -867,6 +1069,65 @@ export interface JsFeatureConfig {
   linkText?: string
 }
 
+/** A file carried alongside a feed item. */
+export interface JsFeedAttachment {
+  url: string
+  mimeType?: string
+  title?: string
+  sizeInBytes?: number
+  durationInSeconds?: number
+}
+
+/** A person credited on a feed item. */
+export interface JsFeedAuthor {
+  name: string
+  url?: string
+}
+
+/** One collection entry considered for a feed. */
+export interface JsFeedItem {
+  title: string
+  description?: string
+  loc: string
+  date?: string
+  lastUpdated?: string
+  draft?: boolean
+  unlisted?: boolean
+  content?: string
+  id?: string
+  authors?: Array<JsFeedAuthor>
+  image?: string
+  attachments?: Array<JsFeedAttachment>
+  language?: string
+}
+
+/** Switches and site metadata for feed generation. */
+export interface JsFeedsOptions {
+  enabled: boolean
+  siteUrl?: string
+  siteName: string
+  siteDescription?: string
+  homePageUrl: string
+  rssUrl: string
+  atomUrl: string
+  jsonUrl: string
+  /** Any of `"rss"`, `"atom"`, `"json"`. Unknown names are ignored. */
+  formats: Array<string>
+  limit: number
+  language?: string
+  image?: string
+  favicon?: string
+  copyright?: string
+}
+
+/** Generated feed bodies, or a warning when generation is skipped. */
+export interface JsFeedsOutput {
+  rssXml?: string
+  atomXml?: string
+  jsonFeed?: string
+  warning?: string
+}
+
 /** Opt-in static `file-tree` fences. */
 export interface JsFileTreeOptions {
   /**
@@ -904,6 +1165,12 @@ export interface JsFrameworkComponentIsland {
   content?: string
 }
 
+/** Generated OpenAPI Markdown pages and navigation metadata. */
+export interface JsGeneratedOpenApiDocs {
+  pages: Record<string, string>
+  nav: Array<JsDocsNavItem>
+}
+
 /** One unique git author returned by `getGitContributors`. */
 export interface JsGitContributor {
   /** Author name from `%an`. */
@@ -1026,6 +1293,34 @@ export interface JsI18NRuntimeLocale {
   dir?: string
 }
 
+/** Opt-in static `::: gallery` image groups. */
+export interface JsImageGalleryOptions {
+  /**
+   * Enable static image gallery blocks.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Add `loading="lazy"` to images inside galleries.
+   *
+   * Default: follows `images.lazy`, or `true` when `images` is disabled.
+   */
+  lazy?: boolean
+  /**
+   * Validation mode for images with empty alt text.
+   *
+   * Default: `"error"`.
+   */
+  missingAlt?: string
+  /**
+   * Validation mode for galleries without image items.
+   *
+   * Default: `"error"`.
+   */
+  empty?: string
+}
+
 /** Opt-in figures, captions, and lazy images. */
 export interface JsImageOptions {
   /**
@@ -1098,6 +1393,28 @@ export interface JsJsonLdPublisher {
   url?: string
 }
 
+/** Opt-in `{kbd:...}` inline keyboard keys. */
+export interface JsKeyboardKeysOptions {
+  /**
+   * Enable `{kbd:Ctrl+K}` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Build-time key aliases. Keys are matched case-insensitively.
+   *
+   * Default: `{}`.
+   */
+  aliases?: Record<string, string>
+  /**
+   * Label style for built-in aliases: `"words"` or `"symbols"`.
+   *
+   * Default: `"words"`.
+   */
+  style?: string
+}
+
 /** Locale information for the locale switcher. */
 export interface JsLocaleInfo {
   /** BCP 47 locale tag. */
@@ -1223,6 +1540,16 @@ export interface JsMathOptions {
   enabled?: boolean
 }
 
+/** A parsed document on its way to a JavaScript `transformers` hook. */
+export interface JsMdastTransformResult {
+  /** The tree, as mdast JSON. */
+  astJson: string
+  /** Frontmatter as JSON, which the tree has no room for. */
+  frontmatter: string
+  /** Preprocessing and parse errors collected so far. */
+  errors: Array<string>
+}
+
 /** Built-in media embed transform switches. */
 export interface JsMediaEmbedsOptions {
   /**
@@ -1231,6 +1558,18 @@ export interface JsMediaEmbedsOptions {
    * Default: `false`.
    */
   spotify?: boolean
+  /**
+   * Render `<AppleMusic>` embeds.
+   *
+   * Default: `false`.
+   */
+  appleMusic?: boolean
+  /**
+   * Render `<SpeakerDeck>` embeds.
+   *
+   * Default: `false`.
+   */
+  speakerDeck?: boolean
   /**
    * Render `<StackBlitz>` embeds.
    *
@@ -1249,12 +1588,154 @@ export interface JsMediaEmbedsOptions {
    * Default: `false`.
    */
   bluesky?: boolean
+  /**
+   * Render `<GoogleMaps>` static place cards.
+   *
+   * Default: `false`.
+   */
+  googleMaps?: boolean
+  /**
+   * Render `<Qiita>` static article cards.
+   *
+   * Default: `false`.
+   */
+  qiita?: boolean
+  /**
+   * Render `<Zenn>` static article cards.
+   *
+   * Default: `false`.
+   */
+  zenn?: boolean
+  /**
+   * Render package registry cards for npm, crates.io, PyPI, and Docker Hub.
+   *
+   * Default: `false`.
+   */
+  packageRegistry?: boolean
+  /**
+   * Render `<CodePen>`, `<JSFiddle>`, and `<Observable>` playground cards.
+   *
+   * Default: `false`.
+   */
+  playgrounds?: boolean
+  /**
+   * Render `<Vimeo>` video cards.
+   *
+   * Default: `false`.
+   */
+  vimeo?: boolean
+  /**
+   * Render `<Twitch>` video, clip, and channel cards.
+   *
+   * Default: `false`.
+   */
+  twitch?: boolean
+  /**
+   * Render `<Discord>` static invite/message cards.
+   *
+   * Default: `false`.
+   */
+  discord?: boolean
+  /**
+   * Render `<Fediverse>`, `<Mastodon>`, `<Misskey>`, and `<Mixi2>` static post cards.
+   *
+   * Default: `false`.
+   */
+  fediverse?: boolean
+  /**
+   * Render `<Facebook>` static post cards.
+   *
+   * Default: `false`.
+   */
+  facebook?: boolean
+  /**
+   * Render `<Threads>` static post cards.
+   *
+   * Default: `false`.
+   */
+  threads?: boolean
+  /**
+   * Render `<Instagram>` static post cards.
+   *
+   * Default: `false`.
+   */
+  instagram?: boolean
   /**
    * Render `<WebContainer>` lazy placeholder blocks.
    *
    * Default: `false`.
    */
   webContainer?: boolean
+  /**
+   * Render `<Audio>` native players.
+   *
+   * Default: `false`.
+   */
+  audio?: boolean
+  /**
+   * Render `<Video>` native players.
+   *
+   * Default: `false`.
+   */
+  video?: boolean
+  /**
+   * Render `<Loom>` recording cards.
+   *
+   * Default: `false`.
+   */
+  loom?: boolean
+  /**
+   * Render `<Asciinema>` terminal-recording cards.
+   *
+   * Default: `false`.
+   */
+  asciinema?: boolean
+  /**
+   * Render `<Figma>` file, design, board, and prototype cards.
+   *
+   * Default: `false`.
+   */
+  figma?: boolean
+  /**
+   * Render `<Note>` note.com article cards.
+   *
+   * Default: `false`.
+   */
+  note?: boolean
+  /**
+   * Render `<GoogleSlides>` deck cards.
+   *
+   * Default: `false`.
+   */
+  googleSlides?: boolean
+}
+
+/** Rewritten HTML plus every tag an enabled provider refused. */
+export interface JsMediaEmbedsResult {
+  html: string
+  diagnostics: Array<JsEmbedDiagnostic>
+}
+
+/** Opt-in `<NotByAI />` authorship badge. */
+export interface JsNotByAiOptions {
+  /**
+   * Enable `<NotByAI />` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Accessible label for the badge link.
+   *
+   * Default: `"Written by human, not by AI"`.
+   */
+  label?: string
+  /**
+   * Destination URL. Unsafe values fall back to `https://notbyai.fyi`.
+   *
+   * Default: `"https://notbyai.fyi"`.
+   */
+  href?: string
 }
 
 /** OG image configuration for JavaScript. */
@@ -1285,6 +1766,19 @@ export interface JsOgImageData {
   author?: string
 }
 
+/** One local OpenAPI file consumed by the generated docs pipeline. */
+export interface JsOpenApiDocsInput {
+  path: string
+  name?: string
+  failOnUnresolvedRefs?: boolean
+}
+
+/** Options shared by all OpenAPI docs inputs. */
+export interface JsOpenApiDocsOptions {
+  root?: string
+  basePath?: string
+}
+
 /** Per-page frontmatter chrome flags. */
 export interface JsPageChromeFlags {
   sidebar?: boolean
@@ -1306,6 +1800,31 @@ export interface JsPagerOverride {
   href?: string
 }
 
+/**
+ * A feed date after parsing: the instant, its civil parts in UTC, and the two
+ * serializations the feed formats ask for.
+ */
+export interface JsParsedFeedDate {
+  /** Seconds since the Unix epoch. */
+  unix: number
+  /** Civil year in UTC. */
+  year: number
+  /** Civil month, 1-12. */
+  month: number
+  /** Civil day of month, 1-31. */
+  day: number
+  /** Hour, 0-23. */
+  hour: number
+  /** Minute, 0-59. */
+  minute: number
+  /** Second, 0-60. */
+  second: number
+  /** `YYYY-MM-DDTHH:MM:SSZ`, as Atom and JSON Feed want it. */
+  rfc3339: string
+  /** `Day, DD Mon YYYY HH:MM:SS +0000`, as RSS wants it. */
+  rfc822: string
+}
+
 /**
  * Parser options for JavaScript.
  *
@@ -1356,6 +1875,34 @@ export interface JsParserOptions {
   autolinks?: boolean
 }
 
+/** Opt-in parameterized Markdown partials. */
+export interface JsPartialsOptions {
+  /**
+   * Enable `<!-- @partial: PATH k="v" -->` expansion.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Root directory used for `@/` and absolute partial paths.
+   *
+   * Default: project root from the JavaScript caller.
+   */
+  rootDir?: string
+  /**
+   * Directory used for bare partial names such as `install.md`.
+   *
+   * Default: `"_partials"`.
+   */
+  root?: string
+  /**
+   * Missing `{{ name }}` substitutions: `"literal"` (default) or `"error"`.
+   *
+   * Default: `"literal"`.
+   */
+  missing?: string
+}
+
 /** A block the native pass left for the caller's highlighter. */
 export interface JsPendingBlock {
   /** The `language-…` class the block carries. */
@@ -1422,12 +1969,63 @@ export interface JsReaderChrome {
   backToTop?: boolean
 }
 
+/** One planned static HTML redirect. */
+export interface JsRedirectEntry {
+  from: string
+  to: string
+  html: string
+  relativePath: string
+}
+
+/** One entry of the config rewrite map, in author order. */
+export interface JsRedirectMapEntry {
+  from: string
+  to: string
+}
+
+/** One page that other paths can redirect to. */
+export interface JsRedirectPage {
+  dest: string
+  aliases?: Array<string>
+  redirect?: string
+}
+
+/** Switches and the config rewrite map. */
+export interface JsRedirectsOptions {
+  enabled: boolean
+  map: Array<JsRedirectMapEntry>
+  netlify: boolean
+  headers: boolean
+  json: boolean
+  allowExternal: boolean
+  html: boolean
+  base?: string
+}
+
+/** Planned redirect pages and optional host files. */
+export interface JsRedirectsOutput {
+  pages: Array<JsRedirectEntry>
+  netlify?: string
+  headers?: string
+  json?: string
+}
+
 /** Resolved source module. */
 export interface JsResolvedModule {
   path: string
   exports: Array<JsPublicExport>
 }
 
+/** One page after cascade and optional permalink / slug rewriting. */
+export interface JsResolvedSsgRoutePage {
+  /** Source path relative to the content root. */
+  source: string
+  /** Resolved URL path. */
+  urlPath: string
+  /** Frontmatter after cascade fills. */
+  frontmatter: Record<string, unknown>
+}
+
 /** HTML sanitizer options. */
 export interface JsSanitizeOptions {
   /**
@@ -1486,6 +2084,8 @@ export interface JsSearchIndexBuildOptions {
   publishState?: JsPublishStateOptions
   /** Explicit MDX parser override. When omitted, `.mdx` files enable MDX. */
   mdx?: boolean
+  /** Conditional blocks are resolved before extracting searchable content. */
+  conditionalBlocks?: JsConditionalBlockOptions
 }
 
 /** Search options for JavaScript. */
@@ -1542,6 +2142,36 @@ export interface JsSectionIndexItem {
   description?: string
 }
 
+/** One page considered for the crawl manifests. */
+export interface JsSiteMapPage {
+  loc: string
+  title: string
+  description?: string
+  /** Source-file git commit time in milliseconds. `None` omits `<lastmod>`. */
+  lastUpdated?: number
+  draft?: boolean
+  unlisted?: boolean
+}
+
+/** Switches and site metadata for crawl-manifest generation. */
+export interface JsSiteMapsOptions {
+  enabled: boolean
+  siteUrl?: string
+  sitemapLoc: string
+  siteName: string
+  siteDescription?: string
+  robots: boolean
+  llms: boolean
+}
+
+/** Generated crawl-manifest bodies, or a warning when generation is skipped. */
+export interface JsSiteMapsOutput {
+  sitemapXml?: string
+  robotsTxt?: string
+  llmsTxt?: string
+  warning?: string
+}
+
 /** Custom social link for JavaScript. */
 export interface JsSocialLink {
   /** Icon label. */
@@ -1788,6 +2418,26 @@ export interface JsSsgPageData {
   robots?: string
   /** Frontmatter `canonical`. */
   canonical?: string
+  /** Companion `.md` URL when copy-as-markdown chrome is on. */
+  markdownSource?: string
+}
+
+/** Resolved page routes plus collision and rejection diagnostics. */
+export interface JsSsgPageRouteOutput {
+  /** Pages that still have a unique URL. */
+  pages: Array<JsResolvedSsgRoutePage>
+  /** Human-readable collision and rejection messages. */
+  errors: Array<string>
+}
+
+/** One page considered for cascade and permalink resolution. */
+export interface JsSsgRoutePageInput {
+  /** Source path relative to the content root. */
+  source: string
+  /** File-tree URL before permalink or slug rewriting. */
+  fileUrl: string
+  /** Parsed frontmatter object. */
+  frontmatter: Record<string, unknown>
 }
 
 /** Resolved SSG output and public route paths. */
@@ -1910,6 +2560,8 @@ export interface JsThemeColors {
 export interface JsThemeConfig {
   /** Progressive cross-document transitions for same-origin MPA navigation. */
   viewTransitions?: boolean
+  /** Circular reveal for a same-document theme change. `"circle"` opts in. */
+  toggleTransition?: string
   /** Right-hand "On this page" outline. Omitted and `false` hide it. */
   aside?: boolean
   /** Breadcrumb trail from the site root through sidebar ancestors. */
@@ -2012,6 +2664,40 @@ export interface JsThemeLayout {
   maxContentWidth?: string
 }
 
+/** Opt-in static `::: timeline` milestone lists. */
+export interface JsTimelineOptions {
+  /**
+   * Enable static timeline blocks.
+   *
+   * Default: `false`.
+   */
+  enabled?: boolean
+  /**
+   * Render timelines as ordered lists unless a block overrides it.
+   *
+   * Default: `true`.
+   */
+  ordered?: boolean
+  /**
+   * Validation mode for malformed dates.
+   *
+   * Default: `"error"`.
+   */
+  invalidDate?: string
+  /**
+   * Validation mode for unsupported item metadata.
+   *
+   * Default: `"error"`.
+   */
+  unknownMeta?: string
+  /**
+   * Validation mode for timeline blocks without items.
+   *
+   * Default: `"error"`.
+   */
+  empty?: string
+}
+
 /**
  * Transform options for JavaScript.
  *
@@ -2216,18 +2902,54 @@ export interface JsTransformOptions {
    * Default: disabled.
    */
   includes?: JsIncludeOptions
+  /**
+   * Opt-in parameterized Markdown partials via `<!-- @partial: PATH k="v" -->`.
+   *
+   * Default: disabled.
+   */
+  partials?: JsPartialsOptions
   /**
    * Opt-in `::: steps` ordered lists.
    *
    * Default: disabled.
    */
   steps?: JsStepsOptions
+  /**
+   * Opt-in `::: code-group` fence groups.
+   *
+   * Default: disabled.
+   */
+  codeGroups?: JsCodeGroupOptions
   /**
    * Opt-in `{badge:variant}` inline badges.
    *
    * Default: disabled.
    */
   badges?: JsBadgeOptions
+  /**
+   * Opt-in `<NotByAI />` authorship badge.
+   *
+   * Default: disabled.
+   */
+  notByAi?: JsNotByAiOptions
+  /**
+   * Opt-in `{kbd:...}` inline keyboard keys.
+   *
+   * Default: disabled.
+   */
+  keyboardKeys?: JsKeyboardKeysOptions
+  /**
+   * Opt-in abbreviation and glossary expansion.
+   *
+   * Default: disabled.
+   */
+  abbreviations?: JsAbbreviationsOptions
+  /**
+   * Opt-in PHP Markdown Extra / mdBook-style definition lists.
+   *
+   * Default: disabled.
+   */
+  definitionLists?: JsDefinitionListOptions
   /**
    * Opt-in `{link:...}` rich magic links.
    *
@@ -2240,6 +2962,24 @@ export interface JsTransformOptions {
    * Default: disabled.
    */
   images?: JsImageOptions
+  /**
+   * Opt-in static `::: gallery` image groups.
+   *
+   * Default: disabled.
+   */
+  imageGalleries?: JsImageGalleryOptions
+  /**
+   * Opt-in static `::: timeline` milestone lists.
+   *
+   * Default: disabled.
+   */
+  timelines?: JsTimelineOptions
+  /**
+   * Opt-in static `::: if` / `::: else` conditional blocks.
+   *
+   * Default: disabled.
+   */
+  conditionalBlocks?: JsConditionalBlockOptions
   /**
    * Opt-in `::: card` / `::: link-card` / `::: card-grid` blocks.
    *
@@ -2258,6 +2998,12 @@ export interface JsTransformOptions {
    * Default: disabled.
    */
   fileTree?: JsFileTreeOptions
+  /**
+   * Opt-in static `csv-table` / `json-table` fences.
+   *
+   * Default: disabled.
+   */
+  dataTables?: JsDataTableOptions
 }
 
 /** Type parameter documentation (`<T extends C = D>`) used by generated API docs. */
@@ -2359,6 +3105,15 @@ export interface MdxImportSpecifier {
   kind: 'default' | 'named' | 'namespace'
 }
 
+/**
+ * Every tag the media-embed transform can rewrite.
+ *
+ * A caller that pre-scans a document to decide whether to run the transform
+ * needs this list, and a hand-kept copy drifts — that is how `<CodeSandbox>`
+ * came to be skipped on a page containing nothing else.
+ */
+export declare function mediaEmbedTags(): Array<JsEmbedTag>
+
 /** Restores code block metadata after JavaScript-side syntax highlighting. */
 export declare function mergeHighlightedCodeBlocks(originalHtml: string, highlightedHtml: string): string
 
@@ -2383,6 +3138,9 @@ export interface Mf2ValidateResult {
 /** Every language name and alias the native highlighter answers to. */
 export declare function nativeHighlightLanguages(): Array<string>
 
+/** Strips a trailing slash except for `/`. Unsafe values return `None`. */
+export declare function normalizeRedirectPath(value: string): string | null
+
 /** Normalizes VitePress-specific frontmatter into ox-content's entry-page shape. */
 export declare function normalizeVitePressFrontmatter(frontmatter: any): any
 
@@ -2399,6 +3157,13 @@ export declare function parseAndRender(source: string, options?: JsParserOptions
 /** Parses Markdown and renders to HTML asynchronously (runs on worker thread). */
 export declare function parseAndRenderAsync(source: string, options?: JsParserOptions | undefined | null): Promise<unknown>
 
+/**
+ * Parses a feed date — an epoch seconds/milliseconds integer, or a civil
+ * date-time with an optional zone offset — returning `null` when the value
+ * names no instant.
+ */
+export declare function parseFeedDate(value?: string | undefined | null): JsParsedFeedDate | null
+
 /** Parses Markdown source into a raw mdast memory block for JavaScript-side deserialization. */
 export declare function parseMdastRaw(source: string, options?: JsParserOptions | undefined | null): Uint8Array
 
@@ -2421,6 +3186,9 @@ export declare function parseScopedSearchQuery(query: string): JsScopedSearchQue
  */
 export declare function parseTransferRaw(source: string, kind: string, options?: JsParserOptions | undefined | null): Uint8Array
 
+/** Plans redirect pages and host files without writing anything. */
+export declare function planRedirects(options: JsRedirectsOptions, pages: Array<JsRedirectPage>): JsRedirectsOutput
+
 /** Prepared Markdown source with parsed frontmatter. */
 export interface PreparedSourceResult {
   /** Markdown content after optional frontmatter removal. */
@@ -2442,7 +3210,13 @@ export declare function prepareSource(source: string, options?: JsSourceOptions
  */
 export declare function prepareSourceRaw(source: string, options?: JsSourceOptions | undefined | null): Uint8Array
 
-/** Renders an AST (provided as JSON) to HTML. */
+/**
+ * Renders an mdast (provided as JSON) to HTML.
+ *
+ * The counterpart to [`parse`]: a tree rewritten in JavaScript comes back
+ * through here and is rendered by the same renderer the original would
+ * have used.
+ */
 export declare function render(astJson: string): RenderResult
 
 /**
@@ -2456,6 +3230,9 @@ export declare function renderFrameworkComponentCode(html: string, target: strin
 /** Resolve Unhead-compatible page-head descriptors to HTML. */
 export declare function renderHead(inputJson: string): JsSsgHtmlResult
 
+/** Static HTML redirect body. `dest` is escaped; callers still validate it. */
+export declare function renderRedirectHtml(dest: string): string
+
 /** Render result containing the HTML output. */
 export interface RenderResult {
   /** The rendered HTML. */
@@ -2470,6 +3247,9 @@ export declare function renderSsgSectionIndex(title: string, items: Array<JsSect
 /** Resolves manual SSG navigation groups. */
 export declare function resolveSsgNavigationGroups(navigation: Array<JsSsgNavigationGroup>, base: string, extension: string): Array<JsSsgNavGroup>
 
+/** Resolves permalink / slug routes and `_index` frontmatter cascade. */
+export declare function resolveSsgPageRoutes(pages: Array<JsSsgRoutePageInput>, permalinksEnabled: boolean, cascadeEnabled: boolean): JsSsgPageRouteOutput
+
 /** Resolves all output and public route paths for an SSG page. */
 export declare function resolveSsgRoutePaths(inputPath: string, srcDir: string, outDir: string, base: string, extension: string, siteUrl?: string | undefined | null): JsSsgRoutePaths
 
@@ -2509,6 +3289,29 @@ export declare function transform(source: string, options?: JsTransformOptions |
 /** Transforms Markdown source asynchronously (runs on worker thread). */
 export declare function transformAsync(source: string, options?: JsTransformOptions | undefined | null): Promise<unknown>
 
+/** Numbers headings, figures, and tables, and links `@id` references to them. */
+export declare function transformCrossReferences(html: string, options: JsCrossReferencesOptions): JsCrossReferenceOutput
+
+/**
+ * Finishes a transform from an mdast a JavaScript `transformers` hook may
+ * have rewritten.
+ *
+ * `transformMdastRaw` produces the tree; this renders it and runs
+ * everything that follows rendering — HTML postprocessing, sanitization,
+ * the table of contents, and the MDX metadata — so a rewritten tree loses
+ * none of it. `frontmatterJson` is carried through untouched.
+ */
+export declare function transformFromMdast(astJson: string, frontmatterJson: string, options?: JsTransformOptions | undefined | null): TransformResult
+
+/**
+ * Runs a transform up to the point where the tree exists.
+ *
+ * The counterpart to `transformFromMdast`: frontmatter is parsed and the
+ * opt-in Markdown features are expanded, then the tree is handed over as
+ * JSON for a `transformers` hook to rewrite.
+ */
+export declare function transformMdast(source: string, options?: JsTransformOptions | undefined | null): JsMdastTransformResult
+
 /**
  * Transforms Markdown into a raw mdast transfer buffer.
  *
@@ -2517,9 +3320,11 @@ export declare function transformAsync(source: string, options?: JsTransformOpti
  */
 export declare function transformMdastRaw(source: string, options?: JsTransformOptions | undefined | null): Uint8Array
 
-/** Transform opt-in static media embed components in already-rendered HTML. */
 export declare function transformMediaEmbeds(html: string, options?: JsMediaEmbedsOptions | undefined | null): string
 
+/** Rewrites embeds and reports the tags no provider would render. */
+export declare function transformMediaEmbedsWithDiagnostics(html: string, options?: JsMediaEmbedsOptions | undefined | null): JsMediaEmbedsResult
+
 /** Transforms mermaid code blocks in HTML to rendered SVG diagrams. */
 export declare function transformMermaid(html: string, mmdcPath: string): MermaidTransformResult
 

package/index.js

@@ -171,11 +171,15 @@ module.exports.render = binding.render;
 module.exports.transform = binding.transform;
 module.exports.transformAsync = binding.transformAsync;
 module.exports.transformMdastRaw = binding.transformMdastRaw;
+module.exports.transformMdast = binding.transformMdast;
+module.exports.transformFromMdast = binding.transformFromMdast;
 module.exports.sanitizeHtml = binding.sanitizeHtml;
 module.exports.transformMediaEmbeds = binding.transformMediaEmbeds;
+module.exports.transformMediaEmbedsWithDiagnostics = binding.transformMediaEmbedsWithDiagnostics;
 module.exports.transformPmEmbeds = binding.transformPmEmbeds;
 module.exports.transformTabsEmbeds = binding.transformTabsEmbeds;
 module.exports.transformYoutubeEmbeds = binding.transformYoutubeEmbeds;
+module.exports.extractYoutubeVideoId = binding.extractYoutubeVideoId;
 module.exports.extractCodeBlocks = binding.extractCodeBlocks;
 module.exports.lintCodeBlocks = binding.lintCodeBlocks;
 module.exports.extractDocsTests = binding.extractDocsTests;
@@ -191,6 +195,7 @@ module.exports.generateDocsNavCode = binding.generateDocsNavCode;
 module.exports.collectDocsSourceFiles = binding.collectDocsSourceFiles;
 module.exports.generateDocsDataJson = binding.generateDocsDataJson;
 module.exports.generateDocsMarkdown = binding.generateDocsMarkdown;
+module.exports.generateOpenApiDocs = binding.generateOpenApiDocs;
 module.exports.writeGeneratedDocs = binding.writeGeneratedDocs;
 module.exports.buildCollectionManifest = binding.buildCollectionManifest;
 module.exports.mergeHighlightedCodeBlocks = binding.mergeHighlightedCodeBlocks;
@@ -210,6 +215,9 @@ module.exports.collectSearchMarkdownFiles = binding.collectSearchMarkdownFiles;
 module.exports.normalizeVitePressFrontmatter = binding.normalizeVitePressFrontmatter;
 module.exports.generateSsgHtml = binding.generateSsgHtml;
 module.exports.renderHead = binding.renderHead;
+module.exports.applySsgReaderChromeHtml = binding.applySsgReaderChromeHtml;
+module.exports.getSsgReaderChromeCss = binding.getSsgReaderChromeCss;
+module.exports.getSsgReaderChromeScript = binding.getSsgReaderChromeScript;
 module.exports.generateSsgBareHtml = binding.generateSsgBareHtml;
 module.exports.highlightCodeBlock = binding.highlightCodeBlock;
 module.exports.applyPendingHighlights = binding.applyPendingHighlights;
@@ -220,6 +228,7 @@ module.exports.nativeHighlightLanguages = binding.nativeHighlightLanguages;
 module.exports.generateSsgBarePage = binding.generateSsgBarePage;
 module.exports.getGitLastUpdated = binding.getGitLastUpdated;
 module.exports.getGitContributors = binding.getGitContributors;
+module.exports.resolveSsgPageRoutes = binding.resolveSsgPageRoutes;
 module.exports.resolveSsgRoutePaths = binding.resolveSsgRoutePaths;
 module.exports.getSsgOutputPath = binding.getSsgOutputPath;
 module.exports.getSsgUrlPath = binding.getSsgUrlPath;
@@ -242,4 +251,13 @@ module.exports.checkI18nProject = binding.checkI18nProject;
 module.exports.extractTranslationKeys = binding.extractTranslationKeys;
 module.exports.renderFrameworkComponentCode = binding.renderFrameworkComponentCode;
 module.exports.renderSsgSectionIndex = binding.renderSsgSectionIndex;
+module.exports.parseFeedDate = binding.parseFeedDate;
+module.exports.generateFeedBodies = binding.generateFeedBodies;
+module.exports.mediaEmbedTags = binding.mediaEmbedTags;
+module.exports.transformCrossReferences = binding.transformCrossReferences;
+module.exports.planRedirects = binding.planRedirects;
+module.exports.renderRedirectHtml = binding.renderRedirectHtml;
+module.exports.isSafeRedirectDest = binding.isSafeRedirectDest;
+module.exports.normalizeRedirectPath = binding.normalizeRedirectPath;
+module.exports.generateSiteMapBodies = binding.generateSiteMapBodies;
 module.exports.escapeSvelteMarkup = binding.escapeSvelteMarkup;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ox-content/napi",
-  "version": "3.0.0-alpha.9",
+  "version": "3.0.0-beta.0",
   "description": "Node.js bindings for Ox Content - High-performance Markdown parser",
   "keywords": [
     "markdown",
@@ -47,12 +47,12 @@
     ]
   },
   "optionalDependencies": {
-    "@ox-content/binding-darwin-x64": "3.0.0-alpha.9",
-    "@ox-content/binding-darwin-arm64": "3.0.0-alpha.9",
-    "@ox-content/binding-linux-x64-gnu": "3.0.0-alpha.9",
-    "@ox-content/binding-linux-x64-musl": "3.0.0-alpha.9",
-    "@ox-content/binding-linux-arm64-gnu": "3.0.0-alpha.9",
-    "@ox-content/binding-linux-arm64-musl": "3.0.0-alpha.9",
-    "@ox-content/binding-win32-x64-msvc": "3.0.0-alpha.9"
+    "@ox-content/binding-darwin-x64": "3.0.0-beta.0",
+    "@ox-content/binding-darwin-arm64": "3.0.0-beta.0",
+    "@ox-content/binding-linux-x64-gnu": "3.0.0-beta.0",
+    "@ox-content/binding-linux-x64-musl": "3.0.0-beta.0",
+    "@ox-content/binding-linux-arm64-gnu": "3.0.0-beta.0",
+    "@ox-content/binding-linux-arm64-musl": "3.0.0-beta.0",
+    "@ox-content/binding-win32-x64-msvc": "3.0.0-beta.0"
   }
 }