@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/context/WikiContext.d.ts

@@ -0,0 +1,404 @@
+/**
+ * WikiContext - Request-scoped context for wiki operations
+ *
+ * Provides a request-scoped container for all contextual information needed
+ * during page rendering, including the engine, current page, user, and
+ * request/response objects.
+ */
+import type { PermissionSubject } from '../managers/UserManager.js';
+import { BaseContext } from './BaseContext.js';
+import type { Request, Response } from 'express';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type PageManager from '../managers/PageManager.js';
+import type RenderingManager from '../managers/RenderingManager.js';
+import type PluginManager from '../managers/PluginManager.js';
+import type VariableManager from '../managers/VariableManager.js';
+import type PolicyInformationPoint from '../security/PolicyInformationPoint.js';
+import { type ThemeInfo } from '../managers/ThemeManager.js';
+import type { PageFrontmatter } from '../types/Page.js';
+/**
+ * Request information extracted from Express request
+ */
+export interface RequestInfo {
+    /** Accept-Language header */
+    acceptLanguage?: string;
+    /** User-Agent header */
+    userAgent?: string;
+    /** Client IP address */
+    clientIp?: string;
+    /** Referer header */
+    referer?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Parsed query-string parameters (e.g. `?page=2&sort=count-desc`) */
+    query?: Record<string, string>;
+}
+/**
+ * User preferences for date/time formatting, locale, etc.
+ */
+export interface UserPreferences {
+    /** User's preferred locale (e.g., 'en-US') */
+    locale?: string;
+    /** User's timezone (e.g., 'America/New_York') */
+    timezone?: string;
+    /** Date format preference (e.g., 'yyyy-MM-dd') */
+    dateFormat?: string;
+    /** Additional preferences */
+    [key: string]: unknown;
+}
+/**
+ * User context - session or authentication context
+ */
+export interface UserContext extends PermissionSubject {
+    /** User display name */
+    displayName?: string;
+    /** Alias for isAuthenticated (legacy templates) */
+    authenticated?: boolean;
+    /** User preferences for formatting, locale, etc. */
+    preferences?: UserPreferences;
+    /** Shorthand for preferences.locale */
+    locale?: string;
+    /** Shorthand for preferences.timezone */
+    timezone?: string;
+    /**
+     * A test account (#1805), from the account record. An attribute for the host
+     * and its add-ons to enforce their own rules from; no policy reads it.
+     */
+    isTest?: boolean;
+    /** Additional user context data */
+    [key: string]: unknown;
+}
+/**
+ * Theme context — active theme identity and user display preference
+ */
+export interface ThemeContext {
+    /** Active theme folder name (e.g. 'default', 'flatly') */
+    activeTheme: string;
+    /** Metadata from the active theme's theme.json */
+    themeInfo: ThemeInfo | null;
+    /** User's light/dark/system display preference */
+    displayTheme: string;
+}
+/**
+ * Page context for rendering
+ */
+export interface PageContext {
+    /** Name of the current page */
+    pageName: string | null;
+    /** User context/session */
+    userContext: UserContext | null;
+    /** Request information */
+    requestInfo: RequestInfo;
+    /** Theme context */
+    themeContext?: ThemeContext;
+    /** Page front matter metadata */
+    pageMetadata?: PageFrontmatter | null;
+}
+/**
+ * Options for MarkupParser.parse()
+ */
+export interface ParseOptions {
+    /** Page-specific context */
+    pageContext: PageContext;
+    /** Wiki engine instance */
+    engine: WikiEngine;
+    /**
+     * Optional reference to the parent WikiContext (#629). When present,
+     * ParseContext getters delegate user/page-data lookups to it instead of
+     * reading the constructor-time `pageContext` snapshot, keeping the
+     * WikiContext as the single source of truth across the parse run.
+     */
+    wikiContext?: unknown;
+}
+/**
+ * Options for WikiContext constructor
+ */
+export interface WikiContextOptions {
+    /** Context type (VIEW, EDIT, PREVIEW, etc.) */
+    context?: string;
+    /** Name of the page */
+    pageName?: string;
+    /** Page content (markdown) */
+    content?: string;
+    /** The caller's subject. Required (#1399) — see the constructor. */
+    userContext: UserContext;
+    /** Express request object */
+    request?: Request;
+    /** Express response object */
+    response?: Response;
+    /** Active theme folder name (e.g. 'default', 'flatly') */
+    activeTheme?: string;
+    /** Metadata from theme.json */
+    themeInfo?: ThemeInfo | null;
+    /** Page front matter metadata — must be set before ACL checks */
+    pageMetadata?: PageFrontmatter;
+}
+/**
+ * Context type constants
+ */
+export interface ContextTypes {
+    /** Viewing a page */
+    VIEW: 'view';
+    /** Editing a page */
+    EDIT: 'edit';
+    /** Previewing page changes */
+    PREVIEW: 'preview';
+    /** Viewing page diff */
+    DIFF: 'diff';
+    /** Viewing page information/metadata */
+    INFO: 'info';
+    /** No specific page context */
+    NONE: 'none';
+}
+/**
+ * WikiContext - Encapsulates the context of a single request or rendering operation
+ *
+ * Inspired by JSPWiki's WikiContext, this class provides a request-scoped container
+ * for all contextual information needed during page rendering, including the engine,
+ * current page, user, request/response objects, and manager references.
+ *
+ * @class WikiContext
+ *
+ * @property {WikiEngine} engine - The wiki engine instance
+ * @property {string} context - The rendering context (VIEW, EDIT, PREVIEW, etc.)
+ * @property {string|null} pageName - Name of the current page
+ * @property {string|null} content - Page content (markdown)
+ * @property {UserContext|null} userContext - Current user context/session
+ * @property {Request|null} request - Express request object
+ * @property {Response|null} response - Express response object
+ * @property {PageManager} pageManager - Reference to PageManager
+ * @property {RenderingManager} renderingManager - Reference to RenderingManager
+ * @property {PluginManager} pluginManager - Reference to PluginManager
+ * @property {VariableManager} variableManager - Reference to VariableManager
+ * @property {PolicyInformationPoint} policyInformationPoint - Reference to PolicyInformationPoint
+ * @property {MarkdownConverter} _fallbackConverter - Fallback markdown converter (#1273)
+ *
+ * @see {@link WikiEngine} for the main engine
+ * @see {@link RenderingManager} for rendering operations
+ */
+declare class WikiContext extends BaseContext {
+    /**
+     * Context type constants for different rendering modes
+     *
+     * @static
+     * @readonly
+     */
+    static readonly CONTEXT: ContextTypes;
+    /** The wiki engine instance */
+    readonly engine: WikiEngine;
+    /** The rendering context type */
+    readonly context: string;
+    /** Name of the current page */
+    readonly pageName: string | null;
+    /** Page content (markdown) */
+    readonly content: string | null;
+    /** Current user context/session */
+    /**
+     * The caller's subject, as the middleware wrote it.
+     *
+     * #1399: stored once, on BaseContext, and read here under the name the
+     * render path and the templates already use. A UserContext IS a
+     * PermissionSubject plus display-only extras, so this is a view of the same
+     * object — never a copy, which is what would drop `privateStoreHandle` and
+     * make a sealed page vanish for its owner (#1382, #1173).
+     */
+    get userContext(): UserContext;
+    /** Express request object */
+    readonly request: Request | null;
+    /** Express response object */
+    readonly response: Response | null;
+    /** Reference to PageManager */
+    readonly pageManager: PageManager;
+    /** Reference to RenderingManager */
+    readonly renderingManager: RenderingManager;
+    /** Reference to PluginManager */
+    readonly pluginManager: PluginManager;
+    /** Reference to VariableManager */
+    readonly variableManager: VariableManager;
+    /** Reference to PolicyInformationPoint */
+    readonly policyInformationPoint: PolicyInformationPoint;
+    /** Override passed via WikiContextOptions; bypasses the lazy resolver */
+    private readonly _activeThemeOverride?;
+    /** Override passed via WikiContextOptions; bypasses the lazy resolver */
+    private readonly _themeInfoOverride?;
+    /** Cached resolved activeTheme — populated on first read of `activeTheme` */
+    private _resolvedActiveTheme?;
+    /** Cached resolved themeInfo — populated on first read of `themeInfo` */
+    private _resolvedThemeInfo?;
+    /** Page front matter metadata — carries audience/access/user-keywords for ACL evaluation */
+    readonly pageMetadata: PageFrontmatter | null;
+    /** Fallback markdown converter */
+    private readonly _fallbackConverter;
+    /**
+     * Per-instance memoization for hasPermission(action) results (#636).
+     * The WikiContext is request-scoped, so this cache lifetime is the request.
+     * We cache the Promise (not the resolved value) so concurrent callers all
+     * await the same in-flight evaluation.
+     */
+    /**
+     * Per-instance memoization for canAccess(action) results, keyed by
+     * `${action}:${pageName}` to handle the rare case where a request mutates
+     * pageName mid-handler (#636).
+     */
+    private readonly _canAccessCache;
+    /**
+     * Creates a new WikiContext instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     * @param {WikiContextOptions} [options={}] - Context options
+     * @throws {Error} If engine is not provided
+     *
+     * @example
+     * const context = new WikiContext(engine, {
+     *   context: WikiContext.CONTEXT.VIEW,
+     *   pageName: 'Main',
+     *   userContext: req.session.user,
+     *   request: req,
+     *   response: res
+     * });
+     */
+    constructor(engine: WikiEngine, options: WikiContextOptions);
+    /**
+     * Returns the current rendering context type
+     *
+     * @returns {string} The context type (VIEW, EDIT, PREVIEW, etc.)
+     *
+     * @example
+     * if (context.getContext() === WikiContext.CONTEXT.EDIT) {
+     *   // Show edit-specific UI
+     * }
+     */
+    getContext(): string;
+    /**
+     * Static role check for callers that don't have a full WikiContext.
+     *
+     * Useful for hot-path middleware (maintenance gate, /metrics) that runs on
+     * every request and shouldn't pay the cost of constructing a WikiContext just
+     * to ask "is this user an admin?". Same semantics as the instance `hasRole`.
+     *
+     * @param userContext - userContext-like object (or null/undefined)
+     * @param names - Role names (matches if user has at least one)
+     * @returns true if userContext.roles contains any of the given names
+     *
+     * @example
+     * if (WikiContext.userHasRole(req.userContext, 'admin')) { ... }
+     */
+    static userHasRole(userContext: {
+        roles?: string[];
+    } | null | undefined, ...names: string[]): boolean;
+    /**
+     * Returns true if the current user is allowed to perform the given action
+     * on the current page — or on a different page when `pageNameOverride` is
+     * passed (#714 Slice B, the cross-page check used by linked-page visibility
+     * filters and serveAttachment's owning-page lookup).
+     *
+     * Delegates to {@link PolicyInformationPoint.checkPagePermissionWithContext} for the
+     * current page (the no-override fast path) and {@link PolicyInformationPoint.canUserAccessPage}
+     * for cross-page checks (#714 Slice B — loads the target page's metadata
+     * internally and runs the same evaluator).
+     *
+     * Returns false if the WikiContext has no pageName (and no override) or no
+     * PolicyInformationPoint.
+     *
+     * @param {string} action - Page action (e.g., 'view', 'edit', 'delete')
+     * @param {string} [pageNameOverride] - When set, check access on this page
+     *   instead of `this.pageName`. Used for cross-page checks (e.g., a private
+     *   attachment whose owning page is not the current request's page).
+     * @returns {Promise<boolean>} true if access is allowed
+     *
+     * @example
+     * if (await wikiContext.canAccess('edit')) { ... }
+     *
+     * @example
+     * // Cross-page check (Slice B): can the current user view the page that
+     * // owns this attachment? Used at WikiRoutes.serveAttachment to enforce
+     * // private-page access for attachments whose owning page is private.
+     * if (!(await wikiContext.canAccess('view', owningPageName))) {
+     *   return 403;
+     * }
+     */
+    canAccess(action: string, pageNameOverride?: string): Promise<boolean>;
+    /**
+     * Would the current user be allowed this action on the current page — asked
+     * only to decide whether to SHOW something (#1668): `<wiki:If
+     * hasPermission:edit>` hiding a block. An affordance, never a door.
+     *
+     * The same evaluator as {@link canAccess}'s same-page path, through
+     * {@link PolicyInformationPoint.pageAffordance}, so the two always agree; it
+     * writes no audit record. Hiding content is not an attempt, and asking the
+     * door here wrote an `authorization-deny` for every anonymous view of a page
+     * using the tag. Anything that then ACTS asks {@link canAccess}.
+     *
+     * @param action - Page action (e.g., 'view', 'edit')
+     * @returns true if the door would allow the action
+     */
+    mayShow(action: string): Promise<boolean>;
+    /**
+     * Active theme folder name (e.g. 'default', 'flatly').
+     *
+     * Lazy: resolves from ConfigurationManager on first access and caches the
+     * result. Permission-only callers (route handlers that just call hasRole /
+     * hasPermission) never trigger the lookup.
+     */
+    get activeTheme(): string;
+    /**
+     * Metadata from the active theme's theme.json.
+     *
+     * Lazy: triggers theme resolution on first access (uses the engine-wide
+     * `getThemeManager` cache). Returns the override if one was passed via
+     * WikiContextOptions.
+     */
+    get themeInfo(): ThemeInfo | null;
+    /**
+     * Returns the user's display theme preference ('light' | 'dark' | 'system')
+     * Derived from userContext.preferences['display.theme']; defaults to 'system'.
+     */
+    get displayTheme(): string;
+    /**
+     * Returns a ThemeContext snapshot for use in parse options and variable context
+     */
+    get themeContext(): ThemeContext;
+    /**
+     * Renders the provided markdown content through the full rendering pipeline
+     *
+     * This method uses the MarkupParser for advanced parsing with plugin support,
+     * variable expansion, and multi-phase processing. Falls back to plain markdown-it
+     * conversion if the parser is unavailable.
+     *
+     * @async
+     * @param {string} [content=this.content] - The markdown content to render
+     * @returns {Promise<string>} The rendered HTML
+     *
+     * @example
+     * const html = await context.renderMarkdown('# Hello World');
+     * // Returns: '<h1>Hello World</h1>'
+     *
+     * @example
+     * // With plugins and variables
+     * const html = await context.renderMarkdown('[{CurrentTimePlugin}]');
+     * // Returns expanded plugin output
+     */
+    renderMarkdown(content?: string | null): Promise<string>;
+    /**
+     * Creates the options object needed for the MarkupParser
+     *
+     * Builds a comprehensive options object containing page context, user context,
+     * request information, and engine reference for use during parsing.
+     *
+     * @returns {ParseOptions} Parse options object
+     *
+     * @example
+     * const options = context.toParseOptions();
+     * const html = await parser.parse(content, options);
+     */
+    toParseOptions(): ParseOptions;
+    /**
+     * Converts the current context to a VariableContext for variable expansion
+     *
+     * @returns {VariableContext} Variable context for use with VariableManager
+     * @private
+     */
+    private toVariableContext;
+}
+export default WikiContext;

