markpaste 0.0.1 → 0.0.2

package/AGENTS.md

@@ -13,9 +13,10 @@ MarkPaste is a web-based utility for converting rich text to Markdown. The core
   - `src/cleaner.js`: The logic for cleaning the HTML.
   - `src/converter.js`: The logic for converting HTML to Markdown.
 
-- `src/markpaste.js`: The library entry point. (for node or bundling)
+- `src/index.js`: The library entry point. (for node or bundling)
 
 - Also:
+  - `bin/markpaste`: The CLI tool for macOS clipboard integration.
   - `test/web/`: Playwright tests for core application functionality.
   - `test/node/`: Node.js unit tests for library logic.
   - `third_party/`: External assets like `pandoc.wasm`.

package/README.md

@@ -13,16 +13,18 @@ MarkPaste is an isomorphic tool that converts rich text to Markdown. It works se
 ## Usage
 
 ### Web Application
+
 1. **Open the app:** Run locally or host the `index.html`.
 2. **Paste:** Copy rich text from a webpage or document and paste it into the input area.
 3. **Get Markdown:** View the generated Markdown from multiple converters simultaneously.
 4. **Copy:** Click to copy the Markdown to your clipboard.
 
 ### Node.js Library
+
 MarkPaste can be used programmatically in Node.js environments. It uses `linkedom` to provide a lightweight DOM implementation for the conversion logic.
 
 ```javascript
-import { convert } from './src/markpaste.js';
+import {convert} from './src/index.js';
 
 const html = '<h1>Hello World</h1><p>This is <b>bold</b> text.</p>';
 
@@ -31,11 +33,11 @@ const markdown = await convert(html);
 console.log(markdown);
 
 // Using Pandoc
-const pandocMarkdown = await convert(html, { converter: 'pandoc' });
+const pandocMarkdown = await convert(html, {converter: 'pandoc'});
 console.log(pandocMarkdown);
 
 // Disabling HTML cleaning
-const rawMarkdown = await convert(html, { clean: false });
+const rawMarkdown = await convert(html, {clean: false});
 ```
 
 ## Development
@@ -43,6 +45,7 @@ const rawMarkdown = await convert(html, { clean: false });
 To run MarkPaste locally:
 
 1. **Clone & Install:**
+
    ```bash
    git clone https://github.com/paulirish/markpaste.git
    cd markpaste
@@ -56,11 +59,14 @@ To run MarkPaste locally:
    Access the application at `http://localhost:7025`.
 
 ### Testing
+
 The project uses a dual-testing strategy:
+
 - **Node.js tests:** Unit tests for isomorphic modules (`pnpm test:node`).
 - **Playwright tests:** End-to-end browser testing (`pnpm test:web`).
 
 Run all tests with:
+
 ```bash
 pnpm test
 ```

package/TYPESCRIPT.md

