@bcelep/capint 0.4.2 → 0.6.5

package/skills/pdf/agents/verdent.yaml

@@ -0,0 +1,9 @@
+category: Media & Files
+interface:
+  display_name: 'PDF'
+  short_description: 'Read, analyze, and create PDFs'
+  icon_dark: './assets/icon-dark.png'
+  icon_light: './assets/icon-light.png'
+  default_prompt: 'Create, edit, or review this PDF and summarize the key output or changes.'
+  builtin: true
+  hidden: true

package/skills/pdf/reference.md

@@ -0,0 +1,221 @@
+# PDF Reading — Advanced Reference
+
+Supplementary material for advanced extraction, performance, and troubleshooting scenarios. Load this file only when the main SKILL.md guidance is insufficient.
+
+## Table of Contents
+
+- [pypdfium2 Text & Rendering](#pypdfium2-text--rendering)
+- [Bounding-Box Text Export](#bounding-box-text-export)
+- [pdfplumber Deep-Dive](#pdfplumber-deep-dive)
+- [Batch Processing](#batch-processing)
+- [Memory-Efficient Chunked Reading](#memory-efficient-chunked-reading)
+- [Performance Notes](#performance-notes)
+- [Troubleshooting](#troubleshooting)
+- [Library Licenses](#library-licenses)
+
+## pypdfium2 Text & Rendering
+
+pypdfium2 wraps Chromium's PDFium engine. Fast rendering and reliable text output.
+
+### Page Text
+
+```python
+import pypdfium2 as pdfium
+
+pdf = pdfium.PdfDocument("document.pdf")
+for i, page in enumerate(pdf):
+    text = page.get_text()
+    print(f"Page {i+1}: {len(text)} chars")
+```
+
+### High-Resolution Rendering
+
+```python
+import os
+
+page = pdf[0]
+bitmap = page.render(scale=3.0, rotation=0)
+img = bitmap.to_pil()
+
+img_dir = os.path.join(os.path.dirname("document.pdf") or ".", "images")
+os.makedirs(img_dir, exist_ok=True)
+img.save(os.path.join(img_dir, "hires.png"), "PNG")
+```
+
+### Multi-Page Render
+
+```python
+import os
+
+img_dir = os.path.join(os.path.dirname("document.pdf") or ".", "images")
+os.makedirs(img_dir, exist_ok=True)
+
+for idx, page in enumerate(pdf):
+    bitmap = page.render(scale=1.5)
+    bitmap.to_pil().save(os.path.join(img_dir, f"page_{idx+1}.jpg"), "JPEG", quality=90)
+```
+
+## Bounding-Box Text Export
+
+`pdftotext -bbox-layout` outputs XML with per-word coordinates — useful for spatial analysis or reconstructing layouts programmatically.
+
+```bash
+pdftotext -bbox-layout document.pdf output.xml
+```
+
+The XML contains `<word xMin yMin xMax yMax>` elements for each text fragment.
+
+## pdfplumber Deep-Dive
+
+### Character-Level Data
+
+Every character on a page is available with position, font, and size:
+
+```python
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    page = pdf.pages[0]
+    for ch in page.chars[:30]:
+        print(f"'{ch['text']}' font={ch['fontname']} size={ch['size']:.1f} "
+              f"x={ch['x0']:.1f} y={ch['top']:.1f}")
+```
+
+### Table Strategy Tuning
+
+When default table detection fails:
+
+```python
+strategies = {
+    "vertical_strategy": "text",
+    "horizontal_strategy": "text",
+    "snap_x_tolerance": 5,
+    "snap_y_tolerance": 5,
+    "text_x_tolerance": 3,
+    "text_y_tolerance": 3,
+}
+tables = page.extract_tables(strategies)
+```
+
+Strategy options:
+
+- `"lines"` — use visible ruling lines
+- `"text"` — infer structure from text alignment
+- `"explicit"` — use manually supplied lines
+
+### Visual Debug
+
+Generate an image overlay showing detected table boundaries:
+
+```python
+import os
+
+img = page.to_image(resolution=150)
+img.debug_tablefinder()
+
+img_dir = os.path.join(os.path.dirname("document.pdf") or ".", "images")
+os.makedirs(img_dir, exist_ok=True)
+img.save(os.path.join(img_dir, "debug_tables.png"))
+```
+
+## Batch Processing
+
+Process a folder of PDFs with error isolation so one corrupt file does not abort the entire run.
+
+```python
+import os, glob, logging
+from pypdf import PdfReader
+
+logging.basicConfig(level=logging.INFO)
+log = logging.getLogger(__name__)
+
+def batch_extract_text(input_dir, output_dir):
+    os.makedirs(output_dir, exist_ok=True)
+    for pdf_path in glob.glob(os.path.join(input_dir, "*.pdf")):
+        try:
+            reader = PdfReader(pdf_path)
+            text_parts = []
+            for page in reader.pages:
+                text_parts.append(page.extract_text() or "")
+            out_name = os.path.splitext(os.path.basename(pdf_path))[0] + ".txt"
+            with open(os.path.join(output_dir, out_name), "w", encoding="utf-8") as f:
+                f.write("\n".join(text_parts))
+            log.info("Done: %s", pdf_path)
+        except Exception as exc:
+            log.error("Failed: %s — %s", pdf_path, exc)
+```
+
+## Memory-Efficient Chunked Reading
+
+For very large PDFs, avoid loading all pages at once. Process in fixed-size chunks:
+
+```python
+from pypdf import PdfReader
+
+def chunked_read(pdf_path, chunk=20):
+    reader = PdfReader(pdf_path)
+    total = len(reader.pages)
+    for start in range(0, total, chunk):
+        end = min(start + chunk, total)
+        chunk_text = []
+        for i in range(start, end):
+            chunk_text.append(reader.pages[i].extract_text() or "")
+        yield start, end, "\n".join(chunk_text)
+```
+
+Usage:
+
+```python
+for start, end, text in chunked_read("big.pdf"):
+    print(f"Pages {start+1}-{end}: {len(text)} chars")
+```
+
+## Performance Notes
+
+| Scenario                      | Recommendation                               |
+| ----------------------------- | -------------------------------------------- |
+| Plain text, speed priority    | `pdftotext` CLI is fastest                   |
+| Structured tables             | pdfplumber with strategy tuning              |
+| Page-to-image conversion      | pypdfium2 (lower memory than pdf2image)      |
+| Embedded image extraction     | `pdfimages` CLI (much faster than rendering) |
+| Scanned/image-only PDF        | OCR via pytesseract + pdf2image              |
+| Very large files (>100 pages) | Chunked reading, 20 pages per batch          |
+
+## Troubleshooting
+
+### Empty text from extract_text()
+
+Possible causes:
+
+1. **Scanned PDF** — pages are images, not searchable text. Use OCR.
+2. **Custom encoding** — try pdfplumber or pypdfium2 as alternatives.
+3. **Encrypted** — decrypt first with `reader.decrypt("password")`.
+
+### Garbled characters
+
+Switch libraries. pypdfium2 handles CIDFont mappings better than pypdf in some documents.
+
+### Table extraction misses columns
+
+- Switch strategy from `"lines"` to `"text"` or vice versa.
+- Adjust `snap_tolerance` and `intersection_tolerance`.
+- Use `page.to_image().debug_tablefinder()` to visualize detection.
+
+### Corrupt PDF
+
+```bash
+qpdf --check input.pdf
+qpdf --replace-input input.pdf
+```
+
+## Library Licenses
+
+| Library       | License      |
+| ------------- | ------------ |
+| pypdf         | BSD          |
+| pdfplumber    | MIT          |
+| pypdfium2     | Apache / BSD |
+| pytesseract   | Apache       |
+| pdf2image     | MIT          |
+| poppler-utils | GPL-2        |
+| qpdf          | Apache       |

package/skills/performance/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: performance
+description: Optimize web performance for faster loading and better user experience. Use when asked to "speed up my site", "optimize performance", "reduce load time", "fix slow loading", "improve page speed", or "performance audit".
+license: MIT
+metadata:
+  author: web-quality-skills
+  version: "1.0"
+---
+
+# Performance optimization
+
+Deep performance optimization based on Lighthouse performance audits. Focuses on loading speed, runtime efficiency, and resource optimization.
+
+## How it works
+
+1. Identify performance bottlenecks in code and assets
+2. Prioritize by impact on Core Web Vitals
+3. Provide specific optimizations with code examples
+4. Measure improvement with before/after metrics
+
+## Performance budget
+
+| Resource | Budget | Rationale |
+|----------|--------|-----------|
+| Total page weight | < 1.5 MB | 3G loads in ~4s |
+| JavaScript (compressed) | < 300 KB | Parsing + execution time |
+| CSS (compressed) | < 100 KB | Render blocking |
+| Images (above-fold) | < 500 KB | LCP impact |
+| Fonts | < 100 KB | FOIT/FOUT prevention |
+| Third-party | < 200 KB | Uncontrolled latency |
+
+## Critical rendering path
+
+### Server response
+* **TTFB < 800ms.** Time to First Byte should be fast. Use CDN, caching, and efficient backends.
+* **Enable compression.** Gzip or Brotli for text assets. Brotli preferred (15-20% smaller).
+* **HTTP/2 or HTTP/3.** Multiplexing reduces connection overhead.
+* **Edge caching.** Cache HTML at CDN edge when possible.
+* **Send Early Hints (HTTP 103) for slow origins.** When the origin needs hundreds of milliseconds to assemble the final response, return a `103 Early Hints` with `Link: </hero.webp>; rel=preload; as=image` (and similar for critical CSS/fonts) so the browser starts fetching before the `200 OK` lands. Cloudflare reports [20–30% LCP improvements](https://blog.cloudflare.com/early-hints-performance/) on image-heavy pages. Requires HTTP/2+ and is supported by Chromium-based browsers; other browsers ignore the 103 and fall through to the 200 — safe to enable. CDNs (Cloudflare, Fastly, Akamai) can synthesize 103s automatically from prior responses; on your own origin, emit them from the same handler that issues the 200.
+
+### Resource loading
+
+**Preconnect to required origins:**
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://cdn.example.com" crossorigin>
+```
+
+**Preload critical resources:**
+```html
+<!-- LCP image -->
+<link rel="preload" href="/hero.webp" as="image" fetchpriority="high">
+
+<!-- Critical font -->
+<link rel="preload" href="/font.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+**Prerender likely-next navigations** with the [Speculation Rules API](https://developer.chrome.com/docs/web-platform/prerender-pages):
+```html
+<script type="speculationrules">
+{
+  "prerender": [{
+    "where": { "href_matches": "/*" },
+    "eagerness": "moderate"
+  }]
+}
+</script>
+```
+`moderate` triggers after a ~200ms hover — usually intent-correlated, rarely wasted. See [core-web-vitals → LCP](../core-web-vitals/SKILL.md#lcp-largest-contentful-paint) for the full discussion of eagerness tradeoffs and the `prerenderingchange` gating you'll need for analytics.
+
+**Defer non-critical CSS:**
+```html
+<!-- Critical CSS inlined -->
+<style>/* Above-fold styles */</style>
+
+<!-- Non-critical CSS -->
+<link rel="preload" href="/styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
+<noscript><link rel="stylesheet" href="/styles.css"></noscript>
+```
+
+### JavaScript optimization
+
+**Defer non-essential scripts:**
+```html
+<!-- Parser-blocking (avoid) -->
+<script src="/critical.js"></script>
+
+<!-- Deferred (preferred) -->
+<script defer src="/app.js"></script>
+
+<!-- Async (for independent scripts) -->
+<script async src="/analytics.js"></script>
+
+<!-- Module (deferred by default) -->
+<script type="module" src="/app.mjs"></script>
+```
+
+**Code splitting patterns:**
+```javascript
+// Route-based splitting
+const Dashboard = lazy(() => import('./Dashboard'));
+
+// Component-based splitting
+const HeavyChart = lazy(() => import('./HeavyChart'));
+
+// Feature-based splitting
+if (user.isPremium) {
+  const PremiumFeatures = await import('./PremiumFeatures');
+}
+```
+
+**Tree shaking best practices:**
+```javascript
+// ❌ Imports entire library
+import _ from 'lodash';
+_.debounce(fn, 300);
+
+// ✅ Imports only what's needed
+import debounce from 'lodash/debounce';
+debounce(fn, 300);
+```
+
+## Image optimization
+
+### Format selection
+| Format | Use case | Browser support |
+|--------|----------|-----------------|
+| AVIF | Photos, best compression | 92%+ |
+| WebP | Photos, good fallback | 97%+ |
+| PNG | Graphics with transparency | Universal |
+| SVG | Icons, logos, illustrations | Universal |
+
+### Responsive images
+```html
+<picture>
+  <!-- AVIF for modern browsers -->
+  <source 
+    type="image/avif"
+    srcset="hero-400.avif 400w,
+            hero-800.avif 800w,
+            hero-1200.avif 1200w"
+    sizes="(max-width: 600px) 100vw, 50vw">
+  
+  <!-- WebP fallback -->
+  <source 
+    type="image/webp"
+    srcset="hero-400.webp 400w,
+            hero-800.webp 800w,
+            hero-1200.webp 1200w"
+    sizes="(max-width: 600px) 100vw, 50vw">
+  
+  <!-- JPEG fallback -->
+  <img 
+    src="hero-800.jpg"
+    srcset="hero-400.jpg 400w,
+            hero-800.jpg 800w,
+            hero-1200.jpg 1200w"
+    sizes="(max-width: 600px) 100vw, 50vw"
+    width="1200" 
+    height="600"
+    alt="Hero image"
+    loading="lazy"
+    decoding="async">
+</picture>
+```
+
+### LCP image priority
+```html
+<!-- Above-fold LCP image: eager loading, high priority -->
+<img 
+  src="hero.webp" 
+  fetchpriority="high"
+  loading="eager"
+  decoding="sync"
+  alt="Hero">
+
+<!-- Below-fold images: lazy loading -->
+<img 
+  src="product.webp" 
+  loading="lazy"
+  decoding="async"
+  alt="Product">
+```
+
+## Font optimization
+
+### Loading strategy
+```css
+/* System font stack as fallback */
+body {
+  font-family: 'Custom Font', -apple-system, BlinkMacSystemFont, 
+               'Segoe UI', Roboto, sans-serif;
+}
+
+/* Prevent invisible text */
+@font-face {
+  font-family: 'Custom Font';
+  src: url('/fonts/custom.woff2') format('woff2');
+  font-display: swap; /* or optional for non-critical */
+  font-weight: 400;
+  font-style: normal;
+  unicode-range: U+0000-00FF; /* Subset to Latin */
+}
+```
+
+### Preloading critical fonts
+```html
+<link rel="preload" href="/fonts/heading.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+### Variable fonts
+```css
+/* One file instead of multiple weights */
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-display: swap;
+}
+```
+
+## Caching strategy
+
+### Cache-Control headers
+```
+# HTML (short or no cache)
+Cache-Control: no-cache, must-revalidate
+
+# Static assets with hash (immutable)
+Cache-Control: public, max-age=31536000, immutable
+
+# Static assets without hash
+Cache-Control: public, max-age=86400, stale-while-revalidate=604800
+
+# API responses
+Cache-Control: private, max-age=0, must-revalidate
+```
+
+### Service worker caching
+```javascript
+// Cache-first for static assets
+self.addEventListener('fetch', (event) => {
+  if (event.request.destination === 'image' ||
+      event.request.destination === 'style' ||
+      event.request.destination === 'script') {
+    event.respondWith(
+      caches.match(event.request).then((cached) => {
+        return cached || fetch(event.request).then((response) => {
+          const clone = response.clone();
+          caches.open('static-v1').then((cache) => cache.put(event.request, clone));
+          return response;
+        });
+      })
+    );
+  }
+});
+```
+
+## Runtime performance
+
+### Avoid layout thrashing
+```javascript
+// ❌ Forces multiple reflows
+elements.forEach(el => {
+  const height = el.offsetHeight; // Read
+  el.style.height = height + 10 + 'px'; // Write
+});
+
+// ✅ Batch reads, then batch writes
+const heights = elements.map(el => el.offsetHeight); // All reads
+elements.forEach((el, i) => {
+  el.style.height = heights[i] + 10 + 'px'; // All writes
+});
+```
+
+### Debounce expensive operations
+```javascript
+function debounce(fn, delay) {
+  let timeout;
+  return (...args) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => fn(...args), delay);
+  };
+}
+
+// Debounce scroll/resize handlers
+window.addEventListener('scroll', debounce(handleScroll, 100));
+```
+
+### Use requestAnimationFrame
+```javascript
+// ❌ May cause jank
+setInterval(animate, 16);
+
+// ✅ Synced with display refresh
+function animate() {
+  // Animation logic
+  requestAnimationFrame(animate);
+}
+requestAnimationFrame(animate);
+```
+
+### Virtualize long lists
+```javascript
+// For lists > 100 items, render only visible items
+// Use libraries like react-window, vue-virtual-scroller, or native CSS:
+.virtual-list {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 50px; /* Estimated item height */
+}
+```
+
+### Smooth navigations with View Transitions
+
+The [View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions) lets the browser cross-fade (or custom-animate) between two DOM states using a single GPU-composited snapshot — no double-render, no layout thrash, and the snapshot doesn't count toward CLS.
+
+**Same-document (SPA-style) — Baseline 2026:**
+```javascript
+// Wrap the DOM mutation that swaps the view
+function navigate(newView) {
+  if (!document.startViewTransition) return swapDOM(newView);
+  document.startViewTransition(() => swapDOM(newView));
+}
+```
+
+**Cross-document (MPA-style) — Chromium-stable, progressive enhancement elsewhere:**
+```css
+/* On both source and destination pages */
+@view-transition { navigation: auto; }
+```
+That's the entire integration — same-origin navigations now fade automatically. To opt specific elements into shared-element transitions (e.g. a thumbnail expanding into a hero), give them a matching `view-transition-name`:
+```css
+.product-thumb[data-id="42"], .product-hero { view-transition-name: product-42; }
+```
+
+Pair this with Speculation Rules (above) for instant + animated navigations.
+
+## Third-party scripts
+
+### Load strategies
+```javascript
+// ❌ Blocks main thread
+<script src="https://analytics.example.com/script.js"></script>
+
+// ✅ Async loading
+<script async src="https://analytics.example.com/script.js"></script>
+
+// ✅ Delay until interaction
+<script>
+document.addEventListener('DOMContentLoaded', () => {
+  const observer = new IntersectionObserver((entries) => {
+    if (entries[0].isIntersecting) {
+      const script = document.createElement('script');
+      script.src = 'https://widget.example.com/embed.js';
+      document.body.appendChild(script);
+      observer.disconnect();
+    }
+  });
+  observer.observe(document.querySelector('#widget-container'));
+});
+</script>
+```
+
+### Facade pattern
+```html
+<!-- Show static placeholder until interaction -->
+<div class="youtube-facade" 
+     data-video-id="abc123" 
+     onclick="loadYouTube(this)">
+  <img src="/thumbnails/abc123.jpg" alt="Video title">
+  <button aria-label="Play video">▶</button>
+</div>
+```
+
+## Measurement
+
+### Key metrics
+| Metric | Target | Tool |
+|--------|--------|------|
+| LCP | < 2.5s | Lighthouse, CrUX |
+| FCP | < 1.8s | Lighthouse |
+| Speed Index | < 3.4s | Lighthouse |
+| TBT | < 200ms | Lighthouse |
+| TTI | < 3.8s | Lighthouse |
+
+### Testing commands
+```bash
+# Lighthouse CLI
+npx lighthouse https://example.com --output html --output-path report.html
+
+# Web Vitals library
+import {onLCP, onINP, onCLS} from 'web-vitals';
+onLCP(console.log);
+onINP(console.log);
+onCLS(console.log);
+```
+
+## References
+
+For Core Web Vitals specific optimizations, see [Core Web Vitals](../core-web-vitals/SKILL.md).