package/lib/src/context/bootActions.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Boot actions — what the instance does to itself at start-up, attributed
+ * (#1197, #631, security-posture P1).
+ *
+ * Boot-time code runs with no request and therefore no actor. Most of it only
+ * wires — registers handlers, reads configuration, builds objects — and needs
+ * none. Some of it ACTS: the required-pages seed writes pages, the bootstrap
+ * admin is created, the delete-retention purge destroys pages, the session
+ * secret is written into `.env`. Those writes reached the audit trail with
+ * nobody attached, or did not reach it at all, because `AuditManager` is the
+ * last manager to initialise and the sink did not yet exist when they ran.
+ *
+ * Two things live here:
+ *
+ * - `systemContext(engine, reason)` — the `JobContext` an acting boot path
+ *   runs under: the system principal named in `.env` (#631), origin `boot`,
+ *   and a stated reason. A path that only wires never asks for one.
+ * - `recordSystemAction(engine, ctx, event)` — record an audit event under
+ *   that context. If the audit sink is up it records now; if not, the event
+ *   waits in the boot ledger and `AuditManager.initialize` drains it once the
+ *   sink exists. Either way the record names who (the principal), from where
+ *   (`origin`) and why (`reason`), so "the system did this" is a statement,
+ *   not a guess.
+ *
+ * The ledger is a module singleton on purpose: it is not a request identity
+ * (the thing the framework refuses to make ambient), it is a queue for a
+ * window in which there is nowhere else to put the record.
+ */
+import { type JobContext } from './JobContext.js';
+import { type AuditEvent, type AuditEventSink } from '../utils/auditEvents.js';
+type EngineLike = {
+    getManager: (name: string) => unknown;
+} | null | undefined;
+/** The system principal named in `.env` (#631), or the fallback where no UserManager answers. */
+export declare function systemPrincipalOf(engine: EngineLike): string;
+/** The context an acting boot path runs under. `reason` says what and why, for the record. */
+export declare function systemContext(engine: EngineLike, reason: string): JobContext;
+/** The same for a scheduled tick (#1196): origin `schedule`. */
+export declare function scheduleContext(engine: EngineLike, reason: string): JobContext;
+/** The audit fields a system context contributes: who, from where, why. */
+export declare function attributedTo(ctx: JobContext): {
+    user: string;
+    actor?: string;
+    ipAddress: string | undefined;
+    metadata: Record<string, unknown>;
+};
+export type SystemActionEvent = Omit<AuditEvent, 'user' | 'ipAddress'> & {
+    ipAddress?: undefined;
+};
+/**
+ * Record an action taken under a system context — now if the audit sink is
+ * up, otherwise into the boot ledger for `drainBootActions` to flush.
+ */
+export declare function recordSystemAction(engine: EngineLike, ctx: JobContext, event: SystemActionEvent): Promise<void>;
+/** Flush the boot ledger into the sink. Called once by `AuditManager.initialize`. Returns how many. */
+export declare function drainBootActions(sink: AuditEventSink): Promise<number>;
+/** What is waiting. For tests and diagnostics. */
+export declare function pendingBootActions(): ReadonlyArray<{
+    context: JobContext;
+    event: AuditEvent;
+}>;
+/** Empty the ledger without recording. For tests. */
+export declare function resetBootActions(): void;
+export {};

package/lib/src/context/bootActions.js

@@ -0,0 +1,111 @@
+/**
+ * Boot actions — what the instance does to itself at start-up, attributed
+ * (#1197, #631, security-posture P1).
+ *
+ * Boot-time code runs with no request and therefore no actor. Most of it only
+ * wires — registers handlers, reads configuration, builds objects — and needs
+ * none. Some of it ACTS: the required-pages seed writes pages, the bootstrap
+ * admin is created, the delete-retention purge destroys pages, the session
+ * secret is written into `.env`. Those writes reached the audit trail with
+ * nobody attached, or did not reach it at all, because `AuditManager` is the
+ * last manager to initialise and the sink did not yet exist when they ran.
+ *
+ * Two things live here:
+ *
+ * - `systemContext(engine, reason)` — the `JobContext` an acting boot path
+ *   runs under: the system principal named in `.env` (#631), origin `boot`,
+ *   and a stated reason. A path that only wires never asks for one.
+ * - `recordSystemAction(engine, ctx, event)` — record an audit event under
+ *   that context. If the audit sink is up it records now; if not, the event
+ *   waits in the boot ledger and `AuditManager.initialize` drains it once the
+ *   sink exists. Either way the record names who (the principal), from where
+ *   (`origin`) and why (`reason`), so "the system did this" is a statement,
+ *   not a guess.
+ *
+ * The ledger is a module singleton on purpose: it is not a request identity
+ * (the thing the framework refuses to make ambient), it is a queue for a
+ * window in which there is nowhere else to put the record.
+ */
+import { jobContextFromSystem, jobContextFromSchedule } from './JobContext.js';
+import { recordAuditEvent } from '../utils/auditEvents.js';
+import logger from '../utils/logger.js';
+import { proxyAttribution } from '../utils/proxyClaim.js';
+/** The name a booted instance carries when no principal can be resolved — only reachable in fixtures. */
+const FALLBACK_PRINCIPAL = 'system';
+/** The system principal named in `.env` (#631), or the fallback where no UserManager answers. */
+export function systemPrincipalOf(engine) {
+    // #1431 step 13: the subject's attributes, the system principal among them, are the PIP's.
+    const pip = engine?.getManager('PolicyInformationPoint');
+    try {
+        return pip?.systemPrincipalName?.() ?? FALLBACK_PRINCIPAL;
+    }
+    catch {
+        return FALLBACK_PRINCIPAL;
+    }
+}
+/** The context an acting boot path runs under. `reason` says what and why, for the record. */
+export function systemContext(engine, reason) {
+    return jobContextFromSystem(systemPrincipalOf(engine), reason);
+}
+/** The same for a scheduled tick (#1196): origin `schedule`. */
+export function scheduleContext(engine, reason) {
+    return jobContextFromSchedule(systemPrincipalOf(engine), reason);
+}
+/** The audit fields a system context contributes: who, from where, why. */
+export function attributedTo(ctx) {
+    // #1762 slice 3: work queued under a proxy grant names the person who
+    // queued it, as the request itself would have.
+    const { metadata: proxyMeta, ...proxy } = proxyAttribution(ctx.viaProxy);
+    return {
+        user: ctx.username,
+        ...proxy,
+        ipAddress: ctx.ipAddress || undefined,
+        metadata: {
+            origin: ctx.origin,
+            reason: ctx.reason ?? null,
+            requestedAt: ctx.requestedAt,
+            ...proxyMeta
+        }
+    };
+}
+const ledger = [];
+function stamp(ctx, event) {
+    const who = attributedTo(ctx);
+    return {
+        ...event,
+        ...who,
+        ipAddress: undefined,
+        metadata: { ...who.metadata, ...(event.metadata ?? {}) }
+    };
+}
+/**
+ * Record an action taken under a system context — now if the audit sink is
+ * up, otherwise into the boot ledger for `drainBootActions` to flush.
+ */
+export async function recordSystemAction(engine, ctx, event) {
+    const stamped = stamp(ctx, event);
+    const sink = engine?.getManager('AuditManager');
+    if (sink && typeof sink.logAuditEvent === 'function') {
+        await recordAuditEvent(sink, stamped, (err) => logger.warn(`[bootActions] Audit record failed for ${stamped.eventType} (${ctx.reason ?? 'no reason'}): ${String(err)}`));
+        return;
+    }
+    ledger.push({ context: ctx, event: stamped });
+}
+/** Flush the boot ledger into the sink. Called once by `AuditManager.initialize`. Returns how many. */
+export async function drainBootActions(sink) {
+    const pending = ledger.splice(0, ledger.length);
+    for (const { context, event } of pending) {
+        await recordAuditEvent(sink, event, (err) => logger.warn(`[bootActions] Deferred audit record failed for ${event.eventType} (${context.reason ?? 'no reason'}): ${String(err)}`));
+    }
+    if (pending.length > 0)
+        logger.info(`[bootActions] Recorded ${pending.length} boot-time action(s) deferred until the audit sink was up`);
+    return pending.length;
+}
+/** What is waiting. For tests and diagnostics. */
+export function pendingBootActions() {
+    return ledger;
+}
+/** Empty the ledger without recording. For tests. */
+export function resetBootActions() {
+    ledger.length = 0;
+}

package/lib/src/converters/HtmlConverter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * HTML to Markdown Converter
+ *
+ * Converts HTML web pages to Markdown for import into ngdpbase.
+ * Uses linkedom for DOM parsing/content extraction and turndown for HTML-to-Markdown conversion.
+ * Extracts metadata from HTML head, meta tags, Open Graph, and Schema.org markup.
+ *
+ * @module HtmlConverter
+ */
+import { IContentConverter, ConversionResult } from './IContentConverter.js';
+/**
+ * HTML to Markdown converter
+ *
+ * Implements IContentConverter for importing web pages as wiki pages.
+ * Extracts the primary article content, strips boilerplate, and converts to Markdown.
+ */
+declare class HtmlConverter implements IContentConverter {
+    readonly formatId = "html";
+    readonly formatName = "HTML Web Page";
+    readonly fileExtensions: string[];
+    private turndown;
+    constructor();
+    /**
+     * Convert HTML content to Markdown
+     *
+     * @param content - Raw HTML string
+     * @returns ConversionResult with Markdown content, metadata, and warnings
+     */
+    convert(content: string): ConversionResult;
+    /**
+     * Check if this converter can handle the given content
+     */
+    canHandle(content: string, filename: string): boolean;
+    /**
+     * Extract metadata from HTML head and Schema.org markup
+     */
+    private extractMetadata;
+    /**
+     * Get content of a meta tag by name or property
+     */
+    private getMetaContent;
+    /**
+     * Extract Schema.org JSON-LD data if present
+     */
+    private extractJsonLd;
+    /**
+     * Remove unwanted elements from the document
+     */
+    private removeElements;
+    /**
+     * Extract the primary content from the document
+     * Tries article, main, [role=main], .content, then falls back to body
+     */
+    private extractContent;
+    /**
+     * Convert a numbered references section into Markdown footnote definitions.
+     *
+     * Detects patterns like:
+     *   ## References
+     *   1.  [url](url)
+     *   2.  [url](url)
+     *
+     * And converts to:
+     *   ----
+     *   [^1]: url
+     *   [^2]: url
+     */
+    private convertReferencesToFootnotes;
+}
+export default HtmlConverter;