@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/parsers/MarkupParser.d.ts

@@ -0,0 +1,769 @@
+import BaseManager from '../managers/BaseManager.js';
+import { HandlerRegistry } from './handlers/HandlerRegistry.js';
+import BaseSyntaxHandler from './handlers/BaseSyntaxHandler.js';
+import FilterChain from './filters/FilterChain.js';
+import { DOMParser as WikiDOMParser } from './dom/DOMParser.js';
+import DOMVariableHandler from './dom/handlers/DOMVariableHandler.js';
+import DOMPluginHandler from './dom/handlers/DOMPluginHandler.js';
+import DOMLinkHandler from './dom/handlers/DOMLinkHandler.js';
+import ParseContext from './context/ParseContext.js';
+import WikiDocument from './dom/WikiDocument.js';
+import type RegionCache from '../cache/RegionCache.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/** Configuration for MarkupParser */
+export interface MarkupParserConfig extends Record<string, unknown> {
+    /** Whether MarkupParser is enabled */
+    enabled: boolean;
+    /** Whether caching is enabled */
+    caching: boolean;
+    /** Cache TTL in seconds */
+    cacheTTL: number;
+    /** Handler registry configuration */
+    handlerRegistry: HandlerRegistryConfig;
+    /** Handler configurations */
+    handlers: Record<string, HandlerConfig>;
+    /** Cache configuration */
+    cache: CacheConfig;
+    /** Performance configuration */
+    performance: PerformanceConfig;
+    /** Emoji shortcode conversion */
+    emoji?: {
+        enabled: boolean;
+    };
+}
+/** Handler registry configuration */
+export interface HandlerRegistryConfig {
+    /** Whether to enable dependency resolution */
+    enableDependencyResolution?: boolean;
+    /** Maximum handler priority */
+    maxPriority?: number;
+    /** Maximum number of handlers */
+    maxHandlers?: number;
+    /** Whether to allow duplicate priorities */
+    allowDuplicatePriorities?: boolean;
+    /** Whether to enable conflict detection */
+    enableConflictDetection?: boolean;
+    /** Default handler timeout in ms */
+    defaultTimeout?: number;
+}
+/** Individual handler configuration */
+export interface HandlerConfig {
+    /** Whether handler is enabled */
+    enabled: boolean;
+    /** Handler priority */
+    priority: number;
+}
+/** Cache configuration */
+export interface CacheConfig {
+    /** Parse results cache strategy */
+    parseResults: CacheStrategyConfig;
+    /** Whether to enable metrics */
+    metricsEnabled: boolean;
+}
+/** Cache strategy configuration */
+export interface CacheStrategyConfig {
+    /** Whether this strategy is enabled */
+    enabled: boolean;
+    /** Time to live in seconds */
+    ttl: number;
+    /** Maximum cache size */
+    maxSize: number;
+}
+/** Performance configuration */
+export interface PerformanceConfig {
+    /** Whether performance monitoring is enabled */
+    monitoring: boolean;
+    /** Alert thresholds */
+    alertThresholds: AlertThresholds;
+}
+/** Performance alert thresholds */
+export interface AlertThresholds {
+    /** Parse time threshold in milliseconds */
+    parseTime: number;
+    /** Cache hit ratio threshold (0-1) */
+    cacheHitRatio: number;
+    /** Error rate threshold (0-1) */
+    errorRate: number;
+    /** Minimum cache samples for metrics */
+    minCacheSamples: number;
+}
+/** Parse context */
+export interface ParseContextData {
+    /** Page name */
+    pageName?: string;
+    /** User name */
+    userName?: string;
+    /** User context object */
+    userContext?: unknown;
+    /** Request information */
+    requestInfo?: unknown;
+    /** Code blocks extracted during parsing */
+    codeBlocks?: string[];
+    /** Protected HTML blocks */
+    protectedBlocks?: string[];
+    /** Syntax tokens */
+    syntaxTokens?: unknown[];
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/** Extracted JSPWiki element */
+export interface ExtractedElement {
+    /** Element type */
+    type: 'variable' | 'plugin' | 'link' | 'escaped' | 'style' | 'inline-style' | 'footnote-ref' | 'footnote-def' | 'code' | 'fenced-code';
+    /** Original syntax */
+    syntax: string;
+    /** Unique ID */
+    id: number;
+    /** Position in content */
+    position?: number;
+    /** Variable name (for variables) */
+    varName?: string;
+    /** Plugin/tag inner content (for plugins) */
+    inner?: string;
+    /** Link target (for links) */
+    target?: string;
+    /** Escaped literal content (for escaped) */
+    literal?: string;
+    /** CSS class name (for style blocks) */
+    className?: string;
+    /** Style block content (for style blocks) */
+    styleContent?: string;
+    /** Accumulated CSS classes from parent style blocks (for nested styles) */
+    accumulatedClasses?: string[];
+    /** Footnote identifier — the id portion of [^id] or [^id]: text */
+    footnoteId?: string;
+    /** Footnote definition text — the content after [^id]: */
+    footnoteText?: string;
+    /** Raw text content for inline code spans (`...`) and fenced code blocks (```...```) */
+    codeContent?: string;
+    /** Language tag from fenced code blocks (e.g. 'javascript' from ```javascript) */
+    codeLanguage?: string;
+    /** #907: inline-style variant — css | sup | sub | strike | class (#938) */
+    inlineVariant?: 'css' | 'sup' | 'sub' | 'strike' | 'class';
+    /** #907: raw CSS declarations for inline-style variant 'css' (parenthesis body) */
+    cssRaw?: string;
+    /** #938: space-separated class list for inline-style variant 'class' */
+    classNames?: string;
+}
+/** Result of extraction */
+export interface ExtractionResult {
+    /** Sanitized content with placeholders */
+    sanitized: string;
+    /** Extracted JSPWiki elements */
+    jspwikiElements: ExtractedElement[];
+    /** Unique UUID for this extraction */
+    uuid: string;
+}
+/** Parser metrics */
+export interface ParserMetrics {
+    /** Number of parses performed */
+    parseCount: number;
+    /** Total parse time in milliseconds */
+    totalParseTime: number;
+    /** Number of errors */
+    errorCount: number;
+    /** Number of cache hits */
+    cacheHits: number;
+    /** Number of cache misses */
+    cacheMisses: number;
+    /** Cache metrics by strategy */
+    cacheMetrics: Map<string, CacheMetrics>;
+}
+/** Cache metrics for a strategy */
+export interface CacheMetrics {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of cache sets */
+    sets: number;
+}
+/** Performance monitor state */
+export interface PerformanceMonitor {
+    /** Performance alerts */
+    alerts: PerformanceAlert[];
+    /** Last check timestamp */
+    lastCheck: number;
+    /** Check interval in milliseconds */
+    checkInterval: number;
+    /** Recent parse times */
+    recentParseTimes: ParseTimeEntry[];
+    /** Recent error rates */
+    recentErrorRates: number[];
+    /** Maximum recent entries to keep */
+    maxRecentEntries: number;
+}
+/** Performance alert */
+export interface PerformanceAlert {
+    /** Alert type */
+    type: string;
+    /** Alert message */
+    message: string;
+    /** Timestamp */
+    timestamp: string;
+    /** Related metrics */
+    metrics: unknown;
+}
+/** Parse time entry */
+export interface ParseTimeEntry {
+    /** Parse time in milliseconds */
+    time: number;
+    /** Whether this was a cache hit */
+    cacheHit: boolean;
+    /** Timestamp */
+    timestamp: number;
+}
+/** Extended metrics returned by getMetrics() */
+export interface ExtendedMetrics extends ParserMetrics {
+    /** Average parse time */
+    averageParseTime: number;
+    /** Cache hit ratio */
+    cacheHitRatio: number;
+    /** Handler registry stats */
+    handlerRegistry?: unknown;
+    /** Filter chain stats */
+    filterChain?: unknown;
+    /** Cache strategies stats */
+    cacheStrategies?: Record<string, unknown>;
+    /** Performance monitoring stats */
+    performance?: unknown;
+}
+declare class MarkupParser extends BaseManager {
+    /** Handler registry for syntax handlers */
+    handlerRegistry: HandlerRegistry;
+    /** Content filter chain */
+    filterChain: FilterChain | null;
+    /** Parse result cache */
+    cache: RegionCache | null;
+    /** Caching strategies by content type */
+    cacheStrategies: Record<string, RegionCache>;
+    /** Performance monitoring state */
+    performanceMonitor: PerformanceMonitor | null;
+    /** Parser performance metrics */
+    metrics: ParserMetrics;
+    /** DOM-based parser for JSPWiki syntax */
+    domParser: WikiDOMParser;
+    /** Variable expansion handler */
+    domVariableHandler: DOMVariableHandler;
+    /** Plugin execution handler */
+    domPluginHandler: DOMPluginHandler;
+    /** Link resolution handler */
+    domLinkHandler: DOMLinkHandler;
+    /** Parser configuration - overrides BaseManager's generic config */
+    protected config: MarkupParserConfig;
+    /**
+     * Creates a new MarkupParser instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the MarkupParser
+     */
+    initialize(config?: Partial<MarkupParserConfig>): Promise<void>;
+    /**
+     * Check if MarkupParser is initialized (required for RenderingManager integration)
+     * @returns {boolean} - True if initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Register default syntax handlers based on configuration
+     */
+    registerDefaultHandlers(): Promise<void>;
+    /**
+     * Load configuration from ConfigurationManager
+     */
+    loadConfiguration(): void;
+    /**
+     * Configure handler registry with loaded configuration
+     * NOTE: Removed - HandlerRegistry.config is private, no public setter available.
+     * HandlerRegistry uses default configuration which is sufficient.
+     */
+    /**
+     * Initialize advanced caching integration with multiple cache strategies
+     */
+    initializeAdvancedCaching(): Promise<void>;
+    /**
+     * Initialize performance monitoring system
+     */
+    initializePerformanceMonitoring(): void;
+    /** The configured `ngdpbase.markup.html-policy`, read when it is needed (#1623). */
+    private configuredHtmlPolicy;
+    /**
+     * Main parsing method - uses WikiDocument DOM extraction pipeline
+     * @param content - Raw content to parse
+     * @param context - Parsing context (page, user, etc.)
+     * @returns Processed HTML content
+     */
+    parse(content: string, context?: Record<string, unknown>): Promise<string>;
+    /**
+     * Render without the page cache: expand the template variables, run the
+     * extraction pipeline, record the timing. #1751 split this out of parse()
+     * so the read-through calls it; parse() still owns the error fallback.
+     */
+    private renderUncached;
+    /**
+     * Register a syntax handler
+     * @param handler - Handler instance
+     * @param options - Registration options
+     * @returns True if registration successful
+     */
+    registerHandler(handler: BaseSyntaxHandler, options?: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Get handler type from handler ID for configuration lookup (modular mapping)
+     * @param handlerId - Handler ID
+     * @returns Handler type or null
+     */
+    getHandlerTypeFromId(handlerId: string): string | null;
+    /**
+     * Get configuration for a specific handler type
+     * @param handlerType - Handler type (plugin, wikitag, etc.)
+     * @returns Handler configuration
+     */
+    getHandlerConfig(handlerType: string): HandlerConfig;
+    /**
+     * Unregister a syntax handler
+     * @param handlerId - Handler identifier
+     * @returns True if unregistration successful
+     */
+    unregisterHandler(handlerId: string): Promise<boolean>;
+    /**
+     * Get handler by ID
+     * @param handlerId - Handler identifier
+     * @returns Handler or null if not found
+     */
+    getHandler(handlerId: string): unknown;
+    /**
+     * Get all handlers sorted by priority
+     * @param enabledOnly - Only return enabled handlers
+     * @returns Handlers sorted by priority
+     */
+    getHandlers(enabledOnly?: boolean): unknown[];
+    /**
+     * Get the FilterChain (#596), which FilterManager owns (#1117).
+     *
+     * A delegating view kept for existing callers (the admin stats route,
+     * legacy save-path lookups). New code should ask FilterManager directly.
+     * Returns null when the pipeline is disabled or the manager is absent —
+     * callers should treat a null chain as "validation skipped, proceed".
+     *
+     * @returns The FilterChain instance, or null
+     */
+    getFilterChain(): FilterChain | null;
+    /**
+     * Enable handler by ID
+     * @param handlerId - Handler identifier
+     * @returns True if successful
+     */
+    enableHandler(handlerId: string): boolean;
+    /**
+     * Disable handler by ID
+     * @param handlerId - Handler identifier
+     * @returns True if successful
+     */
+    disableHandler(handlerId: string): boolean;
+    /**
+     * Generate cache key for content and context
+     * @param content - Content to cache
+     * @param context - Parse context
+     * @returns Cache key
+     */
+    /**
+     * #907: sanitize a raw inline-CSS declaration string against the security
+     * config. Returns validated `prop: val; …` (empty when disabled or nothing
+     * passes). Shared by the DOM inline-style node builder.
+     *
+     * Gate: `ngdpbase.style.security.allow-inline-css`. Each property must be in
+     * `ngdpbase.style.security.allowed-properties`; values with `javascript:`,
+     * `url(`, `expression(`, or angle brackets are dropped.
+     */
+    private sanitizeInlineCss;
+    /**
+     * #907: build a DOM node for an inline JSPWiki style — the unified path that
+     * replaced the Step 0.55 string replacements. `variant` selects the wrapper
+     * (`css` → `<span style>`, `sup` → `<sup>`, `sub` → `<sub>`, `strike` →
+     * `<del>`); `inner` is resolved for wiki syntax via appendWikiNodes (parity
+     * with block styles). For `css` with inline CSS disabled or no safe
+     * declarations, the wrapper degrades to a plain `<span>` (content preserved,
+     * never leaked as literal markup). Used by BOTH the top-level extraction
+     * resolver and the cell/block scanner (appendWikiNodes).
+     */
+    private buildInlineStyleNode;
+    /**
+     * Whether this parse may be cached in a map the whole process shares
+     * (#1423). A page in an encrypted store resolves only through its owner's
+     * unlocked session, so `PageManager.isSharedIndexable` — the same question
+     * #1419 asks of the search index and the link graph — answers false for it.
+     *
+     * A parse with no page name behind it (a preview, a snippet, an addon
+     * rendering a string) is cacheable as before: there is no page to be sealed.
+     */
+    private isSharedIndexable;
+    /**
+     * What a `[store/Title]` link on THIS page is resolved against (#1457):
+     * the private titles the reader can see in the page owner's stores.
+     *
+     * Only on a private page. Its HTML is never cached for sharing — the same
+     * `isSharedIndexable` question above is false for every private name — so
+     * its links may be answered for the reader in front of them, and the owner
+     * of a page that is not there gets a red link to its editor. A public page's
+     * render is shared by role and keeps one appearance for everyone (operator,
+     * 2026-09-23).
+     *
+     * One lookup per render, as the reader — the context as it arrived, never
+     * rebuilt and never defaulted. With no reader, no page manager, or a lookup
+     * that throws there is no answer, and every link stays neutral rather than
+     * claiming a page is missing.
+     */
+    private resolvePrivateLinkTitles;
+    generateCacheKey(content: string, context: ParseContextData): string;
+    /**
+     * Extract style blocks using state-stack parsing for proper nesting support
+     *
+     * Uses JSPWiki-style state tracking:
+     * - When %%class-name found: push to stack with accumulated classes from parents
+     * - When /% found: pop from stack, create element with all accumulated classes
+     *
+     * @param content - Content to extract style blocks from
+     * @param elements - Array to push extracted elements into
+     * @param uuid - UUID for placeholders
+     * @param startId - Starting ID for elements
+     * @returns Object with processed content and next available ID
+     */
+    private extractStyleBlocksWithStack;
+    /**
+     * Extract JSPWiki-specific syntax from content for DOM-based processing
+     *
+     * This method implements the pre-extraction strategy from Issue #114.
+     * Instead of tokenizing both markdown and JSPWiki syntax (which causes conflicts),
+     * we extract ONLY JSPWiki syntax and let markdown-it handle all markdown.
+     *
+     * Extraction order:
+     * 1. Variables: [{$username}] → __JSPWIKI_uuid_0__
+     * 2. Plugins: [{TableOfContents}] → __JSPWIKI_uuid_1__
+     * 3. Escaped: [[{$var}] → __JSPWIKI_uuid_2__ (stores literal [{$var}])
+     * 4. Wiki links: [PageName] → __JSPWIKI_uuid_3__ (but not markdown [text](url))
+     *
+     * Code blocks are already protected by Phase 1 preprocessing, so JSPWiki syntax
+     * inside code blocks won't be extracted.
+     *
+     * @param {string} content - Raw wiki content
+     * @param {ParseContext} context - Parse context (for code block protection)
+     * @returns {Object} - { sanitized, jspwikiElements, uuid }
+     *
+     * Related: #114 (WikiDocument DOM Solution), #115 (Phase 1 Implementation)
+     *
+     * @example
+     * const input = "## Heading\n\nUser: [{$username}]";
+     * const { sanitized, jspwikiElements, uuid } = parser.extractJSPWikiSyntax(input);
+     * // sanitized: "## Heading\n\nUser: <span data-jspwiki-placeholder="abc123-0"></span>"
+     * // jspwikiElements: [{ type: 'variable', varName: '$username', id: 0, ... }]
+     * // uuid: "abc123"
+     */
+    extractJSPWikiSyntax(content: string, _context?: Record<string, unknown>): {
+        sanitized: string;
+        jspwikiElements: ExtractedElement[];
+        uuid: string;
+    };
+    /**
+     * Creates a text node for escaped JSPWiki syntax
+     *
+     * This is a helper method for Phase 2 DOM node creation (Issue #116).
+     * Escaped syntax like [[{$var}]] should render as literal text [{$var}].
+     *
+     * @param element - Extracted escaped element
+     * @param wikiDocument - WikiDocument to create node in
+     * @returns DOM node containing the escaped literal text
+     *
+     * @example
+     * const element = { type: 'escaped', literal: '[{$username}]', id: 0, ... };
+     * const node = createTextNodeForEscaped(element, wikiDoc);
+     * // Returns: <span class="wiki-escaped" data-jspwiki-id="0">[{$username}]</span>
+     */
+    createTextNodeForEscaped(element: ExtractedElement, wikiDocument: WikiDocument): unknown;
+    /**
+     * #1368: when `node`'s only content is one `<p>`, replace the `<p>` with its
+     * children. Leaves anything else — several paragraphs, a list, text beside
+     * the paragraph — as it is.
+     */
+    private static unwrapSoleParagraph;
+    /**
+     * Creates a DOM node from a JSPWiki style block (%%class-name ... /%)
+     *
+     * This handles table-related style classes (table-striped, sortable, etc.)
+     * by parsing JSPWiki table syntax and creating HTML tables with proper styling.
+     * For non-table styles, wraps content in a styled div/span.
+     *
+     * @param element - Extracted style element
+     * @param context - Rendering context
+     * @param wikiDocument - WikiDocument to create node in
+     * @returns DOM node for the styled content
+     *
+     * @example
+     * // For table styles:
+     * const element = { type: 'style', className: 'table-striped', styleContent: '|| H1 ||\n| D1 |' };
+     * const node = createNodeFromStyleBlock(element, context, wikiDoc);
+     * // Returns: <table class="table table-striped">...</table>
+     */
+    createNodeFromStyleBlock(element: ExtractedElement, context: ParseContext, wikiDocument: WikiDocument): Promise<unknown>;
+    /**
+     * Creates an HTML table node from JSPWiki table syntax
+     *
+     * @param content - JSPWiki table content (|| header || and | cell | syntax)
+     * @param className - CSS class to apply (e.g., 'table-striped')
+     * @param elementId - Element ID for tracking
+     * @param wikiDocument - WikiDocument to create node in
+     * @returns HTML table element
+     */
+    /**
+     * Named HTML entities decoded inside DOM-built inner text (#907 follow-up).
+     * Authors write `&nbsp;`, `&copy;`, etc. as raw entities in wiki source; when
+     * that text becomes a real DOM text node its `&` would otherwise serialize to
+     * `&amp;` and the literal `&nbsp;` would show. Decoding to the actual char
+     * makes serialization round-trip correctly. Kept small on purpose — the
+     * common set; numeric `&#…;`/`&#x…;` are handled generically.
+     */
+    private static readonly NAMED_ENTITIES;
+    /**
+     * Decode a small set of named + all numeric HTML entities in plain text.
+     * Single pass, so a double-encoded `&amp;nbsp;` decodes only its outer `&amp;`
+     * (never double-decodes). Text nodes re-escape on serialization, so this is
+     * display-idempotent and cannot introduce markup. Code spans are NOT run
+     * through this — literal `&nbsp;` in backticks stays literal.
+     */
+    private decodeTextEntities;
+    /**
+     * Scans `content` for all JSPWiki wiki syntax (mirrors Steps 1–4 of extractJSPWikiSyntax)
+     * and appends the resolved child nodes directly to `node`. Text between matches is appended
+     * as text nodes. Used by createNodeFromStyleBlock and populateCell (via createTableNode).
+     *
+     * @param content  - Raw cell/block text containing wiki syntax
+     * @param node     - Target element to append children to
+     * @param context  - ParseContext for variable/plugin resolution
+     * @param wikiDocument - WikiDocument for node creation
+     * @param idStart  - Starting ID for created elements (must not collide with outer IDs)
+     */
+    /**
+     * Append `text` to `node` with the inline Markdown rules applied and its
+     * HTML escaped (#1351) — `renderInlineMarkdown`, parsed into nodes. Text
+     * with nothing to render goes in as a plain text node.
+     */
+    private appendInlineMarkdown;
+    private appendWikiNodes;
+    /**
+     * Build the DOM node for one wikiPattern match — the shared body of
+     * appendWikiNodes and appendMarkdownBlockNodes, so both resolve wiki syntax
+     * identically. Always returns a node; the literal cases return a text node.
+     */
+    private createWikiNodeFromMatch;
+    /**
+     * Is this style block a raw code/CSS dump rather than prose? (#1039)
+     *
+     * These must NOT go through the markdown pass. `%%add-css` is JSPWiki's
+     * convention for a stylesheet, and running markdown-it over CSS corrupts it:
+     * a CSS comment's asterisks read as emphasis markers, so a comment around the
+     * word `pagination.less` rendered as `/<em>pagination.less</em>/` on nine CSS
+     * documentation pages. Those pages exist to show the CSS accurately, so that
+     * is a real defect rather than a cosmetic one.
+     *
+     * Two signals, both cheap: the class name, and a CSS comment anywhere in the
+     * content (which catches a stylesheet pasted into a differently-named block).
+     * Checked against the full corpus — every mangled block matched, and no block
+     * containing real markdown did.
+     */
+    private static isRawCodeBlock;
+    /** `&`, `<`, `>` only — enough to keep source text inert through markdown-it. */
+    private escapeForMarkdown;
+    /**
+     * Resolve a style block's BLOCK content with both the wiki pass and the
+     * markdown pass (#1039).
+     *
+     * Style-block content is lifted out at Step 0.5, before markdown-it runs on the
+     * document, and was then handed to appendWikiNodes — which resolves wiki
+     * syntax and emits everything else as text nodes. So markdown inside a block
+     * reached the reader as literal source: `## Introduction` displayed its own
+     * hashes, and `**bold**` its own asterisks, while the identical markup one
+     * line outside the block rendered normally. 12 pages were affected.
+     *
+     * Raw HTML worked in there by accident, which is why it went unnoticed — an
+     * author who reached for `<br>` got a line break and had no reason to suspect
+     * the block was inert. That is also how the one raw `<br>` that #1038's
+     * migration could not convert came to exist.
+     *
+     * ## Why slots rather than converting each text run
+     *
+     * Wiki syntax must still resolve to the same nodes it does today, so the two
+     * passes have to interleave. Converting each text run between wiki matches
+     * separately would cut block constructs in half — a list item containing a
+     * link would become a one-item list, a stray fragment, and another list.
+     *
+     * Instead every wiki match is replaced by an empty slot span, markdown-it runs
+     * over the whole scaffold, and the resolved nodes are swapped back in
+     * afterwards. Block structure survives because markdown-it sees the block whole.
+     *
+     * ## Why the text is escaped first
+     *
+     * Text between matches is escaped before markdown-it sees it, which keeps the
+     * exact inertness the text-node path had: `<script>` in a block stays visible
+     * text, as it does today. Markdown syntax is untouched by that escaping, so
+     * this is strictly additive — it grants markdown without granting raw HTML.
+     */
+    private appendMarkdownBlockNodes;
+    /**
+     * Split a table cell on its line breaks — `<br>` or NCM's `\\` / `\\\` —
+     * leaving inline code spans intact (#1038).
+     *
+     * A plain `cell.split(/<br\s*\/?>|\\{2,3}/i)` was the first cut, and it broke
+     * the pages that DOCUMENT these sequences. `Using Current Time Plugin` has a
+     * SimpleDateFormat reference table whose "escape for text" row carries `\\`
+     * as its example value; splitting emptied that cell and put a line break in
+     * it, so the page stopped showing the thing it was explaining.
+     *
+     * Backticking the value does not rescue it on its own. Splitting first cuts
+     * `` `\\` `` into two lone backticks, which are no longer a code span by the
+     * time the wiki/plain decision runs — the cell then renders literal
+     * backticks AROUND a break, which is worse than where it started. Keeping
+     * the span whole is what lets appendWikiNodes see it and emit `<code>`.
+     *
+     * Only %%style tables need this. A plain markdown table reaches
+     * JSPWikiPreprocessor, where inline code is placeholder-extracted upstream
+     * and never arrives here as backticks at all — which is precisely why a
+     * plain-table probe reported this method as redundant. It is not.
+     *
+     * Code is inert elsewhere in this pipeline for the same reason —
+     * SecurityFilter.collectErrors blanks it before scanning, and
+     * migrate-br-to-ncm skips it — so a style-block cell should not be the one
+     * place a backtick fails to mean "this is a literal".
+     *
+     * A break outside the span still splits: `` `\\` is an escape\\next `` gives
+     * two segments, not three.
+     */
+    private splitCellOnBreaks;
+    private createTableNode;
+    /**
+     * Creates a DOM node from an extracted element (Phase 2 dispatcher)
+     *
+     * This is the dispatcher method for Phase 2 that routes extracted elements
+     * to the appropriate handler based on element type.
+     *
+     * @param element - Extracted element from extractJSPWikiSyntax()
+     * @param context - Rendering context
+     * @param wikiDocument - WikiDocument to create node in
+     * @returns DOM node for the element
+     *
+     * @example
+     * const element = { type: 'variable', varName: '$username', id: 0 };
+     * const node = await createDOMNode(element, context, wikiDoc);
+     * // Returns: <span class="wiki-variable">JohnDoe</span>
+     */
+    createDOMNode(element: ExtractedElement, context: ParseContext, wikiDocument: WikiDocument): Promise<unknown>;
+    /**
+     * Merges DOM nodes back into markdown-it HTML (Phase 3)
+     *
+     * Replaces HTML comment placeholders (<!--JSPWIKI-uuid-id-->) in the HTML with
+     * the rendered DOM nodes. Processes nodes in reverse ID order to
+     * handle nested JSPWiki syntax correctly.
+     *
+     * Uses HTML comments as placeholders to avoid markdown-it interpreting them as markdown.
+     *
+     * @param html - HTML from markdown-it with placeholders
+     * @param nodes - Array of DOM nodes with data-jspwiki-id
+     * @param uuid - UUID from extraction phase
+     * @returns Final HTML with nodes merged in
+     *
+     * @example
+     * // Input HTML: "<p>User: <!--JSPWIKI-abc123-0--></p>"
+     * // Node 0: <span data-jspwiki-id="0">JohnDoe</span>
+     * // Output: "<p>User: <span>JohnDoe</span></p>"
+     */
+    mergeDOMNodes(html: string, nodes: unknown[], uuid: string): string;
+    /**
+     * Put rendered HTML where its placeholder sits in markdown-it's output.
+     * Shared by DOM nodes and by trusted handler output (#1623).
+     */
+    private static placeRendered;
+    /**
+     * #1368: is `offset` inside an open <p>? The nearest tag before it that opens
+     * or closes a container decides: `<p>` says yes; `</p>`, a list item, a cell,
+     * a quote or a div says no.
+     */
+    private static insideParagraph;
+    /**
+     * #1368: rendered HTML that starts with a block element. `p` since #1623:
+     * trusted handler output (a `<wiki:Include>`) is a rendered page, and a
+     * paragraph cannot sit in a paragraph either.
+     */
+    private static readonly BLOCK_START;
+    /**
+     * Parses wiki markup using DOM extraction strategy (Phase 1-3)
+     *
+     * This is the new parsing method that implements the WikiDocument DOM solution:
+     * 1. Extract JSPWiki syntax (variables, plugins, links, escaped)
+     * 2. Create DOM nodes from extracted elements
+     * 3. Let markdown-it parse the sanitized markdown
+     * 4. Merge DOM nodes back into the HTML
+     *
+     * This approach fixes the markdown heading bug by letting markdown-it handle
+     * ALL markdown parsing while WikiDocument handles ONLY JSPWiki syntax.
+     *
+     * @param content - Wiki markup content
+     * @param context - Rendering context
+     * @returns Rendered HTML
+     *
+     * @example
+     * const html = await parser.parseWithDOMExtraction('## Hello\nUser: [{$username}]', context);
+     * // Returns: "<h2>Hello</h2>\n<p>User: <span>JohnDoe</span></p>"
+     */
+    parseWithDOMExtraction(content: string, context: Record<string, unknown>): Promise<string>;
+    /**
+     * Get performance metrics
+     */
+    getMetrics(): ExtendedMetrics;
+    /**
+     * Reset performance metrics
+     */
+    resetMetrics(): void;
+    /**
+     * Get cached parse result
+     * @param cacheKey - Cache key
+     * @returns Cached result or null
+     */
+    getCachedParseResult(cacheKey: string): Promise<string | null>;
+    /**
+     * Cache parse result
+     * @param cacheKey - Cache key
+     * @param content - Content to cache
+     */
+    cacheParseResult(cacheKey: string, content: string): Promise<void>;
+    /**
+     * Update cache metrics for specific strategy
+     * @param strategy - Cache strategy name
+     * @param operation - Operation type (hit, miss, set)
+     */
+    updateCacheMetrics(strategy: string, operation: 'hit' | 'miss' | 'set'): void;
+    /**
+     * Update performance metrics and check thresholds
+     * @param processingTime - Processing time in milliseconds
+     * @param cacheHit - Whether this was a cache hit
+     */
+    updatePerformanceMetrics(processingTime: number, cacheHit: boolean): void;
+    /**
+     * Check performance thresholds and generate alerts
+     */
+    checkPerformanceThresholds(): void;
+    /**
+     * Generate performance alert
+     * @param type - Alert type
+     * @param message - Alert message
+     */
+    generatePerformanceAlert(type: string, message: string): void;
+    /**
+     * Get performance alerts
+     * @returns Array of performance alerts
+     */
+    getPerformanceAlerts(): unknown[];
+    /**
+     * Clear performance alerts
+     */
+    clearPerformanceAlerts(): void;
+    shutdown(): Promise<void>;
+}
+export default MarkupParser;