@j0hanz/superfetch 2.1.0 → 2.1.1

package/dist/transform.js

@@ -5,15 +5,47 @@ import { performance } from 'node:perf_hooks';
 import { Worker } from 'node:worker_threads';
 import { parseHTML } from 'linkedom';
 import { NodeHtmlMarkdown, } from 'node-html-markdown';
-import { Readability } from '@mozilla/readability';
+import { z } from 'zod';
+import { isProbablyReaderable, Readability } from '@mozilla/readability';
 import { config } from './config.js';
 import { FetchError, getErrorMessage } from './errors.js';
 import { isRawTextContentUrl } from './fetch.js';
 import { getOperationId, getRequestId, logDebug, logError, logInfo, logWarn, redactUrl, } from './observability.js';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
+import { isRecord } from './utils.js';
+function getAbortReason(signal) {
+    if (!isRecord(signal))
+        return undefined;
+    return 'reason' in signal ? signal.reason : undefined;
+}
+function getBodyInnerHtml(document) {
+    if (!isRecord(document))
+        return undefined;
+    const { body } = document;
+    if (!isRecord(body))
+        return undefined;
+    const { innerHTML } = body;
+    return typeof innerHTML === 'string' && innerHTML.length > 0
+        ? innerHTML
+        : undefined;
+}
+function getDocumentToString(document) {
+    if (!isRecord(document))
+        return undefined;
+    if (typeof document.toString !== 'function')
+        return undefined;
+    return document.toString.bind(document);
+}
+function getDocumentElementOuterHtml(document) {
+    if (!isRecord(document))
+        return undefined;
+    const { documentElement } = document;
+    if (!isRecord(documentElement))
+        return undefined;
+    const { outerHTML } = documentElement;
+    return typeof outerHTML === 'string' && outerHTML.length > 0
+        ? outerHTML
+        : undefined;
 }
