@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/llm-wiki/deps/baoyu-url-to-markdown/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: baoyu-url-to-markdown
+description: Fetch any URL and convert to markdown using Chrome CDP. Saves the rendered HTML snapshot alongside the markdown, uses an upgraded Defuddle pipeline with better web-component handling and YouTube transcript extraction, and automatically falls back to the pre-Defuddle HTML-to-Markdown pipeline when needed. If local browser capture fails entirely, it can fall back to the hosted defuddle.md API. Supports two modes - auto-capture on page load, or wait for user signal (for pages requiring login). Use when user wants to save a webpage as markdown.
+version: 1.58.1
+metadata:
+  openclaw:
+    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-url-to-markdown
+    requires:
+      anyBins:
+        - bun
+        - npx
+---
+
+# URL to Markdown
+
+Fetches any URL via Chrome CDP, saves the rendered HTML snapshot, and converts it to clean markdown.
+
+## Script Directory
+
+**Important**: All scripts are located in the `scripts/` subdirectory of this skill.
+
+**Agent Execution Instructions**:
+1. Determine this SKILL.md file's directory path as `{baseDir}`
+2. Script path = `{baseDir}/scripts/<script-name>.ts`
+3. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun
+4. Replace all `{baseDir}` and `${BUN_X}` in this document with actual values
+
+**Script Reference**:
+| Script | Purpose |
+|--------|---------|
+| `scripts/main.ts` | CLI entry point for URL fetching |
+| `scripts/html-to-markdown.ts` | Markdown conversion entry point and converter selection |
+| `scripts/defuddle-converter.ts` | Defuddle-based conversion |
+| `scripts/legacy-converter.ts` | Pre-Defuddle legacy extraction and markdown conversion |
+| `scripts/markdown-conversion-shared.ts` | Shared metadata parsing and markdown document helpers |
+
+## Preferences (EXTEND.md)
+
+Check EXTEND.md existence (priority order):
+
+```bash
+# macOS, Linux, WSL, Git Bash
+test -f .baoyu-skills/baoyu-url-to-markdown/EXTEND.md && echo "project"
+test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-url-to-markdown/EXTEND.md" && echo "xdg"
+test -f "$HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md" && echo "user"
+```
+
+```powershell
+# PowerShell (Windows)
+if (Test-Path .baoyu-skills/baoyu-url-to-markdown/EXTEND.md) { "project" }
+$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
+if (Test-Path "$xdg/baoyu-skills/baoyu-url-to-markdown/EXTEND.md") { "xdg" }
+if (Test-Path "$HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md") { "user" }
+```
+
+┌────────────────────────────────────────────────────────┬───────────────────┐
+│                          Path                          │     Location      │
+├────────────────────────────────────────────────────────┼───────────────────┤
+│ .baoyu-skills/baoyu-url-to-markdown/EXTEND.md          │ Project directory │
+├────────────────────────────────────────────────────────┼───────────────────┤
+│ $HOME/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md    │ User home         │
+└────────────────────────────────────────────────────────┴───────────────────┘
+
+┌───────────┬───────────────────────────────────────────────────────────────────────────┐
+│  Result   │                                  Action                                   │
+├───────────┼───────────────────────────────────────────────────────────────────────────┤
+│ Found     │ Read, parse, apply settings                                               │
+├───────────┼───────────────────────────────────────────────────────────────────────────┤
+│ Not found │ **MUST** run first-time setup (see below) — do NOT silently create defaults │
+└───────────┴───────────────────────────────────────────────────────────────────────────┘
+
+**EXTEND.md Supports**: Download media by default | Default output directory | Default capture mode | Timeout settings
+
+### First-Time Setup (BLOCKING)
+
+**CRITICAL**: When EXTEND.md is not found, you **MUST use `AskUserQuestion`** to ask the user for their preferences before creating EXTEND.md. **NEVER** create EXTEND.md with defaults without asking. This is a **BLOCKING** operation — do NOT proceed with any conversion until setup is complete.
+
+Use `AskUserQuestion` with ALL questions in ONE call:
+
+**Question 1** — header: "Media", question: "How to handle images and videos in pages?"
+- "Ask each time (Recommended)" — After saving markdown, ask whether to download media
+- "Always download" — Always download media to local imgs/ and videos/ directories
+- "Never download" — Keep original remote URLs in markdown
+
+**Question 2** — header: "Output", question: "Default output directory?"
+- "url-to-markdown (Recommended)" — Save to ./url-to-markdown/{domain}/{slug}.md
+- (User may choose "Other" to type a custom path)
+
+**Question 3** — header: "Save", question: "Where to save preferences?"
+- "User (Recommended)" — ~/.baoyu-skills/ (all projects)
+- "Project" — .baoyu-skills/ (this project only)
+
+After user answers, create EXTEND.md at the chosen location, confirm "Preferences saved to [path]", then continue.
+
+Full reference: [references/config/first-time-setup.md](references/config/first-time-setup.md)
+
+### Supported Keys
+
+| Key | Default | Values | Description |
+|-----|---------|--------|-------------|
+| `download_media` | `ask` | `ask` / `1` / `0` | `ask` = prompt each time, `1` = always download, `0` = never |
+| `default_output_dir` | empty | path or empty | Default output directory (empty = `./url-to-markdown/`) |
+
+**EXTEND.md → CLI mapping**:
+| EXTEND.md key | CLI argument | Notes |
+|---------------|-------------|-------|
+| `download_media: 1` | `--download-media` | |
+| `default_output_dir: ./posts/` | `--output-dir ./posts/` | Directory path. Do NOT pass to `-o` (which expects a file path) |
+
+**Value priority**:
+1. CLI arguments (`--download-media`, `-o`, `--output-dir`)
+2. EXTEND.md
+3. Skill defaults
+
+## Features
+
+- Chrome CDP for full JavaScript rendering
+- Two capture modes: auto or wait-for-user
+- Save rendered HTML as a sibling `-captured.html` file
+- Clean markdown output with metadata
+- Upgraded Defuddle-first markdown conversion with automatic fallback to the pre-Defuddle extractor from git history
+- Materializes shadow DOM content before conversion so web-component pages survive serialization better
+- YouTube pages can include transcript/caption text in the markdown when YouTube exposes a caption track
+- If local browser capture fails completely, can fall back to `defuddle.md/<url>` and still save markdown
+- Handles login-required pages via wait mode
+- Download images and videos to local directories
+
+## Usage
+
+```bash
+# Auto mode (default) - capture when page loads
+${BUN_X} {baseDir}/scripts/main.ts <url>
+
+# Wait mode - wait for user signal before capture
+${BUN_X} {baseDir}/scripts/main.ts <url> --wait
+
+# Save to specific file
+${BUN_X} {baseDir}/scripts/main.ts <url> -o output.md
+
+# Save to a custom output directory (auto-generates filename)
+${BUN_X} {baseDir}/scripts/main.ts <url> --output-dir ./posts/
+
+# Download images and videos to local directories
+${BUN_X} {baseDir}/scripts/main.ts <url> --download-media
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `<url>` | URL to fetch |
+| `-o <path>` | Output file path — must be a **file** path, not directory (default: auto-generated) |
+| `--output-dir <dir>` | Base output directory — auto-generates `{dir}/{domain}/{slug}.md` (default: `./url-to-markdown/`) |
+| `--wait` | Wait for user signal before capturing |
+| `--timeout <ms>` | Page load timeout (default: 30000) |
+| `--download-media` | Download image/video assets to local `imgs/` and `videos/`, and rewrite markdown links to local relative paths |
+
+## Capture Modes
+
+| Mode | Behavior | Use When |
+|------|----------|----------|
+| Auto (default) | Capture on network idle | Public pages, static content |
+| Wait (`--wait`) | User signals when ready | Login-required, lazy loading, paywalls |
+
+**Wait mode workflow**:
+1. Run with `--wait` → script outputs "Press Enter when ready"
+2. Ask user to confirm page is ready
+3. Send newline to stdin to trigger capture
+
+## Output Format
+
+Each run saves two files side by side:
+
+- Markdown: YAML front matter with `url`, `title`, `description`, `author`, `published`, optional `coverImage`, and `captured_at`, followed by converted markdown content
+- HTML snapshot: `*-captured.html`, containing the rendered page HTML captured from Chrome
+
+When Defuddle or page metadata provides a language hint, the markdown front matter also includes `language`.
+
+The HTML snapshot is saved before any markdown media localization, so it stays a faithful capture of the page DOM used for conversion.
+If the hosted `defuddle.md` API fallback is used, markdown is still saved, but there is no local `-captured.html` snapshot for that run.
+
+## Output Directory
+
+Default: `url-to-markdown/<domain>/<slug>.md`
+With `--output-dir ./posts/`: `./posts/<domain>/<slug>.md`
+
+HTML snapshot path uses the same basename:
+
+- `url-to-markdown/<domain>/<slug>-captured.html`
+- `./posts/<domain>/<slug>-captured.html`
+
+- `<slug>`: From page title or URL path (kebab-case, 2-6 words)
+- Conflict resolution: Append timestamp `<slug>-YYYYMMDD-HHMMSS.md`
+
+When `--download-media` is enabled:
+- Images are saved to `imgs/` next to the markdown file
+- Videos are saved to `videos/` next to the markdown file
+- Markdown media links are rewritten to local relative paths
+
+## Conversion Fallback
+
+Conversion order:
+
+1. Try Defuddle first
+2. For rich pages such as YouTube, prefer Defuddle's extractor-specific output (including transcripts when available) instead of replacing it with the legacy pipeline
+3. If Defuddle throws, cannot load, returns obviously incomplete markdown, or captures lower-quality content than the legacy pipeline, automatically fall back to the pre-Defuddle extractor
+4. If the entire local browser capture flow fails before markdown can be produced, try the hosted `https://defuddle.md/<url>` API and save its markdown output directly
+5. The legacy fallback path uses the older Readability/selector/Next.js-data based HTML-to-Markdown implementation recovered from git history
+
+CLI output will show:
+
+- `Converter: defuddle` when Defuddle succeeds
+- `Converter: legacy:...` plus `Fallback used: ...` when fallback was needed
+- `Converter: defuddle-api` when local browser capture failed and the hosted API was used instead
+
+## Media Download Workflow
+
+Based on `download_media` setting in EXTEND.md:
+
+| Setting | Behavior |
+|---------|----------|
+| `1` (always) | Run script with `--download-media` flag |
+| `0` (never) | Run script without `--download-media` flag |
+| `ask` (default) | Follow the ask-each-time flow below |
+
+### Ask-Each-Time Flow
+
+1. Run script **without** `--download-media` → markdown saved
+2. Check saved markdown for remote media URLs (`https://` in image/video links)
+3. **If no remote media found** → done, no prompt needed
+4. **If remote media found** → use `AskUserQuestion`:
+   - header: "Media", question: "Download N images/videos to local files?"
+   - "Yes" — Download to local directories
+   - "No" — Keep remote URLs
+5. If user confirms → run script **again** with `--download-media` (overwrites markdown with localized links)
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `URL_CHROME_PATH` | Custom Chrome executable path |
+| `URL_DATA_DIR` | Custom data directory |
+| `URL_CHROME_PROFILE_DIR` | Custom Chrome profile directory |
+
+**Troubleshooting**: Chrome not found → set `URL_CHROME_PATH`. Timeout → increase `--timeout`. Complex pages → try `--wait` mode. If markdown quality is poor, inspect the saved `-captured.html` and check whether the run logged a legacy fallback.
+
+### YouTube Notes
+
+- The upgraded Defuddle path uses async extractors, so YouTube pages can include transcript text directly in the markdown body.
+- Transcript availability depends on YouTube exposing a caption track. Videos with captions disabled, restricted playback, or blocked regional access may still produce description-only output.
+- If the page needs time to finish loading descriptions, chapters, or player metadata, prefer `--wait` and capture after the watch page is fully hydrated.
+
+### Hosted API Fallback
+
+- The hosted fallback endpoint is `https://defuddle.md/<url>`. In shell form: `curl https://defuddle.md/stephango.com`
+- Use it only when the local Chrome/CDP capture path fails outright. The local path still has higher fidelity because it can save the captured HTML and handle authenticated pages.
+- The hosted API already returns Markdown with YAML frontmatter, so save that response as-is and then apply the normal media-localization step if requested.
+
+## Extension Support
+
+Custom configurations via EXTEND.md. See **Preferences** section for paths and supported options.

