@j0hanz/superfetch 2.4.3 → 2.4.5

package/dist/transform.js

@@ -14,133 +14,158 @@ import { detectLanguageFromCode, resolveLanguageFromAttributes, } from './langua
 import { addSourceToMarkdown, buildMetadataFooter, cleanupMarkdownArtifacts, extractTitleFromRawMarkdown, isLikelyHtmlContent, isRawTextContent, } from './markdown-cleanup.js';
 import { getOperationId, getRequestId, logDebug, logError, logInfo, logWarn, redactUrl, } from './observability.js';
 import { isObject } from './type-guards.js';
-function getAbortReason(signal) {
-    if (!isObject(signal))
-        return undefined;
-    return 'reason' in signal ? signal.reason : undefined;
-}
-// DOM accessor helpers moved to ./dom-noise-removal.ts
-const CODE_BLOCK = {
-    fence: '```',
-    format: (code, language = '') => {
-        return `\`\`\`${language}\n${code}\n\`\`\``;
-    },
-};
-const transformChannel = diagnosticsChannel.channel('superfetch.transform');
-const LOG_URL_MAX = 80;
-function truncateUrlForLog(url) {
-    return url.substring(0, LOG_URL_MAX);
-}
-function publishTransformEvent(event) {
-    if (!transformChannel.hasSubscribers)
-        return;
-    try {
-        transformChannel.publish(event);
+/* -------------------------------------------------------------------------------------------------
+ * Abort policy (single source of truth)
+ * ------------------------------------------------------------------------------------------------- */
+class AbortPolicy {
+    getAbortReason(signal) {
+        if (!isObject(signal))
+            return undefined;
+        return 'reason' in signal
+            ? signal.reason
+            : undefined;
     }
-    catch {
-        /* empty */
+    isTimeoutReason(reason) {
+        return reason instanceof Error && reason.name === 'TimeoutError';
+    }
+    throwIfAborted(signal, url, stage) {
+        if (!signal?.aborted)
+            return;
+        const reason = this.getAbortReason(signal);
+        if (this.isTimeoutReason(reason)) {
+            throw new FetchError('Request timeout', url, 504, {
+                reason: 'timeout',
+                stage,
+            });
+        }
+        throw new FetchError('Request was canceled', url, 499, {
+            reason: 'aborted',
+            stage,
+        });
+    }
+    createAbortError(url, stage) {
+        return new FetchError('Request was canceled', url, 499, {
+            reason: 'aborted',
+            stage,
+        });
     }
 }
-export function startTransformStage(url, stage, budget) {
-    if (!transformChannel.hasSubscribers && !budget)
-        return null;
-    const remainingBudgetMs = budget
-        ? budget.totalBudgetMs - budget.elapsedMs
-        : undefined;
-    const base = {
-        stage,
-        startTime: performance.now(),
-        url: redactUrl(url),
-    };
-    if (remainingBudgetMs !== undefined && budget) {
-        return {
-            ...base,
-            budgetMs: remainingBudgetMs,
-            totalBudgetMs: budget.totalBudgetMs,
+const abortPolicy = new AbortPolicy();
+/* -------------------------------------------------------------------------------------------------
+ * Stage tracking & diagnostics
+ * ------------------------------------------------------------------------------------------------- */
+class StageTracker {
+    channel = diagnosticsChannel.channel('superfetch.transform');
+    start(url, stage, budget) {
+        if (!this.channel.hasSubscribers && !budget)
+            return null;
+        const remainingBudgetMs = budget
+            ? budget.totalBudgetMs - budget.elapsedMs
+            : undefined;
+        const base = {
+            stage,
+            startTime: performance.now(),
+            url: redactUrl(url),
         };
+        if (remainingBudgetMs !== undefined && budget) {
+            return {
+                ...base,
+                budgetMs: remainingBudgetMs,
+                totalBudgetMs: budget.totalBudgetMs,
+            };
+        }
+        return base;
+    }
+    end(context, options) {
+        if (!context)
+            return 0;
+        const durationMs = performance.now() - context.startTime;
+        const requestId = getRequestId();
+        const operationId = getOperationId();
+        if (context.totalBudgetMs !== undefined) {
+            const warnThresholdMs = context.totalBudgetMs * config.transform.stageWarnRatio;
+            if (durationMs > warnThresholdMs) {
+                logWarn('Transform stage exceeded warning threshold', {
+                    stage: context.stage,
+                    durationMs: Math.round(durationMs),
+                    thresholdMs: Math.round(warnThresholdMs),
+                    url: context.url,
+                });
+            }
+        }
+        const event = {
+            v: 1,
+            type: 'stage',
+            stage: context.stage,
+            durationMs,
+            url: context.url,
+            ...(requestId ? { requestId } : {}),
+            ...(operationId ? { operationId } : {}),
+            ...(options?.truncated !== undefined
+                ? { truncated: options.truncated }
+                : {}),
+        };
+        this.publish(event);
+        return durationMs;
     }
-    return base;
-}
-export function endTransformStage(context, options) {
-    if (!context)
-        return 0;
-    const durationMs = performance.now() - context.startTime;
-    const requestId = getRequestId();
-    const operationId = getOperationId();
-    if (context.totalBudgetMs !== undefined) {
-        const warnThresholdMs = context.totalBudgetMs * config.transform.stageWarnRatio;
-        if (durationMs > warnThresholdMs) {
-            logWarn('Transform stage exceeded warning threshold', {
-                stage: context.stage,
-                durationMs: Math.round(durationMs),
-                thresholdMs: Math.round(warnThresholdMs),
-                url: context.url,
+    run(url, stage, fn, budget) {
+        if (budget && budget.elapsedMs >= budget.totalBudgetMs) {
+            throw new FetchError('Transform budget exhausted', url, 504, {
+                reason: 'timeout',
+                stage: `${stage}:budget_exhausted`,
+                elapsedMs: budget.elapsedMs,
+                totalBudgetMs: budget.totalBudgetMs,
             });
         }
+        const ctx = this.start(url, stage, budget);
+        try {
+            return fn();
+        }
+        finally {
+            this.end(ctx);
+        }
     }
-    const event = {
-        v: 1,
-        type: 'stage',
-        stage: context.stage,
-        durationMs,
-        url: context.url,
-        ...(requestId ? { requestId } : {}),
-        ...(operationId ? { operationId } : {}),
-        ...(options?.truncated !== undefined
-            ? { truncated: options.truncated }
-            : {}),
-    };
-    publishTransformEvent(event);
-    return durationMs;
-}
-function runTransformStage(url, stage, fn, budget) {
-    if (budget && budget.elapsedMs >= budget.totalBudgetMs) {
-        throw new FetchError('Transform budget exhausted', url, 504, {
-            reason: 'timeout',
-            stage: `${stage}:budget_exhausted`,
-            elapsedMs: budget.elapsedMs,
-            totalBudgetMs: budget.totalBudgetMs,
-        });
-    }
-    const context = startTransformStage(url, stage, budget);
-    try {
-        return fn();
+    async runAsync(url, stage, fn) {
+        const ctx = this.start(url, stage);
+        try {
+            return await fn();
+        }
+        finally {
+            this.end(ctx);
+        }
     }
-    finally {
-        endTransformStage(context);
+    publish(event) {
+        if (!this.channel.hasSubscribers)
+            return;
+        try {
+            this.channel.publish(event);
+        }
+        catch {
+            // Intentionally ignore diagnostics failures
+        }
     }
 }
-function isTimeoutReason(reason) {
-    return reason instanceof Error && reason.name === 'TimeoutError';
+const stageTracker = new StageTracker();
+/** Backwards-compatible exports */
+export function startTransformStage(url, stage, budget) {
+    return stageTracker.start(url, stage, budget);
 }
-function throwIfAborted(signal, url, stage) {
-    if (!signal)
-        return;
-    const { aborted } = signal;
-    if (!aborted)
-        return;
-    const reason = getAbortReason(signal);
-    if (isTimeoutReason(reason)) {
-        throw new FetchError('Request timeout', url, 504, {
-            reason: 'timeout',
-            stage,
-        });
-    }
-    throw new FetchError('Request was canceled', url, 499, {
-        reason: 'aborted',
-        stage,
-    });
+export function endTransformStage(context, options) {
+    return stageTracker.end(context, options);
 }
+/* -------------------------------------------------------------------------------------------------
+ * HTML size guard
+ * ------------------------------------------------------------------------------------------------- */
 function truncateHtml(html) {
     const maxSize = config.constants.maxHtmlSize;
     if (html.length <= maxSize) {
-        return html;
+        return { html, truncated: false };
     }
     logWarn('HTML content exceeds maximum size, truncating', {
         size: html.length,
         maxSize,
     });
-    return html.substring(0, maxSize);
+    return { html: html.substring(0, maxSize), truncated: true };
 }
 const META_PROPERTY_HANDLERS = new Map([
     [
@@ -200,162 +225,109 @@ const META_NAME_HANDLERS = new Map([
         },
     ],
 ]);
-function extractMetadata(document) {
-    const ctx = {
-        title: {},
-        description: {},
-    };
-    for (const tag of document.querySelectorAll('meta')) {
-        const content = tag.getAttribute('content')?.trim();
-        if (!content)
-            continue;
-        const property = tag.getAttribute('property');
-        if (property) {
-            META_PROPERTY_HANDLERS.get(property)?.(ctx, content);
+class MetadataExtractor {
+    extract(document) {
+        const ctx = { title: {}, description: {} };
+        for (const tag of document.querySelectorAll('meta')) {
+            const content = tag.getAttribute('content')?.trim();
+            if (!content)
+                continue;
+            const property = tag.getAttribute('property');
+            if (property)
+                META_PROPERTY_HANDLERS.get(property)?.(ctx, content);
+            const name = tag.getAttribute('name');
+            if (name)
+                META_NAME_HANDLERS.get(name)?.(ctx, content);
         }
-        const name = tag.getAttribute('name');
-        if (name) {
-            META_NAME_HANDLERS.get(name)?.(ctx, content);
+        const titleEl = document.querySelector('title');
+        if (!ctx.title.standard && titleEl?.textContent) {
+            ctx.title.standard = titleEl.textContent.trim();
         }
-    }
-    const titleEl = document.querySelector('title');
-    if (!ctx.title.standard && titleEl?.textContent) {
-        ctx.title.standard = titleEl.textContent.trim();
-    }
-    const resolvedTitle = ctx.title.og ?? ctx.title.twitter ?? ctx.title.standard;
-    const resolvedDesc = ctx.description.og ?? ctx.description.twitter ?? ctx.description.standard;
-    const metadata = {};
-    if (resolvedTitle)
-        metadata.title = resolvedTitle;
-    if (resolvedDesc)
-        metadata.description = resolvedDesc;
-    if (ctx.author)
-        metadata.author = ctx.author;
-    if (ctx.image)
-        metadata.image = ctx.image;
-    if (ctx.publishedAt)
-        metadata.publishedAt = ctx.publishedAt;
-    if (ctx.modifiedAt)
-        metadata.modifiedAt = ctx.modifiedAt;
-    return metadata;
-}
+        const resolvedTitle = ctx.title.og ?? ctx.title.twitter ?? ctx.title.standard;
+        const resolvedDesc = ctx.description.og ?? ctx.description.twitter ?? ctx.description.standard;
+        const metadata = {};
+        if (resolvedTitle)
+            metadata.title = resolvedTitle;
+        if (resolvedDesc)
+            metadata.description = resolvedDesc;
+        if (ctx.author)
+            metadata.author = ctx.author;
+        if (ctx.image)
+            metadata.image = ctx.image;
+        if (ctx.publishedAt)
+            metadata.publishedAt = ctx.publishedAt;
+        if (ctx.modifiedAt)
+            metadata.modifiedAt = ctx.modifiedAt;
+        return metadata;
+    }
+}
+const metadataExtractor = new MetadataExtractor();
+/* -------------------------------------------------------------------------------------------------
+ * Article extraction (Readability)
+ * ------------------------------------------------------------------------------------------------- */
 function isReadabilityCompatible(doc) {
     if (!isObject(doc))
         return false;
-    return hasDocumentElement(doc) && hasQuerySelectors(doc);
-}
-function hasDocumentElement(record) {
-    return 'documentElement' in record;
-}
-function hasQuerySelectors(record) {
-    return (typeof record.querySelectorAll === 'function' &&
+    const record = doc;
+    return ('documentElement' in record &&
+        typeof record.querySelectorAll ===
+            'function' &&
         typeof record.querySelector === 'function');
 }
-function extractArticle(document) {
-    if (!isReadabilityCompatible(document)) {
-        logWarn('Document not compatible with Readability');
-        return null;
-    }
-    try {
-        const doc = document;
-        const rawText = doc.querySelector('body')?.textContent ?? doc.documentElement.textContent;
-        const textLength = rawText.replace(/\s+/g, ' ').trim().length;
-        if (textLength < 100) {
-            logWarn('Very minimal server-rendered content detected (< 100 chars). ' +
-                'This might be a client-side rendered (SPA) application. ' +
-                'Content extraction may be incomplete.', { textLength });
-        }
-        if (textLength >= 400 && !isProbablyReaderable(doc)) {
+class ArticleExtractor {
+    extract(document) {
+        if (!isReadabilityCompatible(document)) {
+            logWarn('Document not compatible with Readability');
             return null;
         }
-        const reader = new Readability(doc, { maxElemsToParse: 20_000 });
-        const parsed = reader.parse();
-        if (!parsed)
+        try {
+            const doc = document;
+            const rawText = doc.querySelector('body')?.textContent ??
+                doc.documentElement.textContent;
+            const textLength = rawText.replace(/\s+/g, ' ').trim().length;
+            if (textLength < 100) {
+                logWarn('Very minimal server-rendered content detected (< 100 chars). ' +
+                    'This might be a client-side rendered (SPA) application. ' +
+                    'Content extraction may be incomplete.', { textLength });
+            }
+            if (textLength >= 400 && !isProbablyReaderable(doc)) {
+                return null;
+            }
+            const reader = new Readability(doc, { maxElemsToParse: 20_000 });
+            const parsed = reader.parse();
+            if (!parsed)
+                return null;
+            return {
+                content: parsed.content ?? '',
+                textContent: parsed.textContent ?? '',
+                ...(parsed.title != null && { title: parsed.title }),
+                ...(parsed.byline != null && { byline: parsed.byline }),
+                ...(parsed.excerpt != null && { excerpt: parsed.excerpt }),
+                ...(parsed.siteName != null && { siteName: parsed.siteName }),
+            };
+        }
+        catch (error) {
+            logError('Failed to extract article with Readability', error instanceof Error ? error : undefined);
             return null;
-        return {
-            content: parsed.content ?? '',
-            textContent: parsed.textContent ?? '',
-            ...(parsed.title != null && { title: parsed.title }),
-            ...(parsed.byline != null && { byline: parsed.byline }),
-            ...(parsed.excerpt != null && { excerpt: parsed.excerpt }),
-            ...(parsed.siteName != null && { siteName: parsed.siteName }),
-        };
-    }
-    catch (error) {
-        logError('Failed to extract article with Readability', error instanceof Error ? error : undefined);
-        return null;
-    }
-}
-export function extractContent(html, url, options = {
-    extractArticle: true,
-}) {
-    const result = extractContentWithDocument(html, url, options);
-    return { article: result.article, metadata: result.metadata };
-}
-function extractContentWithDocument(html, url, options) {
-    if (!isValidInput(html, url)) {
-        const { document } = parseHTML('<html></html>');
-        return { article: null, metadata: {}, document };
-    }
-    return tryExtractContent(html, url, options);
-}
-function extractArticleWithStage(document, url, shouldExtract) {
-    if (!shouldExtract)
-        return null;
-    return runTransformStage(url, 'extract:article', () => resolveArticleExtraction(document, shouldExtract));
-}
-function handleExtractionFailure(error, url, signal) {
-    if (error instanceof FetchError) {
-        throw error;
-    }
-    throwIfAborted(signal, url, 'extract:error');
-    logError('Failed to extract content', error instanceof Error ? error : undefined);
-    const { document } = parseHTML('<html></html>');
-    return { article: null, metadata: {}, document };
-}
-function extractContentStages(html, url, options) {
-    throwIfAborted(options.signal, url, 'extract:begin');
-    const truncatedHtml = truncateHtml(html);
-    const { document } = runTransformStage(url, 'extract:parse', () => parseHTML(truncatedHtml));
-    throwIfAborted(options.signal, url, 'extract:parsed');
-    applyBaseUri(document, url);
-    const metadata = runTransformStage(url, 'extract:metadata', () => extractMetadata(document));
-    throwIfAborted(options.signal, url, 'extract:metadata');
-    const article = extractArticleWithStage(document, url, options.extractArticle);
-    throwIfAborted(options.signal, url, 'extract:article');
-    return {
-        article,
-        metadata,
-        document,
-        ...(truncatedHtml.length !== html.length ? { truncated: true } : {}),
-    };
-}
-function tryExtractContent(html, url, options) {
-    try {
-        return extractContentStages(html, url, options);
-    }
-    catch (error) {
-        return handleExtractionFailure(error, url, options.signal);
+        }
     }
 }
-function isValidInput(html, url) {
-    return (validateRequiredString(html, 'extractContent called with invalid HTML input') && validateRequiredString(url, 'extractContent called with invalid URL'));
-}
+const articleExtractor = new ArticleExtractor();
+/* -------------------------------------------------------------------------------------------------
+ * Content extraction orchestration
+ * ------------------------------------------------------------------------------------------------- */
 function validateRequiredString(value, message) {
     if (typeof value === 'string' && value.length > 0)
         return true;
     logWarn(message);
     return false;
 }
-function resolveArticleExtraction(document, shouldExtract) {
-    return shouldExtract ? extractArticle(document) : null;
+function isValidInput(html, url) {
+    return (validateRequiredString(html, 'extractContent called with invalid HTML input') && validateRequiredString(url, 'extractContent called with invalid URL'));
 }
 function applyBaseUri(document, url) {
     try {
-        Object.defineProperty(document, 'baseURI', {
-            value: url,
-            writable: true,
-        });
+        Object.defineProperty(document, 'baseURI', { value: url, writable: true });
     }
     catch (error) {
         logInfo('Failed to set baseURI (non-critical)', {
@@ -364,13 +336,62 @@ function applyBaseUri(document, url) {
         });
     }
 }
+class ContentExtractor {
+    extract(html, url, options) {
+        if (!isValidInput(html, url)) {
+            const { document } = parseHTML('<html></html>');
+            return { article: null, metadata: {}, document };
+        }
+        try {
+            abortPolicy.throwIfAborted(options.signal, url, 'extract:begin');
+            const { html: limitedHtml, truncated } = truncateHtml(html);
+            const { document } = stageTracker.run(url, 'extract:parse', () => parseHTML(limitedHtml));
+            abortPolicy.throwIfAborted(options.signal, url, 'extract:parsed');
+            applyBaseUri(document, url);
+            const metadata = stageTracker.run(url, 'extract:metadata', () => metadataExtractor.extract(document));
+            abortPolicy.throwIfAborted(options.signal, url, 'extract:metadata');
+            const article = options.extractArticle
+                ? stageTracker.run(url, 'extract:article', () => articleExtractor.extract(document))
+                : null;
+            abortPolicy.throwIfAborted(options.signal, url, 'extract:article');
+            return {
+                article,
+                metadata,
+                document,
+                ...(truncated ? { truncated: true } : {}),
+            };
+        }
+        catch (error) {
+            if (error instanceof FetchError)
+                throw error;
+            abortPolicy.throwIfAborted(options.signal, url, 'extract:error');
+            logError('Failed to extract content', error instanceof Error ? error : undefined);
+            const { document } = parseHTML('<html></html>');
+            return { article: null, metadata: {}, document };
+        }
+    }
+}
+const contentExtractor = new ContentExtractor();
+/** Backwards-compatible export */
+export function extractContent(html, url, options = {
+    extractArticle: true,
+}) {
+    const result = contentExtractor.extract(html, url, options);
+    return { article: result.article, metadata: result.metadata };
+}
+/* -------------------------------------------------------------------------------------------------
+ * Markdown conversion
+ * ------------------------------------------------------------------------------------------------- */
+const CODE_BLOCK = {
+    fence: '```',
+    format: (code, language = '') => `\`\`\`${language}\n${code}\n\`\`\``,
+};
 function buildInlineCode(content) {
     let maxBackticks = 0;
     let currentRun = 0;
     for (const char of content) {
-        if (char === '`') {
-            currentRun++;
-        }
+        if (char === '`')
+            currentRun += 1;
         else {
             if (currentRun > maxBackticks)
                 maxBackticks = currentRun;
@@ -402,21 +423,25 @@ function deriveAltFromImageUrl(src) {
         return '';
     }
 }
+function hasGetAttribute(value) {
+    return (isObject(value) &&
+        typeof value.getAttribute === 'function');
+}
 function isCodeBlock(parent) {
     if (!isObject(parent))
         return false;
-    const tagName = typeof parent.tagName === 'string' ? parent.tagName.toUpperCase() : '';
+    const tagName = typeof parent.tagName === 'string'
+        ? parent.tagName.toUpperCase()
+        : '';
     return ['PRE', 'WRAPPED-PRE'].includes(tagName);
 }
-function hasGetAttribute(value) {
-    return isObject(value) && typeof value.getAttribute === 'function';
-}
-function buildInlineCodeTranslator() {
-    return {
-        spaceIfRepeatingChar: true,
-        noEscape: true,
-        postprocess: ({ content }) => buildInlineCode(content),
-    };
+function isAnchor(node) {
+    if (!isObject(node))
+        return false;
+    const tagName = typeof node.tagName === 'string'
+        ? node.tagName.toUpperCase()
+        : '';
+    return tagName === 'A';
 }
 function resolveAttributeLanguage(node) {
     const getAttribute = hasGetAttribute(node)
@@ -426,46 +451,20 @@ function resolveAttributeLanguage(node) {
     const dataLanguage = getAttribute?.('data-language') ?? '';
     return resolveLanguageFromAttributes(className, dataLanguage);
 }
-function buildCodeTranslator(ctx) {
-    if (!isObject(ctx))
-        return buildInlineCodeTranslator();
-    const { parent } = ctx;
-    if (!isCodeBlock(parent))
-        return buildInlineCodeTranslator();
-    return {
-        noEscape: true,
-        preserveWhitespace: true,
-    };
-}
-function buildImageTranslator(ctx) {
-    if (!isObject(ctx))
-        return { content: '' };
-    const { node } = ctx;
-    const getAttribute = hasGetAttribute(node)
-        ? node.getAttribute.bind(node)
-        : undefined;
-    const src = getAttribute?.('src') ?? '';
-    const existingAlt = getAttribute?.('alt') ?? '';
-    const alt = existingAlt.trim() || deriveAltFromImageUrl(src);
-    return {
-        content: `![${alt}](${src})`,
-    };
-}
 function findLanguageFromCodeChild(node) {
     if (!isObject(node))
         return undefined;
-    const { childNodes } = node;
-    if (!Array.isArray(childNodes))
-        return undefined;
+    const childNodes = Array.isArray(node.childNodes)
+        ? node.childNodes
+        : [];
     for (const child of childNodes) {
         if (!isObject(child))
             continue;
         const tagName = typeof child.rawTagName === 'string'
             ? child.rawTagName.toUpperCase()
             : '';
-        if (tagName === 'CODE') {
+        if (tagName === 'CODE')
             return resolveAttributeLanguage(child);
-        }
     }
     return undefined;
 }
@@ -478,6 +477,37 @@ function createCodeBlockPostprocessor(language) {
         return CODE_BLOCK.format(trimmed, resolvedLanguage);
     };
 }
+function buildInlineCodeTranslator() {
+    return {
+        spaceIfRepeatingChar: true,
+        noEscape: true,
+        postprocess: ({ content }) => buildInlineCode(content),
+    };
+}
+function buildCodeTranslator(ctx) {
+    if (!isObject(ctx))
+        return buildInlineCodeTranslator();
+    const { parent } = ctx;
+    if (!isCodeBlock(parent))
+        return buildInlineCodeTranslator();
+    return { noEscape: true, preserveWhitespace: true };
+}
+function buildImageTranslator(ctx) {
+    if (!isObject(ctx))
+        return { content: '' };
+    const { node, parent } = ctx;
+    const getAttribute = hasGetAttribute(node)
+        ? node.getAttribute.bind(node)
+        : undefined;
+    const src = getAttribute?.('src') ?? '';
+    const existingAlt = getAttribute?.('alt') ?? '';
+    const alt = existingAlt.trim() || deriveAltFromImageUrl(src);
+    const markdown = `![${alt}](${src})`;
+    if (isAnchor(parent)) {
+        return { content: markdown };
+    }
+    return { content: `\n\n${markdown}\n\n` };
+}
 function buildPreTranslator(ctx) {
     if (!isObject(ctx))
         return {};
@@ -494,10 +524,9 @@ function createCustomTranslators() {
         code: (ctx) => buildCodeTranslator(ctx),
         img: (ctx) => buildImageTranslator(ctx),
         dl: (ctx) => {
-            if (!isObject(ctx) || !isObject(ctx.node)) {
+            if (!isObject(ctx) || !isObject(ctx.node))
                 return { content: '' };
-            }
-            const node = ctx.node;
+            const { node } = ctx;
             const childNodes = Array.isArray(node.childNodes) ? node.childNodes : [];
             const items = childNodes
                 .map((child) => {
@@ -520,14 +549,15 @@ function createCustomTranslators() {
             return { content: items ? `\n${items}\n\n` : '' };
         },
         div: (ctx) => {
-            if (!isObject(ctx) || !isObject(ctx.node)) {
+            if (!isObject(ctx) || !isObject(ctx.node))
                 return {};
-            }
-            const node = ctx.node;
-            const className = typeof node.attribs?.class === 'string' ? node.attribs.class : '';
-            if (!className.includes('type')) {
+            const { node } = ctx;
+            const getAttribute = hasGetAttribute(node)
+                ? node.getAttribute.bind(node)
+                : undefined;
+            const className = getAttribute?.('class') ?? '';
+            if (!className.includes('type'))
                 return {};
-            }
             return {
                 postprocess: ({ content }) => {
                     const lines = content.split('\n');
@@ -561,37 +591,41 @@ function createCustomTranslators() {
         sup: () => ({
             postprocess: ({ content }) => `^${content}^`,
         }),
-        // Note: section translator removed in favor of HTML preprocessing
-        // See preprocessPropertySections() for the fix to TypeDoc section spacing
+        section: () => ({
+            postprocess: ({ content }) => `\n\n${content}\n\n`,
+        }),
         pre: (ctx) => buildPreTranslator(ctx),
     };
 }
-let markdownInstance = null;
-function createMarkdownInstance() {
-    return new NodeHtmlMarkdown({
-        codeFence: CODE_BLOCK.fence,
-        codeBlockStyle: 'fenced',
-        emDelimiter: '_',
-        bulletMarker: '-',
-    }, createCustomTranslators());
-}
-function getMarkdownConverter() {
-    markdownInstance ??= createMarkdownInstance();
-    return markdownInstance;
+class MarkdownConverter {
+    instance = null;
+    translate(html) {
+        return this.get().translate(html).trim();
+    }
+    get() {
+        this.instance ??= new NodeHtmlMarkdown({
+            codeFence: CODE_BLOCK.fence,
+            codeBlockStyle: 'fenced',
+            emDelimiter: '_',
+            bulletMarker: '-',
+        }, createCustomTranslators());
+        return this.instance;
+    }
 }
+const markdownConverter = new MarkdownConverter();
 function preprocessPropertySections(html) {
-    const result = html.replace(/<\/section>\s*(<section[^>]*class="[^"]*tsd-panel[^"]*tsd-member[^"]*"[^>]*>)/g, '</section><p>&nbsp;</p>$1');
-    return result;
+    return html.replace(/<\/section>\s*(<section[^>]*class="[^"]*tsd-member[^"]*"[^>]*>)/g, '</section><p>&nbsp;</p>$1');
 }
-function translateHtmlToMarkdown(html, url, signal, document, skipNoiseRemoval) {
-    throwIfAborted(signal, url, 'markdown:begin');
+function translateHtmlToMarkdown(params) {
+    const { html, url, signal, document, skipNoiseRemoval } = params;
+    abortPolicy.throwIfAborted(signal, url, 'markdown:begin');
     const cleanedHtml = skipNoiseRemoval
         ? html
-        : runTransformStage(url, 'markdown:noise', () => removeNoiseFromHtml(html, document, url));
-    throwIfAborted(signal, url, 'markdown:cleaned');
-    const preprocessedHtml = runTransformStage(url, 'markdown:preprocess', () => preprocessPropertySections(cleanedHtml));
-    const content = runTransformStage(url, 'markdown:translate', () => getMarkdownConverter().translate(preprocessedHtml).trim());
-    throwIfAborted(signal, url, 'markdown:translated');
+        : stageTracker.run(url, 'markdown:noise', () => removeNoiseFromHtml(html, document, url));
+    abortPolicy.throwIfAborted(signal, url, 'markdown:cleaned');
+    const preprocessedHtml = stageTracker.run(url, 'markdown:preprocess', () => preprocessPropertySections(cleanedHtml));
+    const content = stageTracker.run(url, 'markdown:translate', () => markdownConverter.translate(preprocessedHtml));
+    abortPolicy.throwIfAborted(signal, url, 'markdown:translated');
     return cleanupMarkdownArtifacts(content);
 }
 function appendMetadataFooter(content, metadata, url) {
@@ -603,77 +637,71 @@ export function htmlToMarkdown(html, metadata, options) {
     if (!html)
         return buildMetadataFooter(metadata, url);
     try {
-        const content = translateHtmlToMarkdown(html, url, options?.signal, options?.document, options?.skipNoiseRemoval);
+        const content = translateHtmlToMarkdown({
+            html,
+            url,
+            signal: options?.signal,
+            document: options?.document,
+            skipNoiseRemoval: options?.skipNoiseRemoval,
+        });
         return appendMetadataFooter(content, metadata, url);
     }
     catch (error) {
-        if (error instanceof FetchError) {
+        if (error instanceof FetchError)
             throw error;
-        }
         logError('Failed to convert HTML to markdown', error instanceof Error ? error : undefined);
         return buildMetadataFooter(metadata, url);
     }
 }
+/* -------------------------------------------------------------------------------------------------
+ * Raw content shortcut
+ * ------------------------------------------------------------------------------------------------- */
 function shouldPreserveRawContent(url, content) {
-    if (isRawTextContentUrl(url)) {
+    if (isRawTextContentUrl(url))
         return !isLikelyHtmlContent(content);
-    }
     return isRawTextContent(content);
 }
-function buildRawMarkdownPayload({ rawContent, url, includeMetadata, }) {
-    const title = extractTitleFromRawMarkdown(rawContent);
-    const content = includeMetadata
-        ? addSourceToMarkdown(rawContent, url)
-        : rawContent;
+function buildRawMarkdownPayload(params) {
+    const title = extractTitleFromRawMarkdown(params.rawContent);
+    const content = params.includeMetadata
+        ? addSourceToMarkdown(params.rawContent, params.url)
+        : params.rawContent;
     return { content, title };
 }
-function buildRawMarkdownResult({ rawContent, url, includeMetadata, }) {
-    const { content, title } = buildRawMarkdownPayload({
-        rawContent,
-        url,
-        includeMetadata,
-    });
-    return {
-        markdown: content,
-        title,
-        truncated: false,
-    };
-}
-function tryTransformRawContent({ html, url, includeMetadata, }) {
-    if (!shouldPreserveRawContent(url, html)) {
+function tryTransformRawContent(params) {
+    if (!shouldPreserveRawContent(params.url, params.html))
         return null;
-    }
-    logDebug('Preserving raw markdown content', { url: truncateUrlForLog(url) });
-    return buildRawMarkdownResult({
-        rawContent: html,
-        url,
-        includeMetadata,
+    logDebug('Preserving raw markdown content', {
+        url: params.url.substring(0, 80),
+    });
+    const { content, title } = buildRawMarkdownPayload({
+        rawContent: params.html,
+        url: params.url,
+        includeMetadata: params.includeMetadata,
     });
+    return { markdown: content, title, truncated: false };
 }
+/* -------------------------------------------------------------------------------------------------
+ * Quality gates + content source resolution
+ * ------------------------------------------------------------------------------------------------- */
 const MIN_CONTENT_RATIO = 0.3;
 const MIN_HTML_LENGTH_FOR_GATE = 100;
 const MIN_HEADING_RETENTION_RATIO = 0.7;
 const MIN_CODE_BLOCK_RETENTION_RATIO = 0.5;
-/**
- * Check if HTML string needs document wrapper for proper parsing.
- * Fragments without doctype/html/body tags need wrapping.
- */
+const MIN_LINE_LENGTH_FOR_TRUNCATION_CHECK = 20;
+const MAX_TRUNCATED_LINE_RATIO = 0.5;
 function needsDocumentWrapper(html) {
     const trimmed = html.trim().toLowerCase();
     return (!trimmed.startsWith('<!doctype') &&
         !trimmed.startsWith('<html') &&
         !trimmed.startsWith('<body'));
 }
-/**
- * Wrap HTML fragment in minimal document structure for proper parsing.
- */
 function wrapHtmlFragment(html) {
     return `<!DOCTYPE html><html><body>${html}</body></html>`;
 }
 function resolveHtmlDocument(htmlOrDocument) {
-    if (typeof htmlOrDocument !== 'string') {
+    if (typeof htmlOrDocument !== 'string')
         return htmlOrDocument;
-    }
     const htmlToParse = needsDocumentWrapper(htmlOrDocument)
         ? wrapHtmlFragment(htmlOrDocument)
         : htmlOrDocument;
@@ -682,39 +710,26 @@ function resolveHtmlDocument(htmlOrDocument) {
 function countDomSelector(htmlOrDocument, selector) {
     return resolveHtmlDocument(htmlOrDocument).querySelectorAll(selector).length;
 }
-/**
- * Count headings using DOM querySelectorAll.
- * Handles nested content like <h2><span>Text</span></h2> correctly.
- */
 function countHeadingsDom(htmlOrDocument) {
     return countDomSelector(htmlOrDocument, 'h1,h2,h3,h4,h5,h6');
 }
 function countCodeBlocksDom(htmlOrDocument) {
     return countDomSelector(htmlOrDocument, 'pre');
 }
-function cloneDocumentIfNeeded(htmlOrDocument, doc) {
-    return typeof htmlOrDocument === 'string'
-        ? doc
-        : doc.cloneNode(true);
-}
 function stripNonVisibleNodes(doc) {
-    for (const el of doc.querySelectorAll('script,style,noscript')) {
+    for (const el of doc.querySelectorAll('script,style,noscript'))
         el.remove();
-    }
 }
 function resolveDocumentText(doc) {
-    // Note: linkedom may return null for body on HTML fragments despite types
     const body = doc.body;
     const docElement = doc.documentElement;
     return body?.textContent ?? docElement?.textContent ?? '';
 }
-/**
- * Get visible text length from HTML, excluding script/style/noscript content.
- * Fixes the bug where stripHtmlTagsForLength() counted JS/CSS as visible text.
- */
 function getVisibleTextLength(htmlOrDocument) {
     const doc = resolveHtmlDocument(htmlOrDocument);
-    const workDoc = cloneDocumentIfNeeded(htmlOrDocument, doc);
+    const workDoc = typeof htmlOrDocument === 'string'
+        ? doc
+        : doc.cloneNode(true);
     stripNonVisibleNodes(workDoc);
     const text = resolveDocumentText(workDoc);
     return text.replace(/\s+/g, ' ').trim().length;
@@ -723,29 +738,18 @@ export function isExtractionSufficient(article, originalHtmlOrDocument) {
     if (!article)
         return false;
     const articleLength = article.textContent.length;
-    // Use DOM-based visible text length to exclude script/style content
     const originalLength = getVisibleTextLength(originalHtmlOrDocument);
     if (originalLength < MIN_HTML_LENGTH_FOR_GATE)
         return true;
     return articleLength / originalLength >= MIN_CONTENT_RATIO;
 }
-const MIN_LINE_LENGTH_FOR_TRUNCATION_CHECK = 20;
-const MAX_TRUNCATED_LINE_RATIO = 0.5;
-/**
- * Detect if extracted text has many truncated/incomplete sentences.
- * Lines longer than 20 chars that don't end with sentence punctuation
- * are considered potentially truncated.
- */
 function hasTruncatedSentences(text) {
     const lines = text
         .split('\n')
         .filter((line) => line.trim().length > MIN_LINE_LENGTH_FOR_TRUNCATION_CHECK);
     if (lines.length < 3)
         return false;
-    const incompleteLines = lines.filter((line) => {
-        const trimmed = line.trim();
-        return !/[.!?:;]$/.test(trimmed);
-    });
+    const incompleteLines = lines.filter((line) => !/[.!?:;]$/.test(line.trim()));
     return incompleteLines.length / lines.length > MAX_TRUNCATED_LINE_RATIO;
 }
 export function determineContentExtractionSource(article) {
@@ -768,19 +772,13 @@ export function createContentMetadataBlock(url, article, extractedMeta, shouldEx
     else {
         if (extractedMeta.title !== undefined)
             metadata.title = extractedMeta.title;
-        if (extractedMeta.description !== undefined) {
+        if (extractedMeta.description !== undefined)
             metadata.description = extractedMeta.description;
-        }
-        if (extractedMeta.author !== undefined) {
+        if (extractedMeta.author !== undefined)
             metadata.author = extractedMeta.author;
-        }
     }
     return metadata;
 }
-/**
- * Content root selectors in priority order.
- * These identify the main content area on a page.
- */
 const CONTENT_ROOT_SELECTORS = [
     'main',
     'article',
@@ -797,75 +795,23 @@ const CONTENT_ROOT_SELECTORS = [
     '.post-body',
     '.article-body',
 ];
-/**
- * Find the main content root element in a document.
- * Returns the innerHTML if found, undefined otherwise.
- */
 function findContentRoot(document) {
     for (const selector of CONTENT_ROOT_SELECTORS) {
         const element = document.querySelector(selector);
         if (!element)
             continue;
-        // Check if element has meaningful content
         const innerHTML = typeof element.innerHTML === 'string'
             ? element.innerHTML
             : undefined;
-        if (innerHTML && innerHTML.trim().length > 100) {
+        if (innerHTML && innerHTML.trim().length > 100)
             return innerHTML;
-        }
     }
     return undefined;
 }
-function buildContentSource({ html, url, article, extractedMeta, includeMetadata, useArticleContent, document, }) {
-    const metadata = createContentMetadataBlock(url, article, extractedMeta, useArticleContent, includeMetadata);
-    // If using article content, return it directly
-    if (useArticleContent && article) {
-        return {
-            sourceHtml: article.content,
-            title: article.title,
-            metadata,
-        };
-    }
-    // Try content root fallback before using full HTML
-    if (document) {
-        // Apply noise removal to HTML first (without passing document) to get cleaned HTML,
-        // then parse and find content root. This prevents the aggressive DOM stripping that
-        // happens when noise removal is given the original parsed document.
-        const cleanedHtml = removeNoiseFromHtml(html, undefined, url);
-        const { document: cleanedDoc } = parseHTML(cleanedHtml);
-        const contentRoot = findContentRoot(cleanedDoc);
-        if (contentRoot) {
-            logDebug('Using content root fallback instead of full HTML', {
-                url: truncateUrlForLog(url),
-                contentLength: contentRoot.length,
-            });
-            return {
-                sourceHtml: contentRoot,
-                title: extractedMeta.title,
-                metadata,
-                // Skip noise removal - this HTML is already from a cleaned document
-                skipNoiseRemoval: true,
-            };
-        }
-    }
-    // Fall back to full HTML
-    return {
-        sourceHtml: html,
-        title: extractedMeta.title,
-        metadata,
-        ...(document ? { document } : {}),
-    };
-}
-function logQualityGateFallback({ safeUrl, articleLength, }) {
-    logDebug('Quality gate: Readability extraction below threshold, using full HTML', {
-        url: safeUrl,
-        articleLength,
-    });
-}
 function shouldUseArticleContent(article, originalHtmlOrDocument, url) {
     const articleLength = article.textContent.length;
     const originalLength = getVisibleTextLength(originalHtmlOrDocument);
-    const safeUrl = truncateUrlForLog(url);
+    const safeUrl = url.substring(0, 80);
     let articleDocument = null;
     const getArticleDocument = () => {
         if (articleDocument)
@@ -873,15 +819,16 @@ function shouldUseArticleContent(article, originalHtmlOrDocument, url) {
         articleDocument = resolveHtmlDocument(article.content);
         return articleDocument;
     };
-    // If the document is tiny, don't gate too aggressively.
     if (originalLength >= MIN_HTML_LENGTH_FOR_GATE) {
         const ratio = articleLength / originalLength;
         if (ratio < MIN_CONTENT_RATIO) {
-            logQualityGateFallback({ safeUrl, articleLength });
+            logDebug('Quality gate: Readability extraction below threshold, using full HTML', {
+                url: safeUrl,
+                articleLength,
+            });
             return false;
         }
     }
-    // Heading structure retention (compute counts once to avoid repeated DOM queries/parses).
     const originalHeadings = countHeadingsDom(originalHtmlOrDocument);
     if (originalHeadings > 0) {
         const articleHeadings = countHeadingsDom(getArticleDocument());
@@ -899,7 +846,6 @@ function shouldUseArticleContent(article, originalHtmlOrDocument, url) {
     if (originalCodeBlocks > 0) {
         const articleCodeBlocks = countCodeBlocksDom(getArticleDocument());
         const codeRetentionRatio = articleCodeBlocks / originalCodeBlocks;
-        // Always log code block counts for debugging
         logDebug('Code block retention check', {
             url: safeUrl,
             originalCodeBlocks,
@@ -915,100 +861,106 @@ function shouldUseArticleContent(article, originalHtmlOrDocument, url) {
             return false;
         }
     }
-    // Layout extraction issue: truncated/fragmented lines.
     if (hasTruncatedSentences(article.textContent)) {
-        logDebug('Quality gate: Extracted text has many truncated sentences, using full HTML', { url: safeUrl });
+        logDebug('Quality gate: Extracted text has many truncated sentences, using full HTML', {
+            url: safeUrl,
+        });
         return false;
     }
     return true;
 }
-function resolveContentSource({ html, url, includeMetadata, signal, }) {
-    const { article, metadata: extractedMeta, document, } = extractContentWithDocument(html, url, {
+function buildContentSource(params) {
+    const { html, url, article, extractedMeta, includeMetadata, useArticleContent, document, } = params;
+    const metadata = createContentMetadataBlock(url, article, extractedMeta, useArticleContent, includeMetadata);
+    if (useArticleContent && article) {
+        return { sourceHtml: article.content, title: article.title, metadata };
+    }
+    if (document) {
+        const cleanedHtml = removeNoiseFromHtml(html, undefined, url);
+        const { document: cleanedDoc } = parseHTML(cleanedHtml);
+        const contentRoot = findContentRoot(cleanedDoc);
+        if (contentRoot) {
+            logDebug('Using content root fallback instead of full HTML', {
+                url: url.substring(0, 80),
+                contentLength: contentRoot.length,
+            });
+            return {
+                sourceHtml: contentRoot,
+                title: extractedMeta.title,
+                metadata,
+                skipNoiseRemoval: true,
+            };
+        }
+    }
+    return {
+        sourceHtml: html,
+        title: extractedMeta.title,
+        metadata,
+        ...(document ? { document } : {}),
+    };
+}
+function resolveContentSource(params) {
+    const { article, metadata: extractedMeta, document, } = contentExtractor.extract(params.html, params.url, {
         extractArticle: true,
-        ...(signal ? { signal } : {}),
+        ...(params.signal ? { signal: params.signal } : {}),
     });
-    const originalDocument = document;
     const useArticleContent = article
-        ? shouldUseArticleContent(article, originalDocument, url)
+        ? shouldUseArticleContent(article, document, params.url)
         : false;
     return buildContentSource({
-        html,
-        url,
+        html: params.html,
+        url: params.url,
         article,
         extractedMeta,
-        includeMetadata,
+        includeMetadata: params.includeMetadata,
         useArticleContent,
         document,
     });
 }
-function tryTransformRawStage(html, url, includeMetadata) {
-    return runTransformStage(url, 'transform:raw', () => tryTransformRawContent({
-        html,
-        url,
-        includeMetadata,
-    }));
-}
-function resolveContentSourceStage(html, url, includeMetadata, signal) {
-    return runTransformStage(url, 'transform:extract', () => resolveContentSource({
-        html,
-        url,
-        includeMetadata,
-        ...(signal ? { signal } : {}),
-    }));
-}
+/* -------------------------------------------------------------------------------------------------
+ * In-process transform pipeline (public)
+ * ------------------------------------------------------------------------------------------------- */
 function buildMarkdownFromContext(context, url, signal) {
-    const content = runTransformStage(url, 'transform:markdown', () => htmlToMarkdown(context.sourceHtml, context.metadata, {
+    const content = stageTracker.run(url, 'transform:markdown', () => htmlToMarkdown(context.sourceHtml, context.metadata, {
         url,
         ...(signal ? { signal } : {}),
         ...(context.document ? { document: context.document } : {}),
         ...(context.skipNoiseRemoval ? { skipNoiseRemoval: true } : {}),
     }));
-    return {
-        markdown: content,
-        title: context.title,
-        truncated: false,
-    };
+    return { markdown: content, title: context.title, truncated: false };
 }
-function runTotalTransformStage(url, fn) {
-    const totalStage = startTransformStage(url, 'transform:total');
-    let success = false;
-    try {
-        const result = fn();
-        success = true;
-        return result;
-    }
-    finally {
-        finalizeTotalTransformStage(totalStage, success);
-    }
-}
-function finalizeTotalTransformStage(stage, success) {
-    if (!success)
-        return;
-    endTransformStage(stage, { truncated: false });
-}
-async function runTotalTransformStageAsync(url, fn) {
-    const totalStage = startTransformStage(url, 'transform:total');
+export function transformHtmlToMarkdownInProcess(html, url, options) {
+    const totalStage = stageTracker.start(url, 'transform:total');
     let success = false;
     try {
-        const result = await fn();
+        abortPolicy.throwIfAborted(options.signal, url, 'transform:begin');
+        const raw = stageTracker.run(url, 'transform:raw', () => tryTransformRawContent({
+            html,
+            url,
+            includeMetadata: options.includeMetadata,
+        }));
+        if (raw) {
+            success = true;
+            return raw;
+        }
+        const context = stageTracker.run(url, 'transform:extract', () => resolveContentSource({
+            html,
+            url,
+            includeMetadata: options.includeMetadata,
+            ...(options.signal ? { signal: options.signal } : {}),
+        }));
+        const result = buildMarkdownFromContext(context, url, options.signal);
         success = true;
         return result;
     }
     finally {
-        finalizeTotalTransformStage(totalStage, success);
+        if (success)
+            stageTracker.end(totalStage, { truncated: false });
     }
 }
-export function transformHtmlToMarkdownInProcess(html, url, options) {
-    return runTotalTransformStage(url, () => {
-        throwIfAborted(options.signal, url, 'transform:begin');
-        const raw = tryTransformRawStage(html, url, options.includeMetadata);
-        if (raw) {
-            return raw;
-        }
-        const context = resolveContentSourceStage(html, url, options.includeMetadata, options.signal);
-        return buildMarkdownFromContext(context, url, options.signal);
-    });
-}
+/* -------------------------------------------------------------------------------------------------
+ * Worker pool
+ * ------------------------------------------------------------------------------------------------- */
 const workerMessageSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('result'),
@@ -1031,142 +983,137 @@ const workerMessageSchema = z.discriminatedUnion('type', [
         }),
     }),
 ]);
-let pool = null;
 const POOL_MIN_WORKERS = 2;
 const POOL_MAX_WORKERS = 4;
 const POOL_SCALE_THRESHOLD = 0.5;
-function resolveDefaultWorkerCount() {
-    return POOL_MIN_WORKERS;
-}
 const DEFAULT_TIMEOUT_MS = config.transform.timeoutMs;
-function getOrCreateTransformWorkerPool() {
-    pool ??= new WorkerPool(resolveDefaultWorkerCount(), DEFAULT_TIMEOUT_MS);
-    return pool;
-}
-export async function shutdownTransformWorkerPool() {
-    if (!pool)
-        return;
-    await pool.close();
-    pool = null;
-}
-export function getTransformPoolStats() {
-    if (!pool)
-        return null;
-    return {
-        queueDepth: pool.getQueueDepth(),
-        activeWorkers: pool.getActiveWorkers(),
-        capacity: pool.getCapacity(),
-    };
-}
 class WorkerPool {
     workers = [];
     capacity;
-    minCapacity;
-    maxCapacity;
+    minCapacity = POOL_MIN_WORKERS;
+    maxCapacity = POOL_MAX_WORKERS;
     queue = [];
     inflight = new Map();
     timeoutMs;
     queueMax;
     closed = false;
-    createAbortError(url, stage) {
-        return new FetchError('Request was canceled', url, 499, {
-            reason: 'aborted',
-            stage,
-        });
+    constructor(size, timeoutMs) {
+        this.capacity = Math.max(this.minCapacity, Math.min(size, this.maxCapacity));
+        this.timeoutMs = timeoutMs;
+        this.queueMax = this.maxCapacity * 32;
     }
-    ensureOpen() {
-        if (this.closed) {
-            throw new Error('Transform worker pool closed');
+    async transform(html, url, options) {
+        this.ensureOpen();
+        if (options.signal?.aborted)
+            throw abortPolicy.createAbortError(url, 'transform:enqueue');
+        if (this.queue.length >= this.queueMax) {
+            throw new FetchError('Transform worker queue is full', url, 503, {
+                reason: 'queue_full',
+                stage: 'transform:enqueue',
+            });
         }
+        return new Promise((resolve, reject) => {
+            const task = this.createPendingTask(html, url, options, resolve, reject);
+            this.queue.push(task);
+            this.drainQueue();
+        });
     }
-    ensureNotAborted(signal, url, stage) {
-        if (!signal?.aborted)
-            return;
-        throw this.createAbortError(url, stage);
+    getQueueDepth() {
+        return this.queue.length;
     }
-    ensureQueueCapacity(url) {
-        if (this.queue.length < this.queueMax)
-            return;
-        throw new FetchError('Transform worker queue is full', url, 503, {
-            reason: 'queue_full',
-            stage: 'transform:enqueue',
-        });
+    getActiveWorkers() {
+        return this.workers.filter((s) => s?.busy).length;
     }
-    clearAbortListener(signal, listener) {
-        if (!signal || !listener)
+    getCapacity() {
+        return this.capacity;
+    }
+    async close() {
+        if (this.closed)
             return;
-        try {
-            signal.removeEventListener('abort', listener);
-        }
-        catch {
-            /* empty */
+        this.closed = true;
+        const terminations = this.workers
+            .map((slot) => slot?.worker.terminate())
+            .filter((p) => p !== undefined);
+        this.workers.fill(undefined);
+        this.workers.length = 0;
+        for (const [id, inflight] of this.inflight.entries()) {
+            clearTimeout(inflight.timer);
+            this.clearAbortListener(inflight.signal, inflight.abortListener);
+            inflight.reject(new Error('Transform worker pool closed'));
+            this.inflight.delete(id);
         }
+        for (const task of this.queue)
+            task.reject(new Error('Transform worker pool closed'));
+        this.queue.length = 0;
+        await Promise.allSettled(terminations);
     }
-    markSlotIdle(workerIndex) {
-        const slot = this.workers[workerIndex];
-        if (!slot)
-            return;
-        slot.busy = false;
-        slot.currentTaskId = null;
+    ensureOpen() {
+        if (this.closed)
+            throw new Error('Transform worker pool closed');
     }
-    takeInflight(id) {
-        const inflight = this.inflight.get(id);
-        if (!inflight)
-            return null;
-        clearTimeout(inflight.timer);
-        this.clearAbortListener(inflight.signal, inflight.abortListener);
-        this.inflight.delete(id);
-        return inflight;
+    createPendingTask(html, url, options, resolve, reject) {
+        const id = randomUUID();
+        let abortListener;
+        if (options.signal) {
+            abortListener = () => {
+                this.onAbortSignal(id, url, reject);
+            };
+            options.signal.addEventListener('abort', abortListener, { once: true });
+        }
+        return {
+            id,
+            html,
+            url,
+            includeMetadata: options.includeMetadata,
+            signal: options.signal,
+            abortListener,
+            resolve,
+            reject,
+        };
     }
-    cancelWorkerTask(slot, id) {
-        if (!slot)
+    onAbortSignal(id, url, reject) {
+        if (this.closed) {
+            reject(new Error('Transform worker pool closed'));
             return;
-        try {
-            slot.worker.postMessage({ type: 'cancel', id });
         }
-        catch {
-            /* empty */
-        }
-    }
-    restartWorker(workerIndex, slot) {
-        if (this.closed)
+        const inflight = this.inflight.get(id);
+        if (inflight) {
+            this.abortInflight(id, url, inflight.workerIndex);
             return;
-        const target = slot ?? this.workers[workerIndex];
-        if (target) {
-            void target.worker.terminate();
         }
-        this.workers[workerIndex] = this.spawnWorker(workerIndex);
-        this.drainQueue();
-    }
-    rejectIfClosed(reject) {
-        if (!this.closed)
-            return false;
-        reject(new Error('Transform worker pool closed'));
-        return true;
+        const queuedIndex = this.queue.findIndex((t) => t.id === id);
+        if (queuedIndex !== -1) {
+            this.queue.splice(queuedIndex, 1);
+            reject(abortPolicy.createAbortError(url, 'transform:queued-abort'));
+        }
     }
-    abortInflightTask(id, url, workerIndex) {
+    abortInflight(id, url, workerIndex) {
         const slot = this.workers[workerIndex];
-        this.cancelWorkerTask(slot, id);
-        this.failTask(id, this.createAbortError(url, 'transform:signal-abort'));
         if (slot) {
-            this.restartWorker(workerIndex, slot);
+            try {
+                slot.worker.postMessage({ type: 'cancel', id });
+            }
+            catch {
+                /* ignore */
+            }
         }
+        this.failTask(id, abortPolicy.createAbortError(url, 'transform:signal-abort'));
+        if (slot)
+            this.restartWorker(workerIndex, slot);
     }
-    abortQueuedTask(id, url, reject) {
-        const queuedIndex = this.queue.findIndex((task) => task.id === id);
-        if (queuedIndex === -1)
+    clearAbortListener(signal, listener) {
+        if (!signal || !listener)
             return;
-        this.queue.splice(queuedIndex, 1);
-        reject(this.createAbortError(url, 'transform:queued-abort'));
-    }
-    createWorkerSlot(worker) {
-        return {
-            worker,
-            busy: false,
-            currentTaskId: null,
-        };
+        try {
+            signal.removeEventListener('abort', listener);
+        }
+        catch {
+            /* ignore */
+        }
     }
-    registerWorkerHandlers(workerIndex, worker) {
+    spawnWorker(workerIndex) {
+        const worker = new Worker(new URL('./workers/transform-worker.js', import.meta.url));
+        worker.unref();
         worker.on('message', (raw) => {
             this.onWorkerMessage(workerIndex, raw);
         });
@@ -1176,20 +1123,7 @@ class WorkerPool {
         worker.on('exit', (code) => {
             this.onWorkerBroken(workerIndex, `Transform worker exited (code ${code})`);
         });
-    }
-    constructor(size, timeoutMs) {
-        this.minCapacity = POOL_MIN_WORKERS;
-        this.maxCapacity = POOL_MAX_WORKERS;
-        this.capacity = Math.max(this.minCapacity, Math.min(size, this.maxCapacity));
-        this.timeoutMs = timeoutMs;
-        this.queueMax = this.maxCapacity * 32;
-    }
-    spawnWorker(workerIndex) {
-        const worker = new Worker(new URL('./workers/transform-worker.js', import.meta.url));
-        worker.unref();
-        const slot = this.createWorkerSlot(worker);
-        this.registerWorkerHandlers(workerIndex, worker);
-        return slot;
+        return { worker, busy: false, currentTaskId: null };
     }
     onWorkerBroken(workerIndex, message) {
         if (this.closed)
@@ -1202,19 +1136,14 @@ class WorkerPool {
         }
         this.restartWorker(workerIndex, slot);
     }
-    resolveWorkerResult(inflight, result) {
-        inflight.resolve({
-            markdown: result.markdown,
-            truncated: result.truncated,
-            title: result.title,
-        });
-    }
-    rejectWorkerError(inflight, error) {
-        if (error.name === 'FetchError') {
-            inflight.reject(new FetchError(error.message, error.url, error.statusCode, error.details ?? {}));
+    restartWorker(workerIndex, slot) {
+        if (this.closed)
             return;
-        }
-        inflight.reject(new Error(error.message));
+        const target = slot ?? this.workers[workerIndex];
+        if (target)
+            void target.worker.terminate();
+        this.workers[workerIndex] = this.spawnWorker(workerIndex);
+        this.drainQueue();
     }
     onWorkerMessage(workerIndex, raw) {
         const parsed = workerMessageSchema.safeParse(raw);
@@ -1224,63 +1153,48 @@ class WorkerPool {
         const inflight = this.takeInflight(message.id);
         if (!inflight)
             return;
-        this.markSlotIdle(workerIndex);
+        this.markIdle(workerIndex);
         if (message.type === 'result') {
-            this.resolveWorkerResult(inflight, message.result);
+            inflight.resolve({
+                markdown: message.result.markdown,
+                truncated: message.result.truncated,
+                title: message.result.title,
+            });
         }
         else {
-            this.rejectWorkerError(inflight, message.error);
+            const err = message.error;
+            if (err.name === 'FetchError') {
+                inflight.reject(new FetchError(err.message, err.url, err.statusCode, err.details ?? {}));
+            }
+            else {
+                inflight.reject(new Error(err.message));
+            }
         }
         this.drainQueue();
     }
+    takeInflight(id) {
+        const inflight = this.inflight.get(id);
+        if (!inflight)
+            return null;
+        clearTimeout(inflight.timer);
+        this.clearAbortListener(inflight.signal, inflight.abortListener);
+        this.inflight.delete(id);
+        return inflight;
+    }
+    markIdle(workerIndex) {
+        const slot = this.workers[workerIndex];
+        if (!slot)
+            return;
+        slot.busy = false;
+        slot.currentTaskId = null;
+    }
     failTask(id, error) {
         const inflight = this.takeInflight(id);
         if (!inflight)
             return;
         inflight.reject(error);
-        this.markSlotIdle(inflight.workerIndex);
-    }
-    handleAbortSignal(id, url, reject) {
-        if (this.rejectIfClosed(reject))
-            return;
-        const inflight = this.inflight.get(id);
-        if (inflight) {
-            this.abortInflightTask(id, url, inflight.workerIndex);
-            return;
-        }
-        this.abortQueuedTask(id, url, reject);
-    }
-    createPendingTask(html, url, options, resolve, reject) {
-        const id = randomUUID();
-        let abortListener;
-        if (options.signal) {
-            abortListener = () => {
-                this.handleAbortSignal(id, url, reject);
-            };
-            options.signal.addEventListener('abort', abortListener, { once: true });
-        }
-        return {
-            id,
-            html,
-            url,
-            includeMetadata: options.includeMetadata,
-            signal: options.signal,
-            abortListener,
-            resolve,
-            reject,
-        };
+        this.markIdle(inflight.workerIndex);
     }
-    async transform(html, url, options) {
-        this.ensureOpen();
-        this.ensureNotAborted(options.signal, url, 'transform:enqueue');
-        this.ensureQueueCapacity(url);
-        return new Promise((resolve, reject) => {
-            const task = this.createPendingTask(html, url, options, resolve, reject);
-            this.queue.push(task);
-            this.drainQueue();
-        });
-    }
-    /** Scale capacity up if queue pressure exceeds threshold. */
     maybeScaleUp() {
         if (this.queue.length > this.capacity * POOL_SCALE_THRESHOLD &&
             this.capacity < this.maxCapacity) {
@@ -1288,16 +1202,13 @@ class WorkerPool {
         }
     }
     drainQueue() {
-        if (this.closed)
-            return;
-        if (this.queue.length === 0)
+        if (this.closed || this.queue.length === 0)
             return;
         this.maybeScaleUp();
-        // First pass: try to find an idle existing worker
-        for (let workerIndex = 0; workerIndex < this.workers.length; workerIndex += 1) {
-            const slot = this.workers[workerIndex];
+        for (let i = 0; i < this.workers.length; i += 1) {
+            const slot = this.workers[i];
             if (slot && !slot.busy) {
-                this.dispatchQueueTask(workerIndex, slot);
+                this.dispatchFromQueue(i, slot);
                 if (this.queue.length === 0)
                     return;
             }
@@ -1306,7 +1217,7 @@ class WorkerPool {
             const workerIndex = this.workers.length;
             const slot = this.spawnWorker(workerIndex);
             this.workers.push(slot);
-            this.dispatchQueueTask(workerIndex, slot);
+            this.dispatchFromQueue(workerIndex, slot);
             if (this.workers.length < this.capacity && this.queue.length > 0) {
                 setImmediate(() => {
                     this.drainQueue();
@@ -1314,39 +1225,28 @@ class WorkerPool {
             }
         }
     }
-    dispatchQueueTask(workerIndex, slot) {
+    dispatchFromQueue(workerIndex, slot) {
         const task = this.queue.shift();
         if (!task)
             return;
-        this.dispatch(workerIndex, slot, task);
-    }
-    dispatch(workerIndex, slot, task) {
-        if (this.rejectIfAborted(task))
+        if (this.closed) {
+            task.reject(new Error('Transform worker pool closed'));
             return;
-        this.markSlotBusy(slot, task);
-        const timer = this.startTaskTimer(workerIndex, slot, task);
-        this.registerInflightTask(task, timer, workerIndex);
-        try {
-            this.sendTransformMessage(slot, task);
         }
-        catch (error) {
-            this.handleDispatchFailure(workerIndex, slot, task, timer, error);
+        if (task.signal?.aborted) {
+            this.clearAbortListener(task.signal, task.abortListener);
+            task.reject(abortPolicy.createAbortError(task.url, 'transform:dispatch'));
+            return;
         }
-    }
-    rejectIfAborted(task) {
-        if (!task.signal?.aborted)
-            return false;
-        this.clearAbortListener(task.signal, task.abortListener);
-        task.reject(this.createAbortError(task.url, 'transform:dispatch'));
-        return true;
-    }
-    markSlotBusy(slot, task) {
         slot.busy = true;
         slot.currentTaskId = task.id;
-    }
-    startTaskTimer(workerIndex, slot, task) {
         const timer = setTimeout(() => {
-            this.cancelWorkerTask(slot, task.id);
+            try {
+                slot.worker.postMessage({ type: 'cancel', id: task.id });
+            }
+            catch {
+                /* ignore */
+            }
             const inflight = this.takeInflight(task.id);
             if (!inflight)
                 return;
@@ -1357,9 +1257,6 @@ class WorkerPool {
             this.restartWorker(workerIndex, slot);
         }, this.timeoutMs);
         timer.unref();
-        return timer;
-    }
-    registerInflightTask(task, timer, workerIndex) {
         this.inflight.set(task.id, {
             resolve: task.resolve,
             reject: task.reject,
@@ -1368,58 +1265,56 @@ class WorkerPool {
             abortListener: task.abortListener,
             workerIndex,
         });
+        try {
+            slot.worker.postMessage({
+                type: 'transform',
+                id: task.id,
+                html: task.html,
+                url: task.url,
+                includeMetadata: task.includeMetadata,
+            });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            this.clearAbortListener(task.signal, task.abortListener);
+            this.inflight.delete(task.id);
+            this.markIdle(workerIndex);
+            task.reject(error instanceof Error
+                ? error
+                : new Error('Failed to dispatch transform worker message'));
+            this.restartWorker(workerIndex, slot);
+        }
     }
-    sendTransformMessage(slot, task) {
-        slot.worker.postMessage({
-            type: 'transform',
-            id: task.id,
-            html: task.html,
-            url: task.url,
-            includeMetadata: task.includeMetadata,
-        });
-    }
-    handleDispatchFailure(workerIndex, slot, task, timer, error) {
-        clearTimeout(timer);
-        this.clearAbortListener(task.signal, task.abortListener);
-        this.inflight.delete(task.id);
-        this.markSlotIdle(workerIndex);
-        const message = error instanceof Error
-            ? error
-            : new Error('Failed to dispatch transform worker message');
-        task.reject(message);
-        this.restartWorker(workerIndex, slot);
-    }
-    getQueueDepth() {
-        return this.queue.length;
-    }
-    getActiveWorkers() {
-        return this.workers.filter((s) => s?.busy).length;
+}
+class TransformWorkerPoolManager {
+    pool = null;
+    getOrCreate() {
+        this.pool ??= new WorkerPool(POOL_MIN_WORKERS, DEFAULT_TIMEOUT_MS);
+        return this.pool;
     }
-    getCapacity() {
-        return this.capacity;
+    getStats() {
+        if (!this.pool)
+            return null;
+        return {
+            queueDepth: this.pool.getQueueDepth(),
+            activeWorkers: this.pool.getActiveWorkers(),
+            capacity: this.pool.getCapacity(),
+        };
     }
-    async close() {
-        if (this.closed)
+    async shutdown() {
+        if (!this.pool)
             return;
-        this.closed = true;
-        const terminations = this.workers
-            .map((slot) => slot?.worker.terminate())
-            .filter((p) => p !== undefined);
-        this.workers.fill(undefined);
-        this.workers.length = 0;
-        for (const [id, inflight] of this.inflight.entries()) {
-            clearTimeout(inflight.timer);
-            this.clearAbortListener(inflight.signal, inflight.abortListener);
-            inflight.reject(new Error('Transform worker pool closed'));
-            this.inflight.delete(id);
-        }
-        for (const task of this.queue) {
-            task.reject(new Error('Transform worker pool closed'));
-        }
-        this.queue.length = 0;
-        await Promise.allSettled(terminations);
+        await this.pool.close();
+        this.pool = null;
     }
 }
+const poolManager = new TransformWorkerPoolManager();
+export function getTransformPoolStats() {
+    return poolManager.getStats();
+}
+export async function shutdownTransformWorkerPool() {
+    await poolManager.shutdown();
+}
 function buildWorkerTransformOptions(options) {
     return {
         includeMetadata: options.includeMetadata,
@@ -1427,30 +1322,37 @@ function buildWorkerTransformOptions(options) {
     };
 }
 async function transformWithWorkerPool(html, url, options) {
-    const poolRef = getOrCreateTransformWorkerPool();
-    return poolRef.transform(html, url, buildWorkerTransformOptions(options));
+    const pool = poolManager.getOrCreate();
+    return pool.transform(html, url, buildWorkerTransformOptions(options));
 }
 function resolveWorkerFallback(error, html, url, options) {
-    if (error instanceof FetchError) {
+    if (error instanceof FetchError)
         throw error;
-    }
-    throwIfAborted(options.signal, url, 'transform:worker-fallback');
+    abortPolicy.throwIfAborted(options.signal, url, 'transform:worker-fallback');
     return transformHtmlToMarkdownInProcess(html, url, options);
 }
 export async function transformHtmlToMarkdown(html, url, options) {
-    return runTotalTransformStageAsync(url, async () => {
-        throwIfAborted(options.signal, url, 'transform:begin');
-        const workerStage = startTransformStage(url, 'transform:worker');
+    const totalStage = stageTracker.start(url, 'transform:total');
+    let success = false;
+    try {
+        abortPolicy.throwIfAborted(options.signal, url, 'transform:begin');
+        const workerStage = stageTracker.start(url, 'transform:worker');
         try {
             const result = await transformWithWorkerPool(html, url, options);
+            success = true;
             return result;
         }
         catch (error) {
             const fallback = resolveWorkerFallback(error, html, url, options);
+            success = true;
             return fallback;
         }
         finally {
-            endTransformStage(workerStage);
+            stageTracker.end(workerStage);
         }
-    });
+    }
+    finally {
+        if (success)
+            stageTracker.end(totalStage, { truncated: false });
+    }
 }