-const FRONTMATTER_DELIMITER = '---';
 const CODE_BLOCK = {
     fence: '```',
     format: (code, language = '') => {
@@ -59,6 +91,12 @@ export function endTransformStage(context, options) {
     };
     publishTransformEvent(event);
 }
+function runTransformStage(url, stage, fn) {
+    const context = startTransformStage(url, stage);
+    const result = fn();
+    endTransformStage(context);
+    return result;
+}
 function isTimeoutReason(reason) {
     return reason instanceof Error && reason.name === 'TimeoutError';
 }
@@ -68,7 +106,7 @@ function throwIfAborted(signal, url, stage) {
     const { aborted } = signal;
     if (!aborted)
         return;
-    const { reason } = signal;
+    const reason = getAbortReason(signal);
     if (isTimeoutReason(reason)) {
         throw new FetchError('Request timeout', url, 504, {
             reason: 'timeout',
@@ -192,8 +230,18 @@ function extractArticle(document) {
 }
 function parseReadabilityArticle(document) {
     try {
-        // Type assertion is safe here due to isReadabilityCompatible check
-        const reader = new Readability(document);
+        // Readability mutates the document; operate on a clone.
+        const documentClone = document.cloneNode(true);
+        // Avoid the more expensive parse() when the page is unlikely to be readable,
+        // but don't penalize small documents where the heuristic is often too strict.
+        const rawText = documentClone.body.textContent ||
+            documentClone.documentElement.textContent;
+        const textLength = rawText.replace(/\s+/g, ' ').trim().length;
+        if (textLength >= 400 && !isProbablyReaderable(documentClone)) {
+            return null;
+        }
+        // Guard against pathological DOM sizes.
+        const reader = new Readability(documentClone, { maxElemsToParse: 20_000 });
         return reader.parse();
     }
     catch (error) {
@@ -233,45 +281,48 @@ function addOptionalField(target, key, value) {
 export function extractContent(html, url, options = {
     extractArticle: true,
 }) {
+    const emptyResult = createEmptyExtractionResult();
     if (!isValidInput(html, url)) {
-        return { article: null, metadata: {} };
+        return emptyResult;
     }
     return tryExtractContent(html, url, options);
 }
+function createEmptyExtractionResult() {
+    return { article: null, metadata: {} };
+}
+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);
+    return createEmptyExtractionResult();
+}
+function extractContentStages(html, url, options) {
+    throwIfAborted(options.signal, url, 'extract:begin');
+    const { document } = runTransformStage(url, 'extract:parse', () => parseHTML(truncateHtml(html)));
+    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,
+    };
+}
 function tryExtractContent(html, url, options) {
     try {
-        throwIfAborted(options.signal, url, 'extract:begin');
-        const parseStage = startTransformStage(url, 'extract:parse');
-        const { document } = parseHTML(truncateHtml(html));
-        endTransformStage(parseStage);
-        throwIfAborted(options.signal, url, 'extract:parsed');
-        applyBaseUri(document, url);
-        const metadataStage = startTransformStage(url, 'extract:metadata');
-        const metadata = extractMetadata(document);
-        endTransformStage(metadataStage);
-        throwIfAborted(options.signal, url, 'extract:metadata');
-        let article;
-        if (options.extractArticle) {
-            const articleStage = startTransformStage(url, 'extract:article');
-            article = resolveArticleExtraction(document, options.extractArticle);
-            endTransformStage(articleStage);
-        }
-        else {
-            article = null;
-        }
-        throwIfAborted(options.signal, url, 'extract:article');
-        return {
-            article,
-            metadata,
-        };
+        return extractContentStages(html, url, options);
     }
     catch (error) {
-        if (error instanceof FetchError) {
-            throw error;
-        }
-        throwIfAborted(options.signal, url, 'extract:error');
-        logError('Failed to extract content', error instanceof Error ? error : undefined);
-        return { article: null, metadata: {} };
+        return handleExtractionFailure(error, url, options.signal);
     }
 }
 function isValidInput(html, url) {
@@ -563,56 +614,6 @@ export function resolveLanguageFromAttributes(className, dataLang) {
     const classMatch = extractLanguageFromClassName(className);
     return classMatch ?? resolveLanguageFromDataAttribute(dataLang);
 }
-const YAML_SPECIAL_CHARS = /[:[\]{}"\r\t'|>&*!?,#]|\n/;
-const YAML_NUMERIC = /^[\d.]+$/;
-const YAML_RESERVED_WORDS = /^(true|false|null|yes|no|on|off)$/i;
-const ESCAPE_PATTERNS = {
-    backslash: /\\/g,
-    quote: /"/g,
-    newline: /\n/g,
-    tab: /\t/g,
-};
-const YAML_QUOTE_CHECKS = [
-    (input) => YAML_SPECIAL_CHARS.test(input),
-    (input) => input.startsWith(' ') || input.endsWith(' '),
-    (input) => input === '',
-    (input) => YAML_NUMERIC.test(input),
-    (input) => YAML_RESERVED_WORDS.test(input),
-];
-function needsYamlQuotes(value) {
-    return YAML_QUOTE_CHECKS.some((check) => check(value));
-}
-function escapeYamlValue(value) {
-    if (!needsYamlQuotes(value)) {
-        return value;
-    }
-    const escaped = value
-        .replace(ESCAPE_PATTERNS.backslash, '\\\\')
-        .replace(ESCAPE_PATTERNS.quote, '\\"')
-        .replace(ESCAPE_PATTERNS.newline, '\\n')
-        .replace(ESCAPE_PATTERNS.tab, '\\t');
-    return `"${escaped}"`;
-}
-function appendFrontmatterField(lines, key, value) {
-    if (!value)
-        return;
-    lines.push(`${key}: ${escapeYamlValue(value)}`);
-}
-function joinLines(lines) {
-    return lines.join('\n');
-}
-function buildFrontmatter(metadata) {
-    if (!metadata)
-        return '';
-    const lines = [FRONTMATTER_DELIMITER];
-    appendFrontmatterField(lines, 'title', metadata.title);
-    appendFrontmatterField(lines, 'source', metadata.url);
-    appendFrontmatterField(lines, 'author', metadata.author);
-    appendFrontmatterField(lines, 'description', metadata.description);
-    appendFrontmatterField(lines, 'fetchedAt', metadata.fetchedAt);
-    lines.push(FRONTMATTER_DELIMITER);
-    return joinLines(lines);
-}
 function isElement(node) {
     return (isRecord(node) &&
         'getAttribute' in node &&
@@ -623,16 +624,13 @@ const STRUCTURAL_TAGS = new Set([
     'style',
     'noscript',
     'iframe',
-    'nav',
-    'footer',
-    'aside',
-    'header',
     'form',
     'button',
     'input',
     'select',
     'textarea',
 ]);
+const ALWAYS_NOISE_TAGS = new Set(['nav', 'footer', 'aside']);
 const NAVIGATION_ROLES = new Set([
     'navigation',
     'banner',
@@ -641,8 +639,37 @@ const NAVIGATION_ROLES = new Set([
     'tree',
     'menubar',
     'menu',
+    'dialog',
+    'alertdialog',
 ]);
-const PROMO_PATTERN = /banner|promo|announcement|cta|callout|advert|newsletter|subscribe|cookie|consent|popup|modal|overlay|toast/;
+const PROMO_TOKENS = new Set([
+    'banner',
+    'promo',
+    'announcement',
+    'cta',
+    'callout',
+    'advert',
+    'ad',
+    'ads',
+    'sponsor',
+    'newsletter',
+    'subscribe',
+    'cookie',
+    'consent',
+    'popup',
+    'modal',
+    'overlay',
+    'toast',
+    'share',
+    'social',
+    'related',
+    'recommend',
+    'comment',
+    'breadcrumb',
+    'pagination',
+    'pager',
+]);
+const HEADER_NOISE_PATTERN = /\b(site-header|masthead|topbar|navbar|nav(?:bar)?|menu|header-nav)\b/i;
 const FIXED_PATTERN = /\b(fixed|sticky)\b/;
 const HIGH_Z_PATTERN = /\bz-(?:4\d|50)\b/;
 const ISOLATE_PATTERN = /\bisolate\b/;
@@ -711,15 +738,26 @@ function isStructuralNoiseTag(tagName) {
     return (STRUCTURAL_TAGS.has(tagName) || tagName === 'svg' || tagName === 'canvas');
 }
 function isElementHidden(element) {
+    const style = element.getAttribute('style') ?? '';
     return (element.getAttribute('hidden') !== null ||
-        element.getAttribute('aria-hidden') === 'true');
+        element.getAttribute('aria-hidden') === 'true' ||
+        /\bdisplay\s*:\s*none\b/i.test(style) ||
+        /\bvisibility\s*:\s*hidden\b/i.test(style));
 }
 function hasNoiseRole(role) {
     return role !== null && NAVIGATION_ROLES.has(role);
 }
+function tokenizeIdentifierLikeText(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim()
+        .split(' ')
+        .filter(Boolean);
+}
 function matchesPromoIdOrClass(className, id) {
-    const combined = `${className} ${id}`.toLowerCase();
-    return PROMO_PATTERN.test(combined);
+    const tokens = tokenizeIdentifierLikeText(`${className} ${id}`);
+    return tokens.some((token) => PROMO_TOKENS.has(token));
 }
 function matchesHighZIsolate(className) {
     return HIGH_Z_PATTERN.test(className) && ISOLATE_PATTERN.test(className);
@@ -736,42 +774,49 @@ function readElementMetadata(element) {
         isHidden: isElementHidden(element),
     };
 }
+function isBoilerplateHeader({ className, id, role, }) {
+    if (hasNoiseRole(role))
+        return true;
+    const combined = `${className} ${id}`.toLowerCase();
+    return HEADER_NOISE_PATTERN.test(combined);
+}
 function isNoiseElement(node) {
     const metadata = readElementMetadata(node);
     return (isStructuralNoiseTag(metadata.tagName) ||
+        ALWAYS_NOISE_TAGS.has(metadata.tagName) ||
+        (metadata.tagName === 'header' && isBoilerplateHeader(metadata)) ||
         metadata.isHidden ||
         hasNoiseRole(metadata.role) ||
         matchesFixedOrHighZIsolate(metadata.className) ||
         matchesPromoIdOrClass(metadata.className, metadata.id));
 }
+function stripNoiseNodes(document) {
+    const nodes = document.querySelectorAll('*');
+    for (let index = nodes.length - 1; index >= 0; index -= 1) {
+        const node = typeof nodes.item === 'function' ? nodes.item(index) : nodes[index];
+        if (!node)
+            continue;
+        if (isElement(node) && isNoiseElement(node)) {
+            node.remove();
+        }
+    }
+}
 function removeNoiseFromHtml(html) {
     const shouldParse = isFullDocumentHtml(html) || mayContainNoise(html);
     if (!shouldParse)
         return html;
-    const shouldRemove = mayContainNoise(html);
     try {
         const { document } = parseHTML(html);
-        if (shouldRemove) {
-            const nodes = Array.from(document.querySelectorAll('*'));
-            for (let index = nodes.length - 1; index >= 0; index -= 1) {
-                const node = nodes[index];
-                if (!node)
-                    continue;
-                if (isElement(node) && isNoiseElement(node)) {
-                    node.remove();
-                }
-            }
-        }
-        const { body } = document;
-        if (body?.innerHTML)
-            return body.innerHTML;
-        if (typeof document.toString ===
-            'function') {
-            return document.toString();
-        }
-        const { documentElement } = document;
-        if (documentElement?.outerHTML)
-            return documentElement.outerHTML;
+        stripNoiseNodes(document);
+        const bodyInnerHtml = getBodyInnerHtml(document);
+        if (bodyInnerHtml)
+            return bodyInnerHtml;
+        const docToString = getDocumentToString(document);
+        if (docToString)
+            return docToString();
+        const documentElementOuterHtml = getDocumentElementOuterHtml(document);
+        if (documentElementOuterHtml)
+            return documentElementOuterHtml;
         return html;
     }
     catch {
@@ -785,56 +830,110 @@ function buildInlineCode(content) {
     const padding = delimiter.length > 1 ? ' ' : '';
     return `${delimiter}${padding}${content}${padding}${delimiter}`;
 }
+/**
+ * Derive alt text from an image URL by extracting and humanizing the filename.
+ * Used as a fallback when the image has no alt attribute.
+ */
+function deriveAltFromImageUrl(src) {
+    if (!src)
+        return '';
+    try {
+        // Handle both absolute and relative URLs.
+        const pathname = src.startsWith('http')
+            ? new URL(src).pathname
+            : (src.split('?')[0] ?? '');
+        // Extract filename from path.
+        const segments = pathname.split('/');
+        const filename = segments.pop() ?? '';
+        if (!filename)
+            return '';
+        // Remove file extension.
+        const dotIndex = filename.lastIndexOf('.');
+        const name = dotIndex > 0 ? filename.slice(0, dotIndex) : filename;
+        // Humanize: replace separators with spaces.
+        return name.replace(/[_-]+/g, ' ').trim();
+    }
+    catch {
+        return '';
+    }
+}
 function isCodeBlock(parent) {
     if (!isRecord(parent))
         return false;
     const tagName = typeof parent.tagName === 'string' ? parent.tagName.toUpperCase() : '';
     return ['PRE', 'WRAPPED-PRE'].includes(tagName);
 }
-function createCodeTranslator() {
+function hasGetAttribute(value) {
+    return isRecord(value) && typeof value.getAttribute === 'function';
+}
+function hasCodeBlockTranslators(value) {
+    return isRecord(value) && isRecord(value.codeBlockTranslators);
+}
+function buildInlineCodeTranslator() {
     return {
-        code: (ctx) => {
-            if (!isRecord(ctx)) {
-                return {
-                    spaceIfRepeatingChar: true,
-                    noEscape: true,
-                    postprocess: ({ content }) => buildInlineCode(content),
-                };
-            }
-            const { node, parent, visitor } = ctx;
-            const getAttribute = isRecord(node) && typeof node.getAttribute === 'function'
-                ? node.getAttribute.bind(node)
-                : undefined;
-            if (!isCodeBlock(parent)) {
-                return {
-                    spaceIfRepeatingChar: true,
-                    noEscape: true,
-                    postprocess: ({ content }) => buildInlineCode(content),
-                };
-            }
-            const className = getAttribute?.('class') ?? '';
-            const dataLanguage = getAttribute?.('data-language') ?? '';
-            const attributeLanguage = resolveLanguageFromAttributes(className, dataLanguage);
-            const childTranslators = isRecord(visitor) ? visitor.instance : null;
-            const codeBlockTranslators = isRecord(childTranslators) &&
-                isRecord(childTranslators
-                    .codeBlockTranslators)
-                ? childTranslators.codeBlockTranslators
-                : null;
-            return {
-                noEscape: true,
-                preserveWhitespace: true,
-                ...(codeBlockTranslators
-                    ? { childTranslators: codeBlockTranslators }
-                    : null),
-                postprocess: ({ content }) => {
-                    const language = attributeLanguage ?? detectLanguageFromCode(content) ?? '';
-                    return CODE_BLOCK.format(content, language);
-                },
-            };
+        spaceIfRepeatingChar: true,
+        noEscape: true,
+        postprocess: ({ content }) => buildInlineCode(content),
+    };
+}
+function resolveAttributeLanguage(node) {
+    const getAttribute = hasGetAttribute(node)
+        ? node.getAttribute.bind(node)
+        : undefined;
+    const className = getAttribute?.('class') ?? '';
+    const dataLanguage = getAttribute?.('data-language') ?? '';
+    return resolveLanguageFromAttributes(className, dataLanguage);
+}
+function resolveCodeBlockTranslators(visitor) {
+    const childTranslators = isRecord(visitor) ? visitor.instance : null;
+    return hasCodeBlockTranslators(childTranslators)
+        ? childTranslators.codeBlockTranslators
+        : null;
+}
+function buildCodeBlockTranslator(attributeLanguage, codeBlockTranslators) {
+    return {
+        noEscape: true,
+        preserveWhitespace: true,
+        ...(codeBlockTranslators
+            ? { childTranslators: codeBlockTranslators }
+            : null),
+        postprocess: ({ content }) => {
+            const language = attributeLanguage ?? detectLanguageFromCode(content) ?? '';
+            return CODE_BLOCK.format(content, language);
         },
     };
 }
+function buildCodeTranslator(ctx) {
+    if (!isRecord(ctx))
+        return buildInlineCodeTranslator();
+    const { node, parent, visitor } = ctx;
+    if (!isCodeBlock(parent))
+        return buildInlineCodeTranslator();
+    const attributeLanguage = resolveAttributeLanguage(node);
+    const codeBlockTranslators = resolveCodeBlockTranslators(visitor);
+    return buildCodeBlockTranslator(attributeLanguage, codeBlockTranslators);
+}
+function buildImageTranslator(ctx) {
+    if (!isRecord(ctx))
+        return { content: '' };
+    const { node } = ctx;
+    const getAttribute = hasGetAttribute(node)
+        ? node.getAttribute.bind(node)
+        : undefined;
+    const src = getAttribute?.('src') ?? '';
+    const existingAlt = getAttribute?.('alt') ?? '';
+    // Use existing alt text if present, otherwise derive from filename.
+    const alt = existingAlt.trim() || deriveAltFromImageUrl(src);
+    return {
+        content: `![${alt}](${src})`,
+    };
+}
+function createCustomTranslators() {
+    return {
+        code: (ctx) => buildCodeTranslator(ctx),
+        img: (ctx) => buildImageTranslator(ctx),
+    };
+}
 let markdownInstance = null;
 function createMarkdownInstance() {
     return new NodeHtmlMarkdown({
@@ -842,36 +941,86 @@ function createMarkdownInstance() {
         codeBlockStyle: 'fenced',
         emDelimiter: '_',
         bulletMarker: '-',
-    }, createCodeTranslator());
+    }, createCustomTranslators());
 }
 function getMarkdownConverter() {
     markdownInstance ??= createMarkdownInstance();
     return markdownInstance;
 }
+function translateHtmlToMarkdown(html, url, signal) {
+    throwIfAborted(signal, url, 'markdown:begin');
+    const cleanedHtml = runTransformStage(url, 'markdown:noise', () => removeNoiseFromHtml(html));
+    throwIfAborted(signal, url, 'markdown:cleaned');
+    const content = runTransformStage(url, 'markdown:translate', () => getMarkdownConverter().translate(cleanedHtml).trim());
+    throwIfAborted(signal, url, 'markdown:translated');
+    // Post-process the markdown to clean up common conversion artifacts.
+    return cleanupMarkdownArtifacts(content);
+}
+function appendMetadataFooter(content, metadata, url) {
+    // Metadata is placed as a footer to avoid duplicating titles when the
+    // article content already contains an H1 heading at the top.
+    const footer = buildMetadataFooter(metadata, url);
+    return footer ? `${content}\n\n${footer}` : content;
+}
 export function htmlToMarkdown(html, metadata, options) {
     const url = options?.url ?? metadata?.url ?? '';
-    const frontmatter = buildFrontmatter(metadata);
     if (!html)
-        return frontmatter;
+        return buildMetadataFooter(metadata, url);
     try {
-        throwIfAborted(options?.signal, url, 'markdown:begin');
-        const noiseStage = startTransformStage(url, 'markdown:noise');
-        const cleanedHtml = removeNoiseFromHtml(html);
-        endTransformStage(noiseStage);
-        throwIfAborted(options?.signal, url, 'markdown:cleaned');
-        const translateStage = startTransformStage(url, 'markdown:translate');
-        const content = getMarkdownConverter().translate(cleanedHtml).trim();
-        endTransformStage(translateStage);
-        throwIfAborted(options?.signal, url, 'markdown:translated');
-        return frontmatter ? `${frontmatter}\n${content}` : content;
+        const content = translateHtmlToMarkdown(html, url, options?.signal);
+        return appendMetadataFooter(content, metadata, url);
     }
     catch (error) {
         if (error instanceof FetchError) {
             throw error;
         }
-        return frontmatter;
+        return buildMetadataFooter(metadata, url);
     }
 }
+/**
+ * Clean up common markdown conversion artifacts:
+ * - Empty headings (e.g., "## " with no text)
+ * - Anchor-only links like [ ](#section-id) used for navigation
+ * - Concatenated links without spacing
+ * - Boilerplate phrases like "Was this page helpful?"
+ */
+function cleanupMarkdownArtifacts(content) {
+    let result = content;
+    // Remove empty Markdown headings like "## " produced by placeholder nodes.
+    result = result.replace(/^#{1,6}[ \t\u00A0]*$\r?\n?/gm, '');
+    // Remove anchor-only links like [\u200B](#section-id) or [ ](#anchor).
+    // These are navigation remnants with zero-width or whitespace text.
+    // Match: [ or whitespace or zero-width space ](#...)
+    const zeroWidthAnchorLink = /\[(?:\s|\u200B)*\]\(#[^)]*\)\s*/g;
+    result = result.replace(zeroWidthAnchorLink, '');
+    // Add line breaks between concatenated links: ](url)[text] -> ](url)\n\n[text]
+    result = result.replace(/\]\(([^)]+)\)\[/g, ']($1)\n\n[');
+    // Remove common boilerplate phrases.
+    result = result.replace(/^Was this page helpful\??\s*$/gim, '');
+    // Collapse multiple blank lines into at most two.
+    result = result.replace(/\n{3,}/g, '\n\n');
+    return result.trim();
+}
+function buildMetadataFooter(metadata, fallbackUrl) {
+    if (!metadata)
+        return '';
+    const lines = [];
+    // Horizontal rule as a clear footer separator.
+    lines.push('---');
+    if (metadata.title)
+        lines.push(`**Title:** ${metadata.title}`);
+    if (metadata.description)
+        lines.push(`**Description:** ${metadata.description}`);
+    if (metadata.author)
+        lines.push(`**Author:** ${metadata.author}`);
+    if (metadata.url)
+        lines.push(`**Source:** ${metadata.url}`);
+    else if (fallbackUrl)
+        lines.push(`**Source:** ${fallbackUrl}`);
+    if (metadata.fetchedAt)
+        lines.push(`**Fetched:** ${metadata.fetchedAt}`);
+    return lines.join('\n');
+}
 const HEADING_PATTERN = /^#{1,6}\s/m;
 const LIST_PATTERN = /^(?:[-*+])\s/m;
 const HTML_DOCUMENT_PATTERN = /^(<!doctype|<html)/i;
@@ -895,6 +1044,7 @@ function looksLikeMarkdown(content) {
 function detectLineEnding(content) {
     return content.includes('\r\n') ? '\r\n' : '\n';
 }
+const FRONTMATTER_DELIMITER = '---';
 function findFrontmatterLines(content) {
     const lineEnding = detectLineEnding(content);
     const lines = content.split(lineEnding);
@@ -930,10 +1080,32 @@ function parseFrontmatterEntry(line) {
 function isTitleKey(key) {
     return key === 'title' || key === 'name';
 }
+function extractTitleFromHeading(content) {
+    const lineEnding = detectLineEnding(content);
+    const lines = content.split(lineEnding);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let index = 0;
+        while (index < trimmed.length && trimmed[index] === '#') {
+            index += 1;
+        }
+        if (index === 0 || index > 6)
+            return undefined;
+        const nextChar = trimmed[index];
+        if (nextChar !== ' ' && nextChar !== '\t')
+            return undefined;
+        const heading = trimmed.slice(index).trim();
+        return heading.length > 0 ? heading : undefined;
+    }
+    return undefined;
+}
 function extractTitleFromRawMarkdown(content) {
     const frontmatter = findFrontmatterLines(content);
-    if (!frontmatter)
-        return undefined;
+    if (!frontmatter) {
+        return extractTitleFromHeading(content);
+    }
     const { lines, endIndex } = frontmatter;
     const entry = lines
         .slice(1, endIndex)
@@ -944,8 +1116,48 @@ function extractTitleFromRawMarkdown(content) {
     const value = stripOptionalQuotes(entry.value);
     return value || undefined;
 }
+function hasMarkdownSourceLine(content) {
+    const lineEnding = detectLineEnding(content);
+    const lines = content.split(lineEnding);
+    // Only scan a small prefix to avoid wasting time on huge docs.
+    const limit = Math.min(lines.length, 50);
+    for (let index = 0; index < limit; index += 1) {
+        const line = lines[index];
+        if (!line)
+            continue;
+        if (line.trimStart().toLowerCase().startsWith('source:')) {
+            return true;
+        }
+    }
+    return false;
+}
+function addSourceToMarkdownMarkdownFormat(content, url) {
+    if (hasMarkdownSourceLine(content))
+        return content;
+    const lineEnding = detectLineEnding(content);
+    const lines = content.split(lineEnding);
+    const firstNonEmptyIndex = lines.findIndex((line) => line.trim().length > 0);
+    if (firstNonEmptyIndex !== -1) {
+        const firstLine = lines[firstNonEmptyIndex];
+        if (firstLine && /^#{1,6}\s+/.test(firstLine.trim())) {
+            const insertAt = firstNonEmptyIndex + 1;
+            const updated = [
+                ...lines.slice(0, insertAt),
+                '',
+                `Source: ${url}`,
+                '',
+                ...lines.slice(insertAt),
+            ];
+            return updated.join(lineEnding);
+        }
+    }
+    return [`Source: ${url}`, '', content].join(lineEnding);
+}
 function addSourceToMarkdown(content, url) {
     const frontmatter = findFrontmatterLines(content);
+    if (config.transform.metadataFormat === 'markdown' && !frontmatter) {
+        return addSourceToMarkdownMarkdownFormat(content, url);
+    }
     if (!frontmatter) {
         return `---\nsource: "${url}"\n---\n\n${content}`;
     }
@@ -1086,19 +1298,11 @@ export function createContentMetadataBlock(url, article, extractedMeta, shouldEx
     applyExtractedMetadata(metadata, extractedMeta);
     return metadata;
 }
-function buildArticleContentSource({ url, article, extractedMeta, includeMetadata, }) {
-    const metadata = createContentMetadataBlock(url, article, extractedMeta, true, includeMetadata);
+function buildContentSource({ html, url, article, extractedMeta, includeMetadata, useArticleContent, }) {
+    const metadata = createContentMetadataBlock(url, article, extractedMeta, useArticleContent, includeMetadata);
     return {
-        sourceHtml: article.content,
-        title: article.title,
-        metadata,
-    };
-}
-function buildFullHtmlContentSource({ html, url, article, extractedMeta, includeMetadata, }) {
-    const metadata = createContentMetadataBlock(url, article, extractedMeta, false, includeMetadata);
-    return {
-        sourceHtml: html,
-        title: extractedMeta.title,
+        sourceHtml: useArticleContent && article ? article.content : html,
+        title: useArticleContent && article ? article.title : extractedMeta.title,
         metadata,
     };
 }
@@ -1108,84 +1312,83 @@ function logQualityGateFallback({ url, articleLength, }) {
         articleLength,
     });
 }
-function tryBuildExtractedArticleContentSource({ html, url, article, extractedMeta, includeMetadata, }) {
-    if (!article)
-        return null;
+function shouldUseArticleContent(article, html, url) {
     const shouldExtractFromArticle = determineContentExtractionSource(article);
-    if (shouldExtractFromArticle && isExtractionSufficient(article, html)) {
-        return buildArticleContentSource({
-            url,
-            article,
-            extractedMeta,
-            includeMetadata,
-        });
-    }
-    if (shouldExtractFromArticle) {
-        logQualityGateFallback({
-            url,
-            articleLength: article.textContent.length,
-        });
+    if (!shouldExtractFromArticle)
+        return false;
+    if (isExtractionSufficient(article, html)) {
+        return true;
     }
-    return null;
+    logQualityGateFallback({
+        url,
+        articleLength: article.textContent.length,
+    });
+    return false;
 }
 function resolveContentSource({ html, url, includeMetadata, signal, }) {
     const { article, metadata: extractedMeta } = extractContent(html, url, {
         extractArticle: true,
         ...(signal ? { signal } : {}),
     });
-    const extracted = tryBuildExtractedArticleContentSource({
+    const useArticleContent = article
+        ? shouldUseArticleContent(article, html, url)
+        : false;
+    return buildContentSource({
         html,
         url,
         article,
         extractedMeta,
         includeMetadata,
+        useArticleContent,
     });
-    if (extracted)
-        return extracted;
-    return buildFullHtmlContentSource({
+}
+function tryTransformRawStage(html, url, includeMetadata) {
+    return runTransformStage(url, 'transform:raw', () => tryTransformRawContent({
         html,
         url,
-        article,
-        extractedMeta,
         includeMetadata,
-    });
+    }));
 }
-export function transformHtmlToMarkdownInProcess(html, url, options) {
+function resolveContentSourceStage(html, url, includeMetadata, signal) {
+    return runTransformStage(url, 'transform:extract', () => resolveContentSource({
+        html,
+        url,
+        includeMetadata,
+        ...(signal ? { signal } : {}),
+    }));
+}
+function buildMarkdownFromContext(context, url, signal) {
+    const content = runTransformStage(url, 'transform:markdown', () => htmlToMarkdown(context.sourceHtml, context.metadata, {
+        url,
+        ...(signal ? { signal } : {}),
+    }));
+    return {
+        markdown: content,
+        title: context.title,
+        truncated: false,
+    };
+}
+function runTotalTransformStage(url, fn) {
     const totalStage = startTransformStage(url, 'transform:total');
     let success = false;
     try {
-        throwIfAborted(options.signal, url, 'transform:begin');
-        const rawStage = startTransformStage(url, 'transform:raw');
-        const raw = tryTransformRawContent({
-            html,
-            url,
-            includeMetadata: options.includeMetadata,
-        });
-        endTransformStage(rawStage);
-        if (raw) {
-            success = true;
-            return raw;
+        const result = fn();
+        success = true;
+        return result;
+    }
+    finally {
+        if (success) {
+            endTransformStage(totalStage, { truncated: false });
         }
-        const extractStage = startTransformStage(url, 'transform:extract');
-        const context = resolveContentSource({
-            html,
-            url,
-            includeMetadata: options.includeMetadata,
-            ...(options.signal ? { signal: options.signal } : {}),
-        });
-        endTransformStage(extractStage);
-        const markdownStage = startTransformStage(url, 'transform:markdown');
-        const content = htmlToMarkdown(context.sourceHtml, context.metadata, {
-            url,
-            ...(options.signal ? { signal: options.signal } : {}),
-        });
-        endTransformStage(markdownStage);
+    }
+}
+async function runTotalTransformStageAsync(url, fn) {
+    const totalStage = startTransformStage(url, 'transform:total');
+    let success = false;
+    try {
+        const result = await fn();
         success = true;
-        return {
-            markdown: content,
-            title: context.title,
-            truncated: false,
-        };
+        return result;
     }
     finally {
         if (success) {
@@ -1193,15 +1396,47 @@ export function transformHtmlToMarkdownInProcess(html, url, options) {
         }
     }
 }
+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);
+    });
+}
+const workerMessageSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('result'),
+        id: z.string(),
+        result: z.object({
+            markdown: z.string(),
+            title: z.string().optional(),
+            truncated: z.boolean(),
+        }),
+    }),
+    z.object({
+        type: z.literal('error'),
+        id: z.string(),
+        error: z.object({
+            name: z.string(),
+            message: z.string(),
+            url: z.string(),
+            statusCode: z.number().optional(),
+            details: z.record(z.string(), z.unknown()).optional(),
+        }),
+    }),
+]);
 let pool = null;
 function resolveDefaultWorkerCount() {
     const parallelism = typeof os.availableParallelism === 'function'
         ? os.availableParallelism()
         : os.cpus().length;
-    // Leave 1 core for the event loop; cap to avoid runaway memory.
     return Math.min(16, Math.max(1, parallelism - 1));
 }
-const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_TIMEOUT_MS = config.transform.timeoutMs;
 function getOrCreateTransformWorkerPool() {
     pool ??= new WorkerPool(resolveDefaultWorkerCount(), DEFAULT_TIMEOUT_MS);
     return pool;
@@ -1219,23 +1454,108 @@ class WorkerPool {
     timeoutMs;
     queueMax;
     closed = false;
-    constructor(size, timeoutMs) {
-        const safeSize = Math.max(1, size);
-        this.timeoutMs = timeoutMs;
-        this.queueMax = safeSize * 2;
-        for (let index = 0; index < safeSize; index += 1) {
-            this.workers.push(this.spawnWorker(index));
+    ensureOpen() {
+        if (this.closed) {
+            throw new Error('Transform worker pool closed');
         }
     }
-    spawnWorker(workerIndex) {
-        const worker = new Worker(new URL('./workers/transform-worker.js', import.meta.url));
-        // Workers must not keep the process alive by themselves.
-        worker.unref();
-        const slot = {
+    ensureNotAborted(signal, url, stage) {
+        if (!signal?.aborted)
+            return;
+        throw new FetchError('Request was canceled', url, 499, {
+            reason: 'aborted',
+            stage,
+        });
+    }
+    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',
+        });
+    }
+    clearAbortListener(signal, listener) {
+        if (!signal || !listener)
+            return;
+        try {
+            signal.removeEventListener('abort', listener);
+        }
+        catch {
+            // ignore
+        }
+    }
+    markSlotIdle(workerIndex) {
+        const slot = this.workers[workerIndex];
+        if (!slot)
+            return;
+        slot.busy = false;
+        slot.currentTaskId = null;
+    }
+    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;
+    }
+    cancelWorkerTask(slot, id) {
+        if (!slot)
+            return;
+        try {
+            slot.worker.postMessage({ type: 'cancel', id });
+        }
+        catch {
+            // ignore
+        }
+    }
+    restartWorker(workerIndex, slot) {
+        if (this.closed)
+            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;
+    }
+    abortInflightTask(id, url, workerIndex) {
+        const slot = this.workers[workerIndex];
+        this.cancelWorkerTask(slot, id);
+        this.failTask(id, new FetchError('Request was canceled', url, 499, {
+            reason: 'aborted',
+            stage: '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)
+            return;
+        this.queue.splice(queuedIndex, 1);
+        reject(new FetchError('Request was canceled', url, 499, {
+            reason: 'aborted',
+            stage: 'transform:queued-abort',
+        }));
+    }
+    createWorkerSlot(worker) {
+        return {
             worker,
             busy: false,
             currentTaskId: null,
         };
+    }
+    registerWorkerHandlers(workerIndex, worker) {
         worker.on('message', (raw) => {
             this.onWorkerMessage(workerIndex, raw);
         });
@@ -1245,6 +1565,21 @@ class WorkerPool {
         worker.on('exit', (code) => {
             this.onWorkerBroken(workerIndex, `Transform worker exited (code ${code})`);
         });
+    }
+    constructor(size, timeoutMs) {
+        const safeSize = Math.max(1, size);
+        this.timeoutMs = timeoutMs;
+        this.queueMax = safeSize * 2;
+        for (let index = 0; index < safeSize; index += 1) {
+            this.workers.push(this.spawnWorker(index));
+        }
+    }
+    spawnWorker(workerIndex) {
+        const worker = new Worker(new URL('./workers/transform-worker.js', import.meta.url));
+        // Workers must not keep the process alive by themselves.
+        worker.unref();
+        const slot = this.createWorkerSlot(worker);
+        this.registerWorkerHandlers(workerIndex, worker);
         return slot;
     }
     onWorkerBroken(workerIndex, message) {
@@ -1256,129 +1591,83 @@ class WorkerPool {
         if (slot.busy && slot.currentTaskId) {
             this.failTask(slot.currentTaskId, new Error(message));
         }
-        void slot.worker.terminate();
-        this.workers[workerIndex] = this.spawnWorker(workerIndex);
-        this.drainQueue();
+        this.restartWorker(workerIndex, slot);
     }
-    onWorkerMessage(workerIndex, raw) {
-        if (!raw ||
-            typeof raw !== 'object' ||
-            !('type' in raw) ||
-            !('id' in raw) ||
-            typeof raw.id !== 'string' ||
-            typeof raw.type !== 'string') {
+    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 ?? {}));
             return;
         }
-        const message = raw;
-        const inflight = this.inflight.get(message.id);
+        inflight.reject(new Error(error.message));
+    }
+    onWorkerMessage(workerIndex, raw) {
+        const parsed = workerMessageSchema.safeParse(raw);
+        if (!parsed.success)
+            return;
+        const message = parsed.data;
+        const inflight = this.takeInflight(message.id);
         if (!inflight)
             return;
-        clearTimeout(inflight.timer);
-        if (inflight.signal && inflight.abortListener) {
-            inflight.signal.removeEventListener('abort', inflight.abortListener);
-        }
-        this.inflight.delete(message.id);
-        const slot = this.workers[workerIndex];
-        if (slot) {
-            slot.busy = false;
-            slot.currentTaskId = null;
-        }
+        this.markSlotIdle(workerIndex);
         if (message.type === 'result') {
-            inflight.resolve(message.result);
+            this.resolveWorkerResult(inflight, message.result);
         }
         else {
-            const { error } = message;
-            if (error.name === 'FetchError') {
-                inflight.reject(new FetchError(error.message, error.url, error.statusCode, error.details ?? {}));
-            }
-            else {
-                inflight.reject(new Error(error.message));
-            }
+            this.rejectWorkerError(inflight, message.error);
         }
         this.drainQueue();
     }
     failTask(id, error) {
-        const inflight = this.inflight.get(id);
+        const inflight = this.takeInflight(id);
         if (!inflight)
             return;
-        clearTimeout(inflight.timer);
-        if (inflight.signal && inflight.abortListener) {
-            inflight.signal.removeEventListener('abort', inflight.abortListener);
-        }
-        this.inflight.delete(id);
         inflight.reject(error);
-        const slot = this.workers[inflight.workerIndex];
-        if (slot) {
-            slot.busy = false;
-            slot.currentTaskId = null;
-        }
+        this.markSlotIdle(inflight.workerIndex);
     }
-    async transform(html, url, options) {
-        if (this.closed) {
-            throw new Error('Transform worker pool closed');
-        }
-        if (options.signal?.aborted) {
-            throw new FetchError('Request was canceled', url, 499, {
-                reason: 'aborted',
-                stage: 'transform:enqueue',
-            });
+    handleAbortSignal(id, url, reject) {
+        if (this.rejectIfClosed(reject))
+            return;
+        const inflight = this.inflight.get(id);
+        if (inflight) {
+            this.abortInflightTask(id, url, inflight.workerIndex);
+            return;
         }
-        if (this.queue.length >= this.queueMax) {
-            throw new Error('Transform worker queue is full');
+        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,
+        };
+    }
+    async transform(html, url, options) {
+        this.ensureOpen();
+        this.ensureNotAborted(options.signal, url, 'transform:enqueue');
+        this.ensureQueueCapacity(url);
         return new Promise((resolve, reject) => {
-            const id = randomUUID();
-            let abortListener;
-            if (options.signal) {
-                abortListener = () => {
-                    if (this.closed) {
-                        reject(new Error('Transform worker pool closed'));
-                        return;
-                    }
-                    const inflight = this.inflight.get(id);
-                    if (inflight) {
-                        const { workerIndex } = inflight;
-                        const slot = this.workers[workerIndex];
-                        if (slot) {
-                            try {
-                                slot.worker.postMessage({ type: 'cancel', id });
-                            }
-                            catch {
-                                // ignore
-                            }
-                        }
-                        this.failTask(id, new FetchError('Request was canceled', url, 499, {
-                            reason: 'aborted',
-                            stage: 'transform:signal-abort',
-                        }));
-                        if (slot) {
-                            void slot.worker.terminate();
-                            this.workers[workerIndex] = this.spawnWorker(workerIndex);
-                            this.drainQueue();
-                        }
-                        return;
-                    }
-                    const queuedIndex = this.queue.findIndex((task) => task.id === id);
-                    if (queuedIndex !== -1) {
-                        this.queue.splice(queuedIndex, 1);
-                        reject(new FetchError('Request was canceled', url, 499, {
-                            reason: 'aborted',
-                            stage: 'transform:queued-abort',
-                        }));
-                    }
-                };
-                options.signal.addEventListener('abort', abortListener, { once: true });
-            }
-            this.queue.push({
-                id,
-                html,
-                url,
-                includeMetadata: options.includeMetadata,
-                signal: options.signal,
-                abortListener,
-                resolve,
-                reject,
-            });
+            const task = this.createPendingTask(html, url, options, resolve, reject);
+            this.queue.push(task);
             this.drainQueue();
         });
     }
@@ -1398,43 +1687,48 @@ class WorkerPool {
         }
     }
     dispatch(workerIndex, slot, task) {
-        if (task.signal?.aborted) {
-            if (task.abortListener) {
-                task.signal.removeEventListener('abort', task.abortListener);
-            }
-            task.reject(new FetchError('Request was canceled', task.url, 499, {
-                reason: 'aborted',
-                stage: 'transform:dispatch',
-            }));
+        if (this.rejectIfAborted(task))
             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);
         }
+    }
+    rejectIfAborted(task) {
+        if (!task.signal?.aborted)
+            return false;
+        this.clearAbortListener(task.signal, task.abortListener);
+        task.reject(new FetchError('Request was canceled', task.url, 499, {
+            reason: 'aborted',
+            stage: 'transform:dispatch',
+        }));
+        return true;
+    }
+    markSlotBusy(slot, task) {
         slot.busy = true;
         slot.currentTaskId = task.id;
+    }
+    startTaskTimer(workerIndex, slot, task) {
         const timer = setTimeout(() => {
-            try {
-                slot.worker.postMessage({ type: 'cancel', id: task.id });
-            }
-            catch {
-                // ignore
-            }
-            const inflight = this.inflight.get(task.id);
+            this.cancelWorkerTask(slot, task.id);
+            const inflight = this.takeInflight(task.id);
             if (!inflight)
                 return;
-            clearTimeout(inflight.timer);
-            if (inflight.signal && inflight.abortListener) {
-                inflight.signal.removeEventListener('abort', inflight.abortListener);
-            }
-            this.inflight.delete(task.id);
             inflight.reject(new FetchError('Request timeout', task.url, 504, {
                 reason: 'timeout',
                 stage: 'transform:worker-timeout',
             }));
-            if (!this.closed) {
-                void slot.worker.terminate();
-                this.workers[workerIndex] = this.spawnWorker(workerIndex);
-                this.drainQueue();
-            }
-        }, this.timeoutMs).unref();
+            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,
@@ -1443,6 +1737,8 @@ class WorkerPool {
             abortListener: task.abortListener,
             workerIndex,
         });
+    }
+    sendTransformMessage(slot, task) {
         slot.worker.postMessage({
             type: 'transform',
             id: task.id,
@@ -1451,6 +1747,17 @@ class WorkerPool {
             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);
+    }
     async close() {
         if (this.closed)
             return;
@@ -1459,9 +1766,7 @@ class WorkerPool {
         this.workers.length = 0;
         for (const [id, inflight] of this.inflight.entries()) {
             clearTimeout(inflight.timer);
-            if (inflight.signal && inflight.abortListener) {
-                inflight.signal.removeEventListener('abort', inflight.abortListener);
-            }
+            this.clearAbortListener(inflight.signal, inflight.abortListener);
             inflight.reject(new Error('Transform worker pool closed'));
             this.inflight.delete(id);
         }
@@ -1472,38 +1777,38 @@ class WorkerPool {
         await Promise.allSettled(terminations);
     }
 }
+function buildWorkerTransformOptions(options) {
+    return {
+        includeMetadata: options.includeMetadata,
+        ...(options.signal ? { signal: options.signal } : {}),
+    };
+}
+async function transformWithWorkerPool(html, url, options) {
+    const poolRef = getOrCreateTransformWorkerPool();
+    return poolRef.transform(html, url, buildWorkerTransformOptions(options));
+}
+function resolveWorkerFallback(error, html, url, options) {
+    if (error instanceof FetchError) {
+        throw error;
+    }
+    // Stability-first: if worker infrastructure fails, fall back to in-process.
+    throwIfAborted(options.signal, url, 'transform:worker-fallback');
+    return transformHtmlToMarkdownInProcess(html, url, options);
+}
 export async function transformHtmlToMarkdown(html, url, options) {
-    const totalStage = startTransformStage(url, 'transform:total');
-    let success = false;
-    try {
+    return runTotalTransformStageAsync(url, async () => {
         throwIfAborted(options.signal, url, 'transform:begin');
         const workerStage = startTransformStage(url, 'transform:worker');
         try {
-            const poolRef = getOrCreateTransformWorkerPool();
-            const result = await poolRef.transform(html, url, {
-                includeMetadata: options.includeMetadata,
-                ...(options.signal ? { signal: options.signal } : {}),
-            });
-            success = true;
+            const result = await transformWithWorkerPool(html, url, options);
             return result;
         }
         catch (error) {
-            if (error instanceof FetchError) {
-                throw error;
-            }
-            // Stability-first: if worker infrastructure fails, fall back to in-process.
-            throwIfAborted(options.signal, url, 'transform:worker-fallback');
-            const fallback = transformHtmlToMarkdownInProcess(html, url, options);
-            success = true;
+            const fallback = resolveWorkerFallback(error, html, url, options);
             return fallback;
         }
         finally {
             endTransformStage(workerStage);
         }
-    }
-    finally {
-        if (success) {
-            endTransformStage(totalStage, { truncated: false });
-        }
-    }
+    });
 }