package/dist/skills/llm-wiki/deps/baoyu-url-to-markdown/references/config/first-time-setup.md

@@ -0,0 +1,106 @@
+---
+name: first-time-setup
+description: First-time setup flow for baoyu-url-to-markdown preferences
+---
+
+# First-Time Setup
+
+## Overview
+
+When no EXTEND.md is found, guide user through preference setup.
+
+**BLOCKING OPERATION**: This setup MUST complete before ANY other workflow steps. Do NOT:
+- Start converting URLs
+- Ask about URLs or output paths
+- Proceed to any conversion
+
+ONLY ask the questions in this setup flow, save EXTEND.md, then continue.
+
+## Setup Flow
+
+```
+No EXTEND.md found
+        |
+        v
++---------------------+
+| AskUserQuestion     |
+| (all questions)     |
++---------------------+
+        |
+        v
++---------------------+
+| Create EXTEND.md    |
++---------------------+
+        |
+        v
+    Continue conversion
+```
+
+## Questions
+
+**Language**: Use user's input language or saved language preference.
+
+Use AskUserQuestion with ALL questions in ONE call:
+
+### Question 1: Download Media
+
+```yaml
+header: "Media"
+question: "How to handle images and videos in pages?"
+options:
+  - label: "Ask each time (Recommended)"
+    description: "After saving markdown, ask whether to download media"
+  - label: "Always download"
+    description: "Always download media to local imgs/ and videos/ directories"
+  - label: "Never download"
+    description: "Keep original remote URLs in markdown"
+```
+
+### Question 2: Default Output Directory
+
+```yaml
+header: "Output"
+question: "Default output directory?"
+options:
+  - label: "url-to-markdown (Recommended)"
+    description: "Save to ./url-to-markdown/{domain}/{slug}.md"
+```
+
+Note: User will likely choose "Other" to type a custom path.
+
+### Question 3: Save Location
+
+```yaml
+header: "Save"
+question: "Where to save preferences?"
+options:
+  - label: "User (Recommended)"
+    description: "~/.baoyu-skills/ (all projects)"
+  - label: "Project"
+    description: ".baoyu-skills/ (this project only)"
+```
+
+## Save Locations
+
+| Choice | Path | Scope |
+|--------|------|-------|
+| User | `~/.baoyu-skills/baoyu-url-to-markdown/EXTEND.md` | All projects |
+| Project | `.baoyu-skills/baoyu-url-to-markdown/EXTEND.md` | Current project |
+
+## After Setup
+
+1. Create directory if needed
+2. Write EXTEND.md
+3. Confirm: "Preferences saved to [path]"
+4. Continue with conversion using saved preferences
+
+## EXTEND.md Template
+
+```md
+download_media: [ask/1/0]
+default_output_dir: [path or empty]
+```
+
+## Modifying Preferences Later
+
+Users can edit EXTEND.md directly or delete it to trigger setup again.