@@ -0,0 +1,109 @@
+# Guide: Modern Type Checking without a Build Step
+
+This guide outlines a setup for achieving type safety in both browser and Node.js environments while avoiding a compilation/build step.
+
+## Core Philosophy
+
+1.  **Browser (Client-side)**: Use pure JavaScript with **JSDoc annotations**. This ensures the code runs directly in the browser without bundling or transpilation.
+2.  **Node.js (Server-side/Tooling)**: Use **TypeScript with Erasable Syntax**. This allows Node.js to execute `.ts` files natively while benefiting from TypeScript's static analysis.
+
+---
+
+## 1. Browser-side: JavaScript + JSDoc
+
+Maintain all frontend logic in `.js` files. Use JSDoc to define types, interfaces, and function signatures.
+
+### Patterns
+
+- Use `@type` for variable declarations.
+- Use `@param` and `@returns` for functions.
+- Use `@typedef` or `@template` for complex types.
+- Import types from other files using `import('./path/to/file.js').TypeName`.
+
+```javascript
+/**
+ * @param {string} input
+ * @param {Object} options
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<string>}
+ */
+export async function processData(input, {verbose = false} = {}) {
+  // ...
+}
+```
+
+---
+
+## 2. Node.js: TypeScript + Erasable Syntax
+
+Use `.ts` files for Node.js logic. Stick to **Erasable Syntax Only**—features that can be removed by simply stripping the type annotations.
+
+### Prohibited Features (Non-Erasable)
+
+- `enum`
+- `namespaces`
+- `parameter properties` in constructors (e.g., `constructor(public name: string) {}`)
+- `experimentalDecorators`
+
+### Required Conventions
+
+- **Explicit Extensions**: Always use the `.ts` extension in import statements.
+- **Explicit Type Imports**: Always use `import type` for types to ensure they are safely erasable.
+
+```typescript
+import {helper} from './utils.ts';
+import type {Config} from './types.ts';
+```
+
+---
+
+## 3. Configuration Requirements
+
+### `tsconfig.json`
+
+The configuration must support both JSDoc checking and native TypeScript execution.
+
+```json
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    /* Native TS Execution Flags */
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+
+    /* Type Checking Strategy */
+    "noEmit": true,
+    "allowJs": true,
+    "checkJs": true,
+    "skipLibCheck": true,
+    "strict": true
+  }
+}
+```
+
+### `package.json`
+
+The project must be an ES Module.
+
+```json
+{
+  "type": "module",
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+---
+
+## 4. Environment & Tooling
+
+- **Node.js**: Version **v24.11.0+** is required for stable native TypeScript support.
+- **IDE**: VS Code (or any LSP-compliant editor) will automatically pick up the `tsconfig.json` to provide real-time feedback for both `.js` (via JSDoc) and `.ts` files.
+- **CI/CD**: Run `npm run typecheck` (or equivalent) as a blocking step in your pipeline.

package/bin/markpaste

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+/**
+ * markpaste
+ *
+ * 1. Reads HTML from the clipboard (via raw hex from osascript)
+ * 2. Cleans and converts it to Markdown using MarkPaste
+ * 3. Saves Markdown as Plain Text and Cleaned HTML as HTML back to clipboard
+ * 4. Verifies the set content.
+ */
+
+import { execSync, spawnSync } from 'node:child_process';
+import { writeFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+
+import { convert, cleanHTML, isProbablyMarkdown } from '../src/index.js';
+import { marked } from 'marked';
+
+/**
+ * Formats a string for preview in the logs (truncated, escaped, and dimmed).
+ */
+function textToPreview(text, length = 100) {
+  const dimmedStart = '\x1b[2m';
+  const dimmedEnd = '\x1b[22m';
+  const preview = text.substring(0, length).replace(/\n/g, '\\n');
+  return `${dimmedStart}${preview}${dimmedEnd}...`;
+}
+
+/**
+ * Reads the HTML flavor from the macOS clipboard.
+ * Returns null if no HTML flavor is present.
+ */
+function readHtmlFromClipboard() {
+  try {
+    const script = 'try\n  the clipboard as «class HTML»\non error\n  return ""\nend try';
+    const hexData = execSync(`osascript -e '${script}'`, { encoding: 'utf8' }).trim();
+    const match = hexData.match(/«data HTML([0-9A-F]*)»/i);
+    if (match && match[1]) {
+      return Buffer.from(match[1], 'hex').toString('utf8');
+    }
+  } catch (e) {
+    // Silently fail to return null
+  }
+  return null;
+}
+
+/**
+ * Reads the plain text flavor from the macOS clipboard.
+ */
+function readTextFromClipboard() {
+  return execSync('pbpaste', { encoding: 'utf8' });
+}
+
+/**
+ * Sets both the HTML and Plain Text flavors on the macOS clipboard.
+ */
+function setClipboard(html, markdown) {
+  const mdTmp = path.join(os.tmpdir(), `mp_md_${Date.now()}.txt`);
+  writeFileSync(mdTmp, markdown);
+
+  const htmlHex = Buffer.from(html, 'utf8').toString('hex');
+  const appleScript = `
+    set theText to (read (POSIX file "${mdTmp}") as «class utf8»)
+    set the clipboard to {«class HTML»:«data HTML${htmlHex}», text:theText}
+  `;
+
+  const result = spawnSync('osascript', [], { input: appleScript, encoding: 'utf8' });
+  unlinkSync(mdTmp);
+
+  if (result.status !== 0) {
+    throw new Error(`osascript failed: ${result.stderr}`);
+  }
+}
+
+async function main() {
+  try {
+    const rawHtml = readHtmlFromClipboard();
+    const hasHtmlFlavor = !!rawHtml;
+    const input = rawHtml || readTextFromClipboard();
+
+    if (!input || input.trim() === '') {
+      console.error('No content found in clipboard.');
+      process.exit(1);
+    }
+
+    console.log(`Reading from clipboard... (${input.length} chars)`);
+    console.log(`   Preview: ${textToPreview(input)}`);
+
+    const isMarkdown = isProbablyMarkdown(input, hasHtmlFlavor);
+
+    let cleanedHtml;
+    let markdown;
+
+    if (isMarkdown) {
+      console.log('✨ Markdown detected. Rendering to HTML...');
+      markdown = input;
+      cleanedHtml = await marked.parse(input);
+    } else {
+      cleanedHtml = await cleanHTML(input);
+      markdown = await convert(input, { clean: true, isMarkdown: false });
+    }
+
+    console.log('Updating clipboard...');
+    setClipboard(cleanedHtml, markdown);
+
+    // // Verification Step
+    // const verifiedHtml = readHtmlFromClipboard();
+    // if (verifiedHtml === cleanedHtml) {
+    //   console.log('✅ Clipboard verified: HTML flavor matches perfectly.');
+    // } else {
+    //   console.warn('⚠️  Clipboard verification mismatch!');
+    //   if (!verifiedHtml) {
+    //     console.warn('   Reason: No HTML flavor found after setting.');
+    //   } else {
+    //     console.warn(`   Reason: Length difference (${cleanedHtml.length} vs ${verifiedHtml.length})`);
+    //   }
+    // }
+
+    console.log('\n✅ Clipboard updated with:');
+    console.log(`   - Plain Text (Markdown): ${textToPreview(markdown)}`);
+    console.log(`   - HTML (Cleaned): ${textToPreview(cleanedHtml)}`);
+
+  } catch (err) {
+    console.error('Error during conversion:', err);
+    process.exit(1);
+  }
+}
+
+main();

package/index.html

@@ -56,6 +56,10 @@
 
       <!-- Bottom: 2 Columns Output -->
       <section class="section-outputs two-column-grid">
+        <div id="loadingOverlay" class="loading-overlay hidden">
+          <div class="spinner"></div>
+          <span>Converting...</span>
+        </div>
         <!-- Turndown -->
         <div class="output-column">
           <div class="panel output-panel">
@@ -135,10 +139,10 @@
   <script type="importmap">
     {
       "imports": {
-        "marked": "/node_modules/marked/lib/marked.esm.js",
-        "turndown": "/node_modules/turndown/lib/turndown.es.js",
-        "turndown-plugin-gfm": "/node_modules/turndown-plugin-gfm/lib/turndown-plugin-gfm.es.js",
-        "@bjorn3/browser_wasi_shim": "/node_modules/@bjorn3/browser_wasi_shim/dist/index.js"
+        "marked": "https://unpkg.com/marked@15.0.0/lib/marked.esm.js",
+        "turndown": "https://unpkg.com/turndown@7.2.0/lib/turndown.es.js",
+        "turndown-plugin-gfm": "https://unpkg.com/turndown-plugin-gfm@1.0.2/lib/turndown-plugin-gfm.es.js",
+        "@bjorn3/browser_wasi_shim": "https://unpkg.com/@bjorn3/browser_wasi_shim@0.4.0/dist/index.js"
       }
     }
   </script>

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "markpaste",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "HTML and Markdown, perfected for pasting into documents, emails, and more. So isomorphic. lol.",
-  "main": "src/markpaste.js",
+  "main": "src/index.js",
+  "bin": {
+    "markpaste": "bin/markpaste"
+  },
   "scripts": {
     "start": "npx statikk --port 7025",
     "typecheck": "tsc --noEmit",
-    "format": "prettier --write .",
+    "format": "prettier --write \"**/*.{js,ts,json,md}\"",
     "test": "pnpm run typecheck && pnpm run test:node && pnpm run test:web",
     "test:web": "playwright test",
     "test:node": "node --test test/node/**/*.test.js"

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+overrides:
+  markpaste: 'link:'

package/src/app.js

@@ -15,7 +15,7 @@ window.$ = function (query, context) {
   if (result === null) {
     throw new Error(`query ${query} not found`);
   }
-   return /** @type {import('typed-query-selector/parser.js').ParseSelector<T, Element>} */ (result);
+  return /** @type {import('typed-query-selector/parser.js').ParseSelector<T, Element>} */ (result);
 };
 /**
  * @template {string} T
@@ -55,13 +55,14 @@ function toggleTheme() {
   localStorage.setItem('theme', newTheme);
 }
 
-const {$, $$ } = window;
+const {$, $$} = window;
 
 const inputArea = $('div#inputArea');
 const htmlCode = $('code#htmlCode');
 const copyBtn = $('button#copyBtn');
 const themeToggle = $('button#themeToggle');
 const cleanHtmlToggle = $('input#cleanHtmlToggle');
+const loadingOverlay = $('div#loadingOverlay');
 
 // View Toggle
 const viewMarkdownBtn = $('button#viewMarkdownBtn');
@@ -97,7 +98,6 @@ const convertersPromise = (async () => {
 let currentView = 'markdown'; // 'markdown' or 'rendered'
 
 async function init() {
-
   setupEventListeners();
 
   loadTheme();
@@ -108,7 +108,7 @@ async function init() {
   // Initial process if there's content (e.g. from reload, though usually empty)
   if (inputArea.innerHTML) {
     lastProcessedContent = inputArea.innerHTML;
-    processContent(lastProcessedContent);
+    await processContent(lastProcessedContent);
   }
 }
 
@@ -133,23 +133,24 @@ async function startIdleDetector() {
         if (userState === 'idle') {
           // Unload pandoc if it exists
           if (converters.pandoc) {
-             console.log('User is idle. Unloading pandoc module to free memory.');
-             if (converters.pandoc.dispose) {
-               converters.pandoc.dispose();
-             }
-             delete converters.pandoc;
+            console.log('User is idle. Unloading pandoc module to free memory.');
+            if (converters.pandoc.dispose) {
+              converters.pandoc.dispose();
+            }
+            delete converters.pandoc;
           }
         }
       });
 
       // 10 minutes = 600,000 ms
-      idleDetector.start({
-        threshold: 600000,
-        signal,
-      }).catch(err => {
-         console.warn('Idle detection start failed:', err);
-      });
-
+      idleDetector
+        .start({
+          threshold: 600000,
+          signal,
+        })
+        .catch(err => {
+          console.warn('Idle detection start failed:', err);
+        });
     } catch (err) {
       console.warn('Idle detection setup failed:', err);
     }
@@ -159,18 +160,40 @@ async function startIdleDetector() {
 function setupEventListeners() {
   inputArea.on('paste', handlePaste);
 
-  inputArea.on('input', () => {
+  inputArea.on('input', async () => {
     lastProcessedContent = inputArea.innerHTML;
-    processContent(lastProcessedContent);
+    if (lastProcessedContent.length > 10000) {
+      showLoading();
+      setTimeout(async () => {
+        try {
+          await processContent(lastProcessedContent);
+        } finally {
+          hideLoading();
+        }
+      }, 10);
+    } else {
+      await processContent(lastProcessedContent);
+    }
   });
 
   copyBtn.on('click', copyToClipboard);
 
   themeToggle.on('click', toggleTheme);
 
-  cleanHtmlToggle.on('change', () => {
+  cleanHtmlToggle.on('change', async () => {
     if (lastProcessedContent) {
-      processContent(lastProcessedContent);
+      if (lastProcessedContent.length > 5000) {
+        showLoading();
+        setTimeout(async () => {
+          try {
+            await processContent(lastProcessedContent);
+          } finally {
+            hideLoading();
+          }
+        }, 10);
+      } else {
+        await processContent(lastProcessedContent);
+      }
     }
   });
 
@@ -225,6 +248,14 @@ function handleSelectAll(e) {
   }
 }
 
+function showLoading() {
+  loadingOverlay.classList.remove('hidden');
+}
+
+function hideLoading() {
+  loadingOverlay.classList.add('hidden');
+}
+
 async function handlePaste(e) {
   e.preventDefault();
 
@@ -232,14 +263,25 @@ async function handlePaste(e) {
   const pastedHtml = clipboardData.getData('text/html');
   const pastedText = clipboardData.getData('text/plain');
 
+  showLoading();
+
   await convertersPromise;
 
-  const content = pastedHtml || pastedText;
+  const isMarkdown = isProbablyMarkdown(pastedText, !!pastedHtml);
+  const content = isMarkdown ? pastedText : pastedHtml || pastedText;
   lastProcessedContent = content;
-  processContent(content);
 
-  // Reset scroll position for all pre elements
-  $$('pre').forEach(pre => pre.scrollTop = 0);
+  // Use setTimeout to allow UI to update before blocking the thread with conversion
+  setTimeout(async () => {
+    try {
+      await processContent(content, isMarkdown);
+    } finally {
+      hideLoading();
+    }
+
+    // Reset scroll position for all pre elements
+    $$('pre').forEach(pre => (pre.scrollTop = 0));
+  }, 10);
 
   inputArea.innerHTML = '';
   inputArea.setAttribute('placeholder', 'Pasted! Ready for more...');
@@ -248,34 +290,106 @@ async function handlePaste(e) {
   }, 2000);
 }
 
-function processContent(html) {
-  const shouldClean = cleanHtmlToggle.checked;
-  const contentToConvert = shouldClean ? cleanHTML(html) : removeStyleAttributes(html);
+function isProbablyMarkdown(text, hasHtml) {
+  if (hasHtml) return false;
+  const trimmed = text.trim();
+  if (trimmed.startsWith('<')) return false;
+  return true;
+}
+
+async function processContent(content, isMarkdown = null) {
+  let htmlToShow;
+  let markdownResults;
+
+  if (isMarkdown === null) {
+    isMarkdown = isProbablyMarkdown(content, false);
+  }
+
+  if (isMarkdown) {
+    // If it's markdown, the "results" are just the content itself.
+    markdownResults = {
+      turndown: content,
+      pandoc: content,
+    };
+    // For the HTML preview, we render the markdown.
+    const tempDiv = document.createElement('div');
+    await renderMarkdown(content, tempDiv);
+    htmlToShow = tempDiv.innerHTML;
+  } else {
+    const shouldClean = cleanHtmlToggle.checked;
+    const contentToConvert = shouldClean ? cleanHTML(content) : removeStyleAttributes(content);
+    htmlToShow = contentToConvert;
+    markdownResults = runConverters(contentToConvert);
+  }
 
   // Update HTML Preview
-  htmlCode.textContent = formatHTML(contentToConvert);
+  htmlCode.textContent = formatHTML(htmlToShow);
   if (window.Prism) {
     window.Prism.highlightElement(htmlCode);
   }
 
-  // Run all converters
+  // Update UI with results
+  for (const [name, markdown] of Object.entries(markdownResults)) {
+    if (outputs[name]) {
+      outputs[name].code.textContent = markdown;
+      if (window.Prism) {
+        window.Prism.highlightElement(outputs[name].code);
+      }
+    }
+  }
+
+  // Fire and forget the diff check
+  if (!isMarkdown) {
+    checkDiffs(markdownResults);
+  }
+
+  if (currentView === 'rendered') {
+    updateRenderedPreviews();
+  }
+}
+
+function runConverters(htmlContent) {
+  const results = {};
   for (const [name, converter] of Object.entries(converters)) {
     if (converter) {
       try {
-        const markdown = converter.convert(contentToConvert);
-        outputs[name].code.textContent = markdown;
-        if (window.Prism) {
-          window.Prism.highlightElement(outputs[name].code);
-        }
+        results[name] = converter.convert(htmlContent);
       } catch (err) {
         console.error(`Converter ${name} failed:`, err);
-        outputs[name].code.textContent = `Error converting with ${name}: ${err.message}`;
+        results[name] = `Error converting with ${name}: ${err.message}`;
       }
     }
   }
+  return results;
+}
 
-  if (currentView === 'rendered') {
-    updateRenderedPreviews();
+async function checkDiffs(results) {
+  // We need both to be present and not error messages
+  if (!results.turndown || !results.pandoc) return;
+  if (results.turndown.startsWith('Error converting') || results.pandoc.startsWith('Error converting')) return;
+
+  const tDiv = document.createElement('div');
+  const pDiv = document.createElement('div');
+
+  await renderMarkdown(results.turndown, tDiv);
+  await renderMarkdown(results.pandoc, pDiv);
+
+  const turndownHtml = tDiv.innerHTML;
+  const pandocHtml = pDiv.innerHTML;
+  tDiv.innerHTML = pDiv.innerHTML = '';
+
+  if (turndownHtml !== pandocHtml) {
+    let firstDiff = 0;
+    const maxLength = Math.max(turndownHtml.length, pandocHtml.length);
+    while (firstDiff < maxLength && turndownHtml[firstDiff] === pandocHtml[firstDiff]) {
+      firstDiff++;
+    }
+
+    console.group('Converter Diff Discrepancy');
+    console.log(`First difference at index ${firstDiff}:`);
+    console.log(`  Turndown: "...${turndownHtml.substring(firstDiff, firstDiff + 40)}..."`);
+    console.log(`  Pandoc:   "...${pandocHtml.substring(firstDiff, firstDiff + 40)}..."`);
+    console.groupEnd();
   }
 }
 
@@ -341,7 +455,7 @@ async function copyToClipboard() {
 
   try {
     const items = {
-      'text/plain': new Blob([textToCopy], {type: 'text/plain'})
+      'text/plain': new Blob([textToCopy], {type: 'text/plain'}),
     };
     if (htmlToCopy) {
       items['text/html'] = new Blob([htmlToCopy], {type: 'text/html'});
@@ -361,7 +475,7 @@ async function copyToClipboard() {
     console.error('Failed to copy:', err);
     copyBtn.textContent = 'Copy failed';
     setTimeout(() => {
-       copyBtn.innerHTML = originalText;
+      copyBtn.innerHTML = originalText;
     }, 2000);
   }
 }

package/src/cleaner.js

@@ -7,7 +7,7 @@
 let parseHTMLGlobal, documentGlobal, NodeGlobal;
 
 if (typeof window !== 'undefined') {
-  parseHTMLGlobal = (html) => {
+  parseHTMLGlobal = html => {
     const parser = new DOMParser();
     return parser.parseFromString(html, 'text/html');
   };
@@ -15,8 +15,8 @@ if (typeof window !== 'undefined') {
   NodeGlobal = window.Node;
 } else {
   // We are in Node.js
-  const { parseHTML } = await import('linkedom');
-  parseHTMLGlobal = (html) => {
+  const {parseHTML} = await import('linkedom');
+  parseHTMLGlobal = html => {
     const fullHtml = `<!DOCTYPE html><html><body>${html}</body></html>`;
     return parseHTML(fullHtml).document;
   };
@@ -26,8 +26,35 @@ if (typeof window !== 'undefined') {
 }
 
 const ALLOWED_TAGS = [
-  'P', 'STRONG', 'B', 'EM', 'I', 'BLOCKQUOTE', 'CODE', 'PRE', 'A', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6',
-  'UL', 'OL', 'LI', 'DL', 'DT', 'DD', 'BR', 'HR', 'TABLE', 'THEAD', 'TBODY', 'TR', 'TH', 'TD',
+  'P',
+  'STRONG',
+  'B',
+  'EM',
+  'I',
+  'BLOCKQUOTE',
+  'CODE',
+  'PRE',
+  'A',
+  'H1',
+  'H2',
+  'H3',
+  'H4',
+  'H5',
+  'H6',
+  'UL',
+  'OL',
+  'LI',
+  'DL',
+  'DT',
+  'DD',
+  'BR',
+  'HR',
+  'TABLE',
+  'THEAD',
+  'TBODY',
+  'TR',
+  'TH',
+  'TD',
 ];
 
 const ALLOWED_ATTRIBUTES = {
@@ -72,12 +99,9 @@ function processNode(sourceNode, targetParent) {
     if (sourceNode.classList && sourceNode.classList.contains('mdn-copy-button')) {
       return;
     }
-    
+
     const href = sourceNode.getAttribute('href');
-    if (
-      tagName === 'A' &&
-      href && href.startsWith('https://developer.mozilla.org/en-US/play')
-    ) {
+    if (tagName === 'A' && href && href.startsWith('https://developer.mozilla.org/en-US/play')) {
       return;
     }
 
@@ -86,13 +110,12 @@ function processNode(sourceNode, targetParent) {
       // This tweak should only happen when this element is the FIRST element in the received DOM.
       if (tagName === 'UL' || tagName === 'OL') {
         const parent = sourceNode.parentNode;
-        const isFirstElementInBody = parent && 
-                                    parent.tagName === 'BODY' && 
-                                    Array.from(parent.children).find(c => !['META', 'STYLE'].includes(c.tagName.toUpperCase())) === sourceNode;
+        const isFirstElementInBody =
+          parent && parent.tagName === 'BODY' && Array.from(parent.children).find(c => !['META', 'STYLE'].includes(c.tagName.toUpperCase())) === sourceNode;
 
         if (isFirstElementInBody) {
-          const hasLiChild = Array.from(sourceNode.childNodes).some(child =>
-            child.nodeType === NodeGlobal.ELEMENT_NODE && child.tagName.toUpperCase() === 'LI'
+          const hasLiChild = Array.from(sourceNode.childNodes).some(
+            child => child.nodeType === NodeGlobal.ELEMENT_NODE && child.tagName.toUpperCase() === 'LI'
           );
           if (!hasLiChild) {
             // Unwrap: process children directly into targetParent
@@ -142,4 +165,4 @@ export function removeStyleAttributes(html) {
     allElements[i].removeAttribute('style');
   }
   return body.innerHTML;
-}
+}

package/src/converter.js

@@ -43,7 +43,7 @@ async function getPandocConverter() {
     },
     dispose: () => {
       pandocModule.dispose();
-    }
+    },
   };
 }
 

package/src/index.js

@@ -0,0 +1,46 @@
+/**
+ * index.js
+ * MarkPaste Library Entry Point (Node.js)
+ */
+
+import {cleanHTML, removeStyleAttributes} from './cleaner.js';
+import {getConverter} from './converter.js';
+
+/**
+ * Converts HTML to Markdown using the specified converter.
+ * @param {string} input The HTML (or Markdown) string to convert.
+ * @param {Object} options Configuration options.
+ * @param {string} [options.converter='turndown'] The converter to use ('turndown', 'pandoc').
+ * @param {boolean} [options.clean=true] Whether to clean the HTML before conversion.
+ * @param {boolean} [options.isMarkdown] Force treatment as markdown (skipping conversion).
+ * @returns {Promise<string>} The resulting Markdown string.
+ */
+export async function convert(input, options = {}) {
+  const {converter: converterName = 'turndown', clean = true, isMarkdown: forcedIsMarkdown} = options;
+
+  const isMarkdown = forcedIsMarkdown !== undefined ? forcedIsMarkdown : isProbablyMarkdown(input);
+
+  if (isMarkdown) {
+    return input;
+  }
+
+  const cleanedHtml = clean ? await cleanHTML(input) : await removeStyleAttributes(input);
+  const converter = await getConverter(converterName);
+
+  return converter.convert(cleanedHtml);
+}
+
+/**
+ * Heuristic to detect if a string is likely Markdown instead of HTML.
+ * @param {string} text
+ * @param {boolean} [hasHtmlFlavor=false] If we know for a fact there was an HTML flavor (e.g. from clipboard)
+ * @returns {boolean}
+ */
+export function isProbablyMarkdown(text, hasHtmlFlavor = false) {
+  if (hasHtmlFlavor) return false;
+  const trimmed = text.trim();
+  if (trimmed.startsWith('<')) return false;
+  return true;
+}
+
+export {cleanHTML, removeStyleAttributes, getConverter};

package/src/pandoc.js

@@ -47,7 +47,7 @@ async function loadWasm() {
   } else {
     const fs = await import('node:fs');
     const path = await import('node:path');
-    const { fileURLToPath } = await import('node:url');
+    const {fileURLToPath} = await import('node:url');
     const __dirname = path.dirname(fileURLToPath(import.meta.url));
     const wasmPath = path.join(__dirname, '..', 'third_party', 'pandoc.wasm');
     const bytes = fs.readFileSync(wasmPath);
@@ -95,4 +95,4 @@ export function dispose() {
   out_file = null;
   wasi = null;
   instance = null;
-}
+}

package/src/renderer.js

@@ -1,4 +1,4 @@
-import { marked } from 'marked';
+import {marked} from 'marked';
 
 /**
  * Renders markdown into a target element, sanitizing it first.
@@ -12,17 +12,17 @@ export async function renderMarkdown(markdown, targetElement) {
   }
 
   const rawHtml = await marked.parse(markdown);
-  
+
   // @ts-ignore
   if (targetElement.setHTML) {
     // @ts-ignore
     const sanitizer = new Sanitizer();
     // @ts-ignore
-    targetElement.setHTML(rawHtml, { sanitizer });
+    targetElement.setHTML(rawHtml, {sanitizer});
   } else {
     // Fallback if setHTML/Sanitizer is not supported (though we should encourage it)
     // For now, we will just set innerHTML as a fallback or warn.
-    // Given the prompt asks for Sanitizer API, we assume it's available or polyfilled, 
+    // Given the prompt asks for Sanitizer API, we assume it's available or polyfilled,
     // but in reality it's very experimental.
     // We'll stick to the requested API.
     console.warn('Sanitizer API (setHTML) not supported. Falling back to innerHTML (UNSAFE).');

package/src/style.css

@@ -156,6 +156,7 @@ main.vertical-layout {
   min-height: 200px; /* Minimum height for outputs */
   display: flex;
   gap: 1rem;
+  position: relative;
 }
 
 .section-copy-actions {
@@ -275,6 +276,15 @@ main.vertical-layout {
     margin: revert;
     padding: revert;
   }
+
+  pre, code {
+    background: var(--secondary-bg);
+    color: var(--text-color);
+    padding: 0.2rem 0.4rem;
+    border-radius: 4px;
+    font-family: var(--font-mono);
+    font-size: 90%;
+  }
 }
 
 
@@ -288,6 +298,39 @@ main.vertical-layout {
   display: none !important;
 }
 
+.loading-overlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: var(--panel-bg);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  z-index: 10;
+  backdrop-filter: blur(4px);
+  border-radius: 6px;
+  color: var(--text-color);
+  font-weight: 500;
+}
+
+.spinner {
+  width: 40px;
+  height: 40px;
+  border: 4px solid var(--secondary-bg);
+  border-top: 4px solid var(--primary-color);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+  margin-bottom: 1rem;
+}
+
+@keyframes spin {
+  0% { transform: rotate(0deg); }
+  100% { transform: rotate(360deg); }
+}
+
 /* App Footer */
 .app-footer {
   display: flex;

package/test/node/cleaner.test.js

@@ -1,6 +1,6 @@
-import { test } from 'node:test';
+import {test} from 'node:test';
 import assert from 'node:assert';
-import { cleanHTML, removeStyleAttributes } from '../../src/cleaner.js';
+import {cleanHTML, removeStyleAttributes} from '../../src/cleaner.js';
 
 test('cleaner: cleanHTML should remove disallowed tags', async () => {
   const html = '<div><p>Hello</p><script>alert(1)</script><span>World</span></div>';
@@ -36,9 +36,7 @@ test('cleaner: removeStyleAttributes should strip style attributes', async () =>
   assert.strictEqual(stripped.toLowerCase().includes('<p>hello</p>'), true);
 });
 
-
 test('cleaner: handles leading OL/UL tags correctly', async () => {
-
   const html = `<meta charset='utf-8'><ol style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 0px; padding-left: 40px; list-style: outside decimal; color: rgb(32, 33, 36); font-family: Roboto, &quot;Noto Sans&quot;, &quot;Noto Sans JP&quot;, &quot;Noto Sans KR&quot;, &quot;Noto Naskh Arabic&quot;, &quot;Noto Sans Thai&quot;, &quot;Noto Sans Hebrew&quot;, &quot;Noto Sans Bengali&quot;, sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><h1 class="devsite-page-title" tabindex="-1" style="box-sizing: inherit; font: 500 36px / 44px &quot;Google Sans&quot;, &quot;Noto Sans&quot;, &quot;Noto Sans JP&quot;, &quot;Noto Sans KR&quot;, &quot;Noto Naskh Arabic&quot;, &quot;Noto Sans Thai&quot;, &quot;Noto Sans Hebrew&quot;, &quot;Noto Sans Bengali&quot;, sans-serif; color: rgb(32, 33, 36); letter-spacing: normal; margin: 0px 0px 24px; overflow: visible; text-overflow: ellipsis; display: inline; vertical-align: middle;">Manage Python packages<devsite-actions data-nosnippet="" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; display: inline-flex; gap: 8px; padding-inline: 8px;"><devsite-feature-tooltip ack-key="AckCollectionsBookmarkTooltipDismiss" analytics-category="Site-Wide Custom Events" analytics-action-show="Callout Profile displayed" analytics-action-close="Callout Profile dismissed" analytics-label="Create Collection Callout" class="devsite-page-bookmark-tooltip nocontent inline-block" dismiss-button="true" id="devsite-collections-dropdown" dismiss-button-text="Dismiss" close-button-text="Got it" rendered="" current-step="0" style="--devsite-popout-top: calc(100% + 17px); --devsite-popout-width: min(50vw,320px); --devsite-feature-tooltip-text-color: #fff; position: relative; box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; display: inline-block; --devsite-popout-offset-x: 32px;"><slot><devsite-bookmark class="show" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; --devsite-bookmark-background: 0; --devsite-bookmark-background-focus-legacy: #e8eaed; --devsite-bookmark-background-hover-legacy: #f1f3f4; --devsite-bookmark-icon-color: #5f6368; --devsite-bookmark-icon-color-saved: #1a73e8; --devsite-bookmark-icon-color-saved-hover: #174ea6; --devsite-dropdown-list-toggle-background-hover: #f1f3f4; --devsite-dropdown-list-toggle-border: 1px solid #dadce0; --devsite-dropdown-list-toggle-border-hover: 1px solid #dadce0; --devsite-dropdown-list-toggle-height: 36px; display: inline-flex; -webkit-box-align: center; align-items: center; background: none 0px 50% / auto repeat scroll padding-box border-box rgba(0, 0, 0, 0); border: 0px; box-shadow: none; cursor: pointer; height: 36px; -webkit-box-pack: center; justify-content: center; margin: 0px; padding: 0px; vertical-align: middle;"><devsite-dropdown-list aria-label="Bookmark collections drop down" ellipsis="" checkboxes="" fetchingitems="true" writable="" additemtext="New Collection" rendered="" style="--devsite-checkbox-icon-canvas-offset-x: -10px; --devsite-checkbox-icon-canvas-offset-y: -8px; --devsite-checkbox-offset-x: 4px; --devsite-checkbox-offset-y: -2px; --devsite-mdc-line-height: 50px; display: inline-flex; position: relative; vertical-align: middle; box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; --devsite-button-box-shadow: none; visibility: visible;"><button class="toggle-button button" aria-haspopup="menu" id="dropdown-list-0-toggle" aria-controls="dropdown-list-0-dropdown" aria-expanded="false" aria-label="Open dropdown" style="align-self: auto; appearance: none; background: 0px center; border-color: rgb(218, 220, 224); border-style: solid; border-width: 1px; border-image: none 100% / 1 / 0 stretch; border-radius: 4px; box-shadow: none; box-sizing: border-box; color: rgb(95, 99, 104); cursor: pointer; display: flex; font: 500 14px / 34px &quot;Google Sans&quot;, &quot;Noto Sans&quot;, &quot;Noto Sans JP&quot;, &quot;Noto Sans KR&quot;, &quot;Noto Naskh Arabic&quot;, &quot;Noto Sans Thai&quot;, &quot;Noto Sans Hebrew&quot;, &quot;Noto Sans Bengali&quot;, sans-serif; height: 36px; letter-spacing: normal; max-width: none; min-width: auto; outline: 0px; overflow: hidden; padding: 0px 3px; text-align: center; text-decoration: none; text-overflow: ellipsis; text-transform: none; transition: background-color 0.2s, border 0.2s, box-shadow 0.2s; vertical-align: middle; white-space: nowrap; width: auto; margin: 0px; margin-inline-end: 0px; -webkit-box-align: center; -webkit-box-pack: center; align-items: center; justify-content: center;"><slot name="toggle"><span data-label="devsite-bookmark-direct-action" data-title="Save page" class="material-icons bookmark-icon bookmark-action" slot="toggle" style="-webkit-font-smoothing: antialiased; text-rendering: optimizelegibility; overflow-wrap: normal; font-style: normal; font-variant: normal; font-size-adjust: none; font-language-override: normal; font-kerning: auto; font-optical-sizing: auto; font-feature-settings: &quot;liga&quot;; font-variation-settings: normal; font-weight: normal; font-stretch: normal; font-size: 24px; line-height: 1; font-family: &quot;Material Icons&quot;; text-transform: none; box-sizing: inherit; letter-spacing: normal; display: inline-block; white-space: nowrap; direction: ltr; color: rgb(95, 99, 104); transition: color 0.2s; vertical-align: bottom;">bookmark_border</span></slot></button></devsite-dropdown-list></devsite-bookmark></slot></devsite-feature-tooltip></devsite-actions></h1><devsite-toc class="devsite-nav devsite-toc-embedded" depth="2" devsite-toc-embedded="" visible="" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; font-size: 13px; display: block; margin: 28px 0px 24px;"><ul class="devsite-nav-list" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 0px; padding: 0px; list-style: outside none; border-inline-start: 4px solid rgb(25, 103, 210); width: auto; padding-inline-start: 12px;"><li class="devsite-nav-item devsite-nav-heading devsite-toc-toggle" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 0px; padding: 0px; line-height: 16px; display: flex;"></li><li class="devsite-nav-item" visible="" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 0px; padding: 0px; line-height: 16px; display: block;"></li><li class="devsite-toc-toggle" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 0px; padding: 0px; display: flex;"></li></ul></devsite-toc><div class="devsite-article-body clearfix" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 16px 0px 0px; padding: 0px;"><p style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 0px 0px 16px; padding: 0px; color: rgb(32, 33, 36); font-family: Roboto, &quot;Noto Sans&quot;, &quot;Noto Sans JP&quot;, &quot;Noto Sans KR&quot;, &quot;Noto Naskh Arabic&quot;, &quot;Noto Sans Thai&quot;, &quot;Noto Sans Hebrew&quot;, &quot;Noto Sans Bengali&quot;, sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><a href="https://pypi.org/" class="external" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">Python Package Index</a><span> </span>(PyPI) is a public repository for Python packages. You can use Artifact Registry to create private repositories for your Python packages. These private repositories use the canonical Python repository implementation, the<span> </span><a href="https://www.python.org/dev/peps/pep-0503/" class="external" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">simple repository API</a><span> </span>(PEP 503), and work with installation tools like<span> </span><code translate="no" dir="ltr" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; background: none 0% 0% / auto repeat scroll padding-box border-box rgb(241, 243, 244); color: rgb(55, 71, 79); font-style: normal; font-variant: normal; font-weight: 500; font-stretch: 100%; font-size: 14.4px; line-height: 14.4px; font-family: &quot;Roboto Mono&quot;, monospace; font-optical-sizing: auto; font-size-adjust: none; font-kerning: auto; font-variation-settings: normal; font-language-override: normal; padding: 1px 4px; direction: ltr !important; text-align: left !important; border-color: rgb(55, 71, 79); border-style: none; border-width: 0px; border-image: none 100% / 1 / 0 stretch; border-radius: 0px; word-break: break-word;">pip</code>.</p><h2 id="overview" data-text="Overview" tabindex="-1" role="presentation" style="box-sizing: inherit; font: 400 24px / 32px &quot;Google Sans&quot;, &quot;Noto Sans&quot;, &quot;Noto Sans JP&quot;, &quot;Noto Sans KR&quot;, &quot;Noto Naskh Arabic&quot;, &quot;Noto Sans Thai&quot;, &quot;Noto Sans Hebrew&quot;, &quot;Noto Sans Bengali&quot;, sans-serif; letter-spacing: normal; margin: 48px 0px 24px; overflow-x: clip; text-overflow: ellipsis; border-bottom: 0px none rgb(32, 33, 36); padding: 0px; color: rgb(32, 33, 36); orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><span class="devsite-heading" role="heading" aria-level="2" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;;">Overview</span><button type="button" class="devsite-heading-link button-flat material-icons" aria-label="Copy link to this section: Overview" data-title="Copy link to this section: Overview" data-id="overview" style="box-sizing: border-box; font-feature-settings: &quot;liga&quot;; appearance: none; align-self: auto; background: none 0px 50% / auto repeat scroll padding-box border-box rgba(0, 0, 0, 0); border: 0px; border-radius: 4px; box-shadow: none; color: rgb(95, 99, 104); cursor: pointer; display: inline-block; font-style: normal; font-variant: normal; font-weight: normal; font-stretch: 100%; font-size: 24px; font-family: &quot;Material Icons&quot;; font-optical-sizing: auto; font-size-adjust: none; font-kerning: auto; font-variation-settings: normal; font-language-override: normal; height: 24px; letter-spacing: normal; line-height: 24px; margin: 0px; margin-inline-end: 0px; max-width: none; min-width: 36px; outline: 0px; overflow: hidden; padding: 0px 24px; text-align: center; text-decoration: none; text-overflow: ellipsis; text-transform: none; transition: background-color 0.2s, border 0.2s, box-shadow 0.2s; vertical-align: middle; white-space: nowrap; width: auto; overflow-wrap: normal; direction: ltr; -webkit-font-smoothing: antialiased; padding-inline: 8px; --devsite-button-white-line-height: 24px; --devsite-button-white-background-hover: transparent; opacity: 0;"></button></h2><p style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 16px 0px; padding: 0px; color: rgb(32, 33, 36); font-family: Roboto, &quot;Noto Sans&quot;, &quot;Noto Sans JP&quot;, &quot;Noto Sans KR&quot;, &quot;Noto Naskh Arabic&quot;, &quot;Noto Sans Thai&quot;, &quot;Noto Sans Hebrew&quot;, &quot;Noto Sans Bengali&quot;, sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">To get familiar with Python packages in Artifact Registry, you can try the<span> </span><a href="https://docs.cloud.google.com/artifact-registry/docs/python/quickstart" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">quickstart</a>.</p><p style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 16px 0px; padding: 0px; color: rgb(32, 33, 36); font-family: Roboto, &quot;Noto Sans&quot;, &quot;Noto Sans JP&quot;, &quot;Noto Sans KR&quot;, &quot;Noto Naskh Arabic&quot;, &quot;Noto Sans Thai&quot;, &quot;Noto Sans Hebrew&quot;, &quot;Noto Sans Bengali&quot;, sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;">When you are ready to learn more, read the following information:</p><ol style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 0px; padding-left: 40px; list-style: outside decimal; color: rgb(32, 33, 36); font-family: Roboto, &quot;Noto Sans&quot;, &quot;Noto Sans JP&quot;, &quot;Noto Sans KR&quot;, &quot;Noto Naskh Arabic&quot;, &quot;Noto Sans Thai&quot;, &quot;Noto Sans Hebrew&quot;, &quot;Noto Sans Bengali&quot;, sans-serif; font-size: 16px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; background-color: rgb(255, 255, 255); text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial;"><li style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 12px 0px; padding: 0px;"><a href="https://docs.cloud.google.com/artifact-registry/docs/repositories/create-repos" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">Create a Python package repository</a><span> </span>for your packages.</li><li style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 12px 0px; padding: 0px;"><a href="https://docs.cloud.google.com/artifact-registry/docs/access-control" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">Grant permissions</a><span> </span>to the account that will connect with the repository. Service accounts for common integrations with Artifact Registry have default<span> </span><a href="https://docs.cloud.google.com/artifact-registry/docs/access-control#gcp" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">permissions</a><span> </span>for repositories in the same project.</li><li style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 12px 0px; padding: 0px;">Configure your tools:<ul style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 0px; padding-left: 40px; list-style: outside disc;"><li style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 12px 0px; padding: 0px;"><a href="https://docs.cloud.google.com/artifact-registry/docs/python/authentication" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">Configure authentication</a><span> </span>for Python clients that interact with the repository.</li><li style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 12px 0px; padding: 0px;"><a href="https://docs.cloud.google.com/artifact-registry/docs/configure-cloud-build" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">Configure Cloud Build</a><span> </span>to upload and download packages.</li><li style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; margin: 12px 0px; padding: 0px;">Learn about<span> </span><a href="https://docs.cloud.google.com/artifact-registry/docs/deploy" style="box-sizing: inherit; font-feature-settings: &quot;dgun&quot;; color: rgb(26, 115, 232); outline: 0px; text-decoration: rgb(26, 115, 232); word-break: break-word;">deploying</a><span> </span>to Google Cloud runtime environments.</li></ul></li></ol><br class="Apple-interchange-newline">`;
 
   const cleaned = await cleanHTML(html);
