नेटिव मीडिया + सिस्टम उपयोगिताएँ

यह दस्तावेज़ docs/natives-architecture.md में वर्णित system/media/conversion primitives परत का एक सबसिस्टम गहन-विश्लेषण है: image, html, clipboard, और work प्रोफाइलिंग।

इम्प्लीमेंटेशन फ़ाइलें

• crates/pi-natives/src/image.rs
• crates/pi-natives/src/html.rs
• crates/pi-natives/src/clipboard.rs
• crates/pi-natives/src/prof.rs
• crates/pi-natives/src/task.rs
• packages/natives/src/image/index.ts
• packages/natives/src/image/types.ts
• packages/natives/src/html/index.ts
• packages/natives/src/html/types.ts
• packages/natives/src/clipboard/index.ts
• packages/natives/src/clipboard/types.ts
• packages/natives/src/work/index.ts
• packages/natives/src/work/types.ts

नोट: कोई crates/pi-natives/src/work.rs नहीं है; work प्रोफाइलिंग prof.rs में इम्प्लीमेंट की गई है और task.rs में इंस्ट्रूमेंटेशन द्वारा फीड की जाती है।

TS API ↔ Rust एक्सपोर्ट/मॉड्यूल मैपिंग

TS एक्सपोर्ट (packages/natives)	Rust N-API एक्सपोर्ट	Rust मॉड्यूल
PhotonImage.parse(bytes)	PhotonImage::parse	image.rs
PhotonImage#resize(width, height, filter)	PhotonImage::resize	image.rs
PhotonImage#encode(format, quality)	PhotonImage::encode	image.rs
htmlToMarkdown(html, options)	html_to_markdown	html.rs
copyToClipboard(text)	copy_to_clipboard + TS फ़ॉलबैक लॉजिक	clipboard.rs + clipboard/index.ts
readImageFromClipboard()	read_image_from_clipboard	clipboard.rs
getWorkProfile(lastSeconds)	get_work_profile	prof.rs

डेटा फ़ॉर्मेट सीमाएँ और रूपांतरण

इमेज (image)

• JS इनपुट सीमा: Uint8Array एन्कोडेड इमेज बाइट्स।
• Rust डिकोड सीमा: बाइट्स को Vec<u8> में कॉपी किया जाता है, फ़ॉर्मेट का अनुमान ImageReader::with_guessed_format() से लगाया जाता है, फिर DynamicImage में डिकोड किया जाता है।
• इन-मेमोरी स्टेट: PhotonImage में Arc<DynamicImage> स्टोर होता है।
• आउटपुट सीमा: encode(format, quality) Promise<Uint8Array> (Rust Vec<u8>) लौटाता है।

फ़ॉर्मेट ID न्यूमेरिक हैं:

• 0: PNG
• 1: JPEG
• 2: WebP (lossless एनकोडर)
• 3: GIF

बाधाएँ:

• quality केवल JPEG के लिए उपयोग होती है।
• PNG/WebP/GIF quality को अनदेखा करते हैं।
• असमर्थित फ़ॉर्मेट ID विफल होते हैं (Invalid image format: <id>)।

HTML रूपांतरण (html)

• JS इनपुट सीमा: HTML string + वैकल्पिक ऑब्जेक्ट { cleanContent?: boolean; skipImages?: boolean }।
• Rust रूपांतरण सीमा: String इनपुट को html_to_markdown_rs::convert द्वारा रूपांतरित किया जाता है।
• आउटपुट सीमा: Markdown string।

रूपांतरण व्यवहार:

• cleanContent डिफ़ॉल्ट रूप से false है।
• जब cleanContent=true हो, तो PreprocessingPreset::Aggressive और नेविगेशन/फॉर्म के लिए हार्ड-रिमूवल फ़्लैग के साथ प्रीप्रोसेसिंग सक्षम होती है।
• skipImages डिफ़ॉल्ट रूप से false है।

क्लिपबोर्ड (clipboard)

• टेक्स्ट पथ:
  • TS पहले OSC 52 (\x1b]52;c;<base64>\x07) उत्सर्जित करता है जब stdout एक TTY हो।
  • फिर उसी टेक्स्ट को नेटिव क्लिपबोर्ड API (native.copyToClipboard) के माध्यम से बेस्ट-एफ़र्ट प्रयास किया जाता है।
  • Termux पर, TS पहले termux-clipboard-set का प्रयास करता है।
• इमेज रीड पथ:
  • Rust arboard से रॉ इमेज पढ़ता है।
  • Rust इसे PNG बाइट्स (image crate) में पुनः एन्कोड करता है, { data: Uint8Array, mimeType: "image/png" } लौटाता है।
  • TS Termux पर या बिना डिस्प्ले सर्वर (DISPLAY/WAYLAND_DISPLAY अनुपस्थित) वाले Linux सेशन पर जल्दी null लौटाता है।

Work प्रोफाइलिंग (work)

• संग्रह सीमा: प्रोफाइलिंग सैंपल task::blocking और task::future में profile_region(tag) गार्ड द्वारा उत्पन्न होते हैं।
• स्टोरेज फ़ॉर्मेट: निश्चित आकार का सर्कुलर बफ़र (MAX_SAMPLES = 10_000) जो स्टैक पाथ + अवधि (μs) + टाइमस्टैम्प (μs since process start) स्टोर करता है।
• आउटपुट सीमा: getWorkProfile(lastSeconds) ऑब्जेक्ट लौटाता है:
  • folded: फ़ोल्डेड-स्टैक टेक्स्ट (flamegraph इनपुट)
  • summary: markdown टेबल सारांश
  • svg: वैकल्पिक flamegraph SVG
  • totalMs, sampleCount

जीवनचक्र और स्टेट ट्रांज़िशन

इमेज जीवनचक्र

1. PhotonImage.parse(bytes) एक ब्लॉकिंग डिकोड टास्क (image.decode) शेड्यूल करता है।
2. सफलता पर, JS में एक नेटिव PhotonImage हैंडल मौजूद होता है।
3. resize(...) एक नया नेटिव हैंडल (image.resize) बनाता है, पुराने और नए हैंडल साथ-साथ रह सकते हैं।
4. encode(...) इमेज डाइमेंशन को म्यूटेट किए बिना बाइट्स (image.encode) मटेरियलाइज़ करता है।

विफलता ट्रांज़िशन:

• फ़ॉर्मेट डिटेक्शन/डिकोड विफलता parse promise को रिजेक्ट करती है।
• एन्कोड विफलता encode promise को रिजेक्ट करती है।
• अमान्य फ़ॉर्मेट ID encode promise को रिजेक्ट करती है।

HTML जीवनचक्र

1. htmlToMarkdown(html, options) एक ब्लॉकिंग रूपांतरण टास्क शेड्यूल करता है।
2. रूपांतरण डिफ़ॉल्ट विकल्पों (cleanContent=false, skipImages=false) के साथ चलता है जब तक निर्दिष्ट न हो।
3. markdown स्ट्रिंग लौटाता है या रिजेक्ट करता है।

विफलता ट्रांज़िशन:

• कनवर्टर विफलता रिजेक्टेड promise लौटाती है (Conversion error: ...)।

क्लिपबोर्ड जीवनचक्र

copyToClipboard(text) जानबूझकर बेस्ट-एफ़र्ट और मल्टी-पाथ है:

1. यदि TTY: OSC 52 राइट का प्रयास करें (base64 पेलोड)।
2. TERMUX_VERSION सेट होने पर Termux कमांड आज़माएँ।
3. नेटिव arboard टेक्स्ट कॉपी आज़माएँ।
4. TS लेयर पर एरर को निगल लें।

readImageFromClipboard() की सख्ती चरण के अनुसार भिन्न होती है:

1. TS असमर्थित रनटाइम संदर्भों (Termux/headless Linux) को null पर हार्ड-गेट करता है।
2. Rust arboard रीड केवल तभी चलती है जब TS इसकी अनुमति दे।
3. ContentNotAvailable को null पर मैप किया जाता है।
4. अन्य Rust एरर रिजेक्ट करते हैं।

Work प्रोफाइलिंग जीवनचक्र

1. कोई स्पष्ट शुरुआत नहीं: जब टास्क हेल्पर्स निष्पादित होते हैं तो प्रोफाइलिंग हमेशा चालू रहती है।
2. प्रत्येक इंस्ट्रूमेंटेड टास्क स्कोप गार्ड ड्रॉप पर एक सैंपल रिकॉर्ड करता है।
3. बफ़र क्षमता पहुँचने के बाद सैंपल सबसे पुरानी एंट्री को ओवरराइट करते हैं।
4. getWorkProfile(lastSeconds) एक टाइम विंडो पढ़ता है और folded/summary/svg आर्टिफैक्ट निकालता है।

विफलता ट्रांज़िशन:

• SVG जनरेशन विफलता सॉफ्ट-फेल है (svg: null), जबकि folded और summary फिर भी लौटते हैं।
• खाली सैंपल विंडो खाली folded डेटा और svg: null लौटाती है, न कि एरर।

असमर्थित ऑपरेशन और एरर प्रोपेगेशन

इमेज

• असमर्थित डिकोड इनपुट या दूषित बाइट्स: सख्त विफलता (promise रिजेक्शन)।
• असमर्थित एन्कोड फ़ॉर्मेट ID: सख्त विफलता।
• TS रैपर में कोई बेस्ट-एफ़र्ट फ़ॉलबैक पाथ नहीं।

HTML

• रूपांतरण एरर सख्त विफलताएँ हैं (रिजेक्शन)।
• विकल्प छोड़ना बेस्ट-एफ़र्ट डिफ़ॉल्टिंग है, विफलता नहीं।

क्लिपबोर्ड

• टेक्स्ट कॉपी TS लेयर पर बेस्ट-एफ़र्ट है: ऑपरेशनल विफलताएँ दबाई जाती हैं।
• इमेज रीड “कोई इमेज नहीं” (null) और ऑपरेशनल विफलता (रिजेक्शन) के बीच अंतर करता है।
• Termux/headless Linux को इमेज रीड के लिए असमर्थित संदर्भ माना जाता है (null)।

Work प्रोफाइलिंग

• फ़ंक्शन कॉल के लिए रिट्रीवल सख्त है, लेकिन आर्टिफैक्ट जनरेशन आंशिक रूप से बेस्ट-एफ़र्ट है (svg nullable)।
• बफ़र ट्रंकेशन अपेक्षित व्यवहार है (ring buffer), डेटा हानि बग नहीं।

प्लेटफ़ॉर्म संबंधी चेतावनियाँ

• क्लिपबोर्ड टेक्स्ट: OSC 52 टर्मिनल समर्थन पर निर्भर करता है; नेटिव क्लिपबोर्ड एक्सेस डेस्कटॉप वातावरण/सेशन पर निर्भर करती है।
• क्लिपबोर्ड इमेज रीड: Termux और बिना डिस्प्ले सर्वर वाले Linux के लिए TS में ब्लॉक है।