package/dist/skills/llm-wiki/deps/baoyu-url-to-markdown/scripts/cdp.ts

@@ -0,0 +1,179 @@
+import {
+  CdpConnection,
+  findChromeExecutable as findChromeExecutableBase,
+  findExistingChromeDebugPort,
+  getFreePort,
+  killChrome,
+  launchChrome as launchChromeBase,
+  sleep,
+  waitForChromeDebugPort,
+  type PlatformCandidates,
+} from 'baoyu-chrome-cdp';
+
+import { resolveUrlToMarkdownChromeProfileDir } from './paths.js';
+import { NETWORK_IDLE_TIMEOUT_MS } from './constants.js';
+
+const CHROME_CANDIDATES_FULL: PlatformCandidates = {
+  darwin: [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+    '/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  ],
+  win32: [
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+    'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  ],
+  default: [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/snap/bin/chromium',
+    '/usr/bin/microsoft-edge',
+  ],
+};
+
+export { CdpConnection, getFreePort, killChrome, sleep, waitForChromeDebugPort };
+
+export async function findExistingChromePort(): Promise<number | null> {
+  return await findExistingChromeDebugPort({
+    profileDir: resolveUrlToMarkdownChromeProfileDir(),
+  });
+}
+
+export function findChromeExecutable(): string | null {
+  return findChromeExecutableBase({
+    candidates: CHROME_CANDIDATES_FULL,
+    envNames: ['URL_CHROME_PATH'],
+  }) ?? null;
+}
+
+export async function launchChrome(url: string, port: number, headless = false) {
+  const chromePath = findChromeExecutable();
+  if (!chromePath) throw new Error('Chrome executable not found. Install Chrome or set URL_CHROME_PATH env.');
+
+  return await launchChromeBase({
+    chromePath,
+    profileDir: resolveUrlToMarkdownChromeProfileDir(),
+    port,
+    url,
+    headless,
+    extraArgs: ['--disable-popup-blocking'],
+  });
+}
+
+export async function waitForNetworkIdle(
+  cdp: CdpConnection,
+  sessionId: string,
+  timeoutMs: number = NETWORK_IDLE_TIMEOUT_MS,
+): Promise<void> {
+  return new Promise((resolve) => {
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let pending = 0;
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      cdp.off('Network.requestWillBeSent', onRequest);
+      cdp.off('Network.loadingFinished', onFinish);
+      cdp.off('Network.loadingFailed', onFinish);
+    };
+    const done = () => { cleanup(); resolve(); };
+    const resetTimer = () => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(done, timeoutMs);
+    };
+    const onRequest = () => { pending++; resetTimer(); };
+    const onFinish = () => { pending = Math.max(0, pending - 1); if (pending <= 2) resetTimer(); };
+    cdp.on('Network.requestWillBeSent', onRequest);
+    cdp.on('Network.loadingFinished', onFinish);
+    cdp.on('Network.loadingFailed', onFinish);
+    resetTimer();
+  });
+}
+
+export async function waitForPageLoad(
+  cdp: CdpConnection,
+  sessionId: string,
+  timeoutMs: number = 30_000,
+): Promise<void> {
+  void sessionId;
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      cdp.off('Page.loadEventFired', handler);
+      resolve();
+    }, timeoutMs);
+    const handler = () => {
+      clearTimeout(timer);
+      cdp.off('Page.loadEventFired', handler);
+      resolve();
+    };
+    cdp.on('Page.loadEventFired', handler);
+  });
+}
+
+export async function createTargetAndAttach(
+  cdp: CdpConnection,
+  url: string,
+): Promise<{ targetId: string; sessionId: string }> {
+  const { targetId } = await cdp.send<{ targetId: string }>('Target.createTarget', { url });
+  const { sessionId } = await cdp.send<{ sessionId: string }>('Target.attachToTarget', { targetId, flatten: true });
+  await cdp.send('Network.enable', {}, { sessionId });
+  await cdp.send('Page.enable', {}, { sessionId });
+  return { targetId, sessionId };
+}
+
+export async function navigateAndWait(
+  cdp: CdpConnection,
+  sessionId: string,
+  url: string,
+  timeoutMs: number,
+): Promise<void> {
+  const loadPromise = new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Page load timeout')), timeoutMs);
+    const handler = (params: unknown) => {
+      const event = params as { name?: string };
+      if (event.name === 'load' || event.name === 'DOMContentLoaded') {
+        clearTimeout(timer);
+        cdp.off('Page.lifecycleEvent', handler);
+        resolve();
+      }
+    };
+    cdp.on('Page.lifecycleEvent', handler);
+  });
+  await cdp.send('Page.navigate', { url }, { sessionId });
+  await loadPromise;
+}
+
+export async function evaluateScript<T>(
+  cdp: CdpConnection,
+  sessionId: string,
+  expression: string,
+  timeoutMs: number = 30_000,
+): Promise<T> {
+  const result = await cdp.send<{ result: { value?: T } }>(
+    'Runtime.evaluate',
+    { expression, returnByValue: true, awaitPromise: true },
+    { sessionId, timeoutMs },
+  );
+  return result.result.value as T;
+}
+
+export async function autoScroll(
+  cdp: CdpConnection,
+  sessionId: string,
+  steps: number = 8,
+  waitMs: number = 600,
+): Promise<void> {
+  let lastHeight = await evaluateScript<number>(cdp, sessionId, 'document.body.scrollHeight');
+  for (let i = 0; i < steps; i++) {
+    await evaluateScript<void>(cdp, sessionId, 'window.scrollTo(0, document.body.scrollHeight)');
+    await sleep(waitMs);
+    const newHeight = await evaluateScript<number>(cdp, sessionId, 'document.body.scrollHeight');
+    if (newHeight === lastHeight) break;
+    lastHeight = newHeight;
+  }
+  await evaluateScript<void>(cdp, sessionId, 'window.scrollTo(0, 0)');
+}