@@ -47,4 +45,4 @@ test('cleaner: handles leading OL/UL tags correctly', async () => {
   assert.strictEqual(cleaned.toLowerCase().startsWith('<ol'), false);
   assert.strictEqual(cleaned.toLowerCase().includes('<h1'), true);
   assert.strictEqual(cleaned.toLowerCase().includes('manage python packages'), true);
-});
+});

package/test/node/converter.test.js

@@ -1,6 +1,6 @@
-import { test } from 'node:test';
+import {test} from 'node:test';
 import assert from 'node:assert';
-import { getConverter } from '../../src/converter.js';
+import {getConverter} from '../../src/converter.js';
 
 test('converter: turndown should convert HTML to Markdown', async () => {
   const converter = await getConverter('turndown');
@@ -10,9 +10,12 @@ test('converter: turndown should convert HTML to Markdown', async () => {
 });
 
 test('converter: unknown converter should throw error', async () => {
-  await assert.rejects(async () => {
-    await getConverter('non-existent');
-  }, {
-    message: 'Unknown converter: non-existent. Available converters: turndown, pandoc'
-  });
+  await assert.rejects(
+    async () => {
+      await getConverter('non-existent');
+    },
+    {
+      message: 'Unknown converter: non-existent. Available converters: turndown, pandoc',
+    }
+  );
 });

package/test/node/index.test.js

@@ -1,6 +1,6 @@
-import { test } from 'node:test';
+import {test} from 'node:test';
 import assert from 'node:assert';
-import { convert } from '../../src/markpaste.js';
+import {convert} from '../../src/index.js';
 
 test('library: convert should use turndown by default', async () => {
   const html = '<h1>Hello</h1>';
@@ -10,7 +10,7 @@ test('library: convert should use turndown by default', async () => {
 
 test('library: convert should support pandoc', async () => {
   const html = '<p>Hello <b>World</b></p>';
-  const markdown = await convert(html, { converter: 'pandoc' });
+  const markdown = await convert(html, {converter: 'pandoc'});
   assert.strictEqual(markdown.includes('Hello'), true);
   assert.strictEqual(markdown.includes('World'), true);
 });
@@ -18,6 +18,19 @@ test('library: convert should support pandoc', async () => {
 test('library: convert should support disabling cleaning', async () => {
   const html = '<div style="color: red;"><p>Hello</p></div>';
   // If clean is false, it uses removeStyleAttributes which unwraps but might keep some structure
-  const markdown = await convert(html, { clean: false });
+  const markdown = await convert(html, {clean: false});
   assert.strictEqual(markdown.includes('Hello'), true);
 });
+
+test('library: convert should short-circuit if markdown is detected', async () => {
+  const markdownInput = '# Already Markdown\n\n- item';
+  const result = await convert(markdownInput);
+  assert.strictEqual(result, markdownInput);
+});
+
+test('library: convert should NOT short-circuit if isMarkdown: false is passed', async () => {
+  const input = '# Not Markdown'; // Looks like MD, but we force it not to be
+  const result = await convert(input, {isMarkdown: false});
+  // Turndown escapes # if it's not a real header
+  assert.strictEqual(result.trim(), '\\# Not Markdown');
+});

package/test/node/markpaste.test.js

@@ -0,0 +1,72 @@
+import {test} from 'node:test';
+import assert from 'node:assert';
+import {execSync, spawnSync} from 'node:child_process';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import os from 'node:os';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLIP_TOOL = path.resolve(__dirname, '../../bin/markpaste');
+
+// This test only works on macOS
+if (os.platform() === 'darwin') {
+  test('markpaste cli: round-trip conversion', async () => {
+    const testContent = '<h1>Test</h1><p><b>Bold</b></p>';
+
+    // 1. Set initial clipboard state
+    const htmlHex = Buffer.from(testContent, 'utf8').toString('hex');
+    const setScript = `set the clipboard to {«class HTML»:«data HTML${htmlHex}», text:"${testContent}"}`;
+    spawnSync('osascript', ['-e', setScript]);
+
+    // 2. Run markpaste
+    execSync(`"${CLIP_TOOL}"`, {encoding: 'utf8'});
+
+    // 3. Verify Plain Text flavor (should be Markdown)
+    const plainText = execSync('osascript -e "get (the clipboard as string)"', {encoding: 'utf8'}).trim();
+    assert.strictEqual(plainText.includes('# Test'), true);
+    assert.strictEqual(plainText.includes('**Bold**'), true);
+
+    // 4. Verify HTML flavor (should be cleaned HTML)
+    const htmlData = execSync('osascript -e "get (the clipboard as «class HTML»)"', {encoding: 'utf8'}).trim();
+    assert.strictEqual(htmlData.includes('«data HTML'), true);
+
+    // Extract hex and convert back to string
+    const match = htmlData.match(/«data HTML([0-9A-F]*)»/i);
+    if (match && match[1]) {
+      const resultHtml = Buffer.from(match[1], 'hex').toString('utf8');
+      assert.strictEqual(resultHtml.toLowerCase().includes('<h1>test</h1>'), true);
+      assert.strictEqual(resultHtml.toLowerCase().includes('<b>bold</b>'), true);
+    } else {
+      assert.fail('Could not extract HTML hex from clipboard');
+    }
+  });
+
+  test('markpaste cli: markdown to html conversion', async () => {
+    const markdownInput = '# MD Test\n\n- item 1';
+
+    // 1. Set clipboard to plain text only (no HTML flavor)
+    execSync('pbcopy', {input: markdownInput});
+    // Verify no HTML flavor exists (or at least we want to simulate that state)
+    // Actually pbcopy only sets text flavor, so this is perfect.
+
+    // 2. Run markpaste
+    execSync(`"${CLIP_TOOL}"`, {encoding: 'utf8'});
+
+    // 3. Verify HTML flavor (should be rendered HTML)
+    const htmlData = execSync('osascript -e "get (the clipboard as «class HTML»)"', {encoding: 'utf8'}).trim();
+    assert.strictEqual(htmlData.includes('«data HTML'), true);
+
+    const match = htmlData.match(/«data HTML([0-9A-F]*)»/i);
+    const resultHtml = Buffer.from(match[1], 'hex').toString('utf8');
+    assert.strictEqual(resultHtml.toLowerCase().includes('<h1>md test</h1>'), true);
+    assert.strictEqual(resultHtml.toLowerCase().includes('<li>item 1</li>'), true);
+
+    // 4. Verify Plain Text flavor (should be original markdown)
+    const plainText = execSync('osascript -e "get (the clipboard as string)"', {encoding: 'utf8'}).trim();
+    assert.strictEqual(plainText, markdownInput);
+  });
+} else {
+  test('markpaste cli: skipped on non-macOS', () => {
+    // Pass
+  });
+}

package/test/node/pandoc.test.js

@@ -1,12 +1,12 @@
-import { test } from 'node:test';
+import {test} from 'node:test';
 import assert from 'node:assert';
-import { getConverter } from '../../src/converter.js';
+import {getConverter} from '../../src/converter.js';
 
 test('pandoc: converter should convert HTML to Markdown', async () => {
   const converter = await getConverter('pandoc');
   const html = '<h1>Hello</h1>';
   const markdown = converter.convert(html);
-  
+
   assert.strictEqual(markdown.includes('Hello'), true);
   // Pandoc usually adds its own flavor of Markdown
   assert.strictEqual(markdown.includes('#'), true);

package/test/web/basic-load.spec.ts

@@ -1,6 +1,6 @@
-import { test, expect } from '@playwright/test';
+import {test, expect} from '@playwright/test';
 
-test('should load the page without errors or 404s', async ({ page }) => {
+test('should load the page without errors or 404s', async ({page}) => {
   const failedRequests: string[] = [];
   const consoleErrors: string[] = [];
 
@@ -39,14 +39,14 @@ test('should load the page without errors or 404s', async ({ page }) => {
   await expect(page.locator('h1')).toHaveText('MarkPaste');
 });
 
-test('should paste HTML and update all 2 markdown outputs', async ({ page }) => {
+test('should paste HTML and update all 2 markdown outputs', async ({page}) => {
   await page.goto('http://127.0.0.1:8081/index.html');
 
   const inputArea = page.locator('#inputArea');
   const testHtml = '<h1>Test Title</h1><p>Hello <strong>world</strong></p>';
 
   // Simulate paste event
-  await page.evaluate((html) => {
+  await page.evaluate(html => {
     const el = document.querySelector('#inputArea');
     if (!el) return;
     const dataTransfer = new DataTransfer();

package/test/web/pasting.spec.ts

@@ -77,7 +77,7 @@ test.describe('MarkPaste functionality', () => {
     // Uncheck "Clean HTML"
     await page.locator('#cleanHtmlToggle').uncheck();
     // Wait for update
-    await page.waitForTimeout(100); 
+    await page.waitForTimeout(100);
 
     expect(await htmlCode.textContent()).toContain('<div>');
     expect(await htmlCode.textContent()).not.toContain('<script>');
@@ -114,4 +114,31 @@ test.describe('MarkPaste functionality', () => {
     await expect(htmlCode).toContainText('<td');
     await expect(htmlCode).toContainText('<th');
   });
+
+  test('should handle pasting markdown and pipe it through', async ({page}) => {
+    const markdown = '# This is Markdown\n\n- List item 1\n- List item 2';
+
+    // Simulate paste event
+    await page.evaluate(text => {
+      const inputArea = document.getElementById('inputArea');
+      const dataTransfer = new DataTransfer();
+      dataTransfer.setData('text/plain', text);
+      const event = new ClipboardEvent('paste', {
+        clipboardData: dataTransfer,
+        bubbles: true,
+        cancelable: true,
+      });
+      inputArea.dispatchEvent(event);
+    }, markdown);
+
+    const outputCode = page.locator('#outputCodeTurndown');
+    await expect(outputCode).toHaveText(markdown);
+
+    const htmlCode = page.locator('#htmlCode');
+    // It should be rendered HTML in the preview
+    const htmlText = await htmlCode.innerText();
+    expect(htmlText).toContain('<h1>This is Markdown</h1>');
+    expect(htmlText).toContain('<ul>');
+    expect(htmlText).toContain('<li>List item 1</li>');
+  });
 });

package/types/globals.d.ts

@@ -29,19 +29,22 @@ declare global {
     on(name: string, fn: EventListenerOrEventListenerObject): void;
   }
 
-
   // idle detector
 
   interface IdleDetector {
-    addEventListener(type: "change", listener: (this: IdleDetector, ev: { userState: "active" | "idle", screenState: "locked" | "unlocked" }) => unknown, options?: boolean | AddEventListenerOptions): void;
-    start(options: { threshold: number; signal?: AbortSignal }): Promise<void>;
-    screenState: "locked" | "unlocked";
-    userState: "active" | "idle";
+    addEventListener(
+      type: 'change',
+      listener: (this: IdleDetector, ev: {userState: 'active' | 'idle'; screenState: 'locked' | 'unlocked'}) => unknown,
+      options?: boolean | AddEventListenerOptions
+    ): void;
+    start(options: {threshold: number; signal?: AbortSignal}): Promise<void>;
+    screenState: 'locked' | 'unlocked';
+    userState: 'active' | 'idle';
   }
 
   declare const IdleDetector: {
-      new(): IdleDetector;
-      requestPermission(): Promise<"granted" | "denied">;
+    new (): IdleDetector;
+    requestPermission(): Promise<'granted' | 'denied'>;
   };
 }
 /// <reference path="pandoc-wasm.d.ts" />

package/src/markpaste.js

@@ -1,26 +0,0 @@
-/**
- * markpaste.js
- * MarkPaste Library Entry Point
- */
-
-import { cleanHTML, removeStyleAttributes } from './cleaner.js';
-import { getConverter } from './converter.js';
-
-/**
- * Converts HTML to Markdown using the specified converter.
- * @param {string} html The HTML string to convert.
- * @param {Object} options Configuration options.
- * @param {string} [options.converter='turndown'] The converter to use ('turndown', 'pandoc').
- * @param {boolean} [options.clean=true] Whether to clean the HTML before conversion.
- * @returns {Promise<string>} The resulting Markdown string.
- */
-export async function convert(html, options = {}) {
-  const { converter: converterName = 'turndown', clean = true } = options;
-
-  const cleanedHtml = clean ? await cleanHTML(html) : await removeStyleAttributes(html);
-  const converter = await getConverter(converterName);
-
-  return converter.convert(cleanedHtml);
-}
-
-export { cleanHTML, removeStyleAttributes, getConverter };