package/dist/skills/llm-wiki/deps/baoyu-url-to-markdown/scripts/constants.ts

@@ -0,0 +1,13 @@
+import { resolveUrlToMarkdownChromeProfileDir } from "./paths.js";
+
+export const DEFAULT_USER_AGENT =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36";
+
+export const USER_DATA_DIR = resolveUrlToMarkdownChromeProfileDir();
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const CDP_CONNECT_TIMEOUT_MS = 15_000;
+export const NETWORK_IDLE_TIMEOUT_MS = 1_500;
+export const POST_LOAD_DELAY_MS = 800;
+export const SCROLL_STEP_WAIT_MS = 600;
+export const SCROLL_MAX_STEPS = 8;

package/dist/skills/llm-wiki/deps/baoyu-url-to-markdown/scripts/defuddle-converter.ts

@@ -0,0 +1,58 @@
+import { JSDOM, VirtualConsole } from "jsdom";
+import { Defuddle } from "defuddle/node";
+
+import {
+  type ConversionResult,
+  type PageMetadata,
+  isMarkdownUsable,
+  normalizeMarkdown,
+  pickString,
+} from "./markdown-conversion-shared.js";
+
+export async function tryDefuddleConversion(
+  html: string,
+  url: string,
+  baseMetadata: PageMetadata
+): Promise<{ ok: true; result: ConversionResult } | { ok: false; reason: string }> {
+  try {
+    const virtualConsole = new VirtualConsole();
+    virtualConsole.on("jsdomError", (error: Error & { type?: string }) => {
+      if (error.type === "css parsing" || /Could not parse CSS stylesheet/i.test(error.message)) {
+        return;
+      }
+      console.warn(`[url-to-markdown] jsdom: ${error.message}`);
+    });
+
+    const dom = new JSDOM(html, { url, virtualConsole });
+    const result = await Defuddle(dom, url, { markdown: true });
+    const markdown = normalizeMarkdown(result.content || "");
+
+    if (!isMarkdownUsable(markdown, html)) {
+      return { ok: false, reason: "Defuddle returned empty or incomplete markdown" };
+    }
+
+    return {
+      ok: true,
+      result: {
+        metadata: {
+          ...baseMetadata,
+          title: pickString(result.title, baseMetadata.title) ?? "",
+          description: pickString(result.description, baseMetadata.description) ?? undefined,
+          author: pickString(result.author, baseMetadata.author) ?? undefined,
+          published: pickString(result.published, baseMetadata.published) ?? undefined,
+          coverImage: pickString(result.image, baseMetadata.coverImage) ?? undefined,
+          language: pickString(result.language, baseMetadata.language) ?? undefined,
+        },
+        markdown,
+        rawHtml: html,
+        conversionMethod: "defuddle",
+        variables: result.variables,
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+}