docs: skills - upgrade skill instructions

2026-08-24 00:08:06 +00:00 · 2026-04-28 19:14:07 +08:00
parent f78d03236a
commit 7a902b3348
16 changed files with 1228 additions and 3070 deletions
@@ -1,274 +1,122 @@
 ---
 name: snapdom
-description: snapDOM is a fast, accurate DOM-to-image capture tool that converts HTML elements into scalable SVG images. Use for capturing HTML elements, converting DOM to images (SVG, PNG, JPG, WebP), preserving styles, fonts, and pseudo-elements.
+description: "snapDOM DOM-to-image skill: capture HTML elements as SVG/PNG/JPG/WebP/canvas/blob, preserve styles/fonts/pseudo-elements, use scaling/exclusion/CORS proxy options, and compare screenshot output."
 ---

-# SnapDOM Skill
+# snapdom Skill

-Fast, dependency-free DOM-to-image capture library for converting HTML elements into scalable SVG or raster image formats.
+Use this skill to capture browser DOM elements into image outputs with snapDOM while preserving styling and controlling export options.

 ## When to Use This Skill

-Use SnapDOM when you need to:
- Convert HTML elements to images (SVG, PNG, JPG, WebP)
- Capture styled DOM with pseudo-elements and shadows
- Export elements with embedded fonts and icons
- Create screenshots with custom dimensions or scaling
- Handle CORS-blocked resources using proxy fallback
- Implement custom rendering pipelines with plugins
- Optimize performance on large or complex elements
+Trigger when any of these applies:
+- Exporting a DOM element to SVG, PNG, JPG, WebP, Canvas, or Blob.
+- Capturing styled UI with fonts, pseudo-elements, shadows, transforms, or Shadow DOM.
+- Building screenshot/export/download features in web apps.
+- Debugging missing assets, CORS-blocked images, scaling, tight bounds, or excluded controls.
+- Comparing snapDOM with `html2canvas` or browser screenshot workflows.

-## Key Features
+## Not For / Boundaries

-### Universal Export Options
- **SVG** - Scalable vector format, embeds all styles
- **PNG, JPG, WebP** - Raster formats with configurable quality
- **Canvas** - Get raw Canvas element for further processing
- **Blob** - Raw binary data for custom handling
+- Not for full-page browser automation screenshots; use Playwright/Puppeteer when viewport, navigation, or browser state is the core need.
+- CORS-blocked resources may require a proxy or same-origin setup; do not assume cross-origin images will embed automatically.
+- Do not capture sensitive DOM content unless the user explicitly intends to export it.
+- Required inputs: target element selector, desired format, dimensions/scale, asset/CORS constraints, and where the image should be used.
+- Verify package/API names against the installed version if build errors indicate version drift.

-### Performance
- Ultra-fast capture (1.6ms for small elements, ~171ms for 4000×2000)
- **No dependencies** - Uses standard Web APIs only
- Outperforms html2canvas by 10-40x on complex elements
+## Quick Reference

-### Style Support
- Embedded fonts (including icon fonts)
- CSS pseudo-elements (::before, ::after)
- CSS counters
- CSS line-clamp
- Transform and shadow effects
- Shadow DOM content
+### Common Patterns

-### Advanced Capabilities
- Same-origin iframe support
- CORS proxy fallback for blocked assets
- Plugin system for custom transformations
- Straighten transforms (remove rotate/translate)
- Selective element exclusion
- Tight bounding box calculation
-
-## Installation
-
-### NPM/Yarn
+**Install**
 ```bash
 npm install @zumer/snapdom
-# or
-yarn add @zumer/snapdom
 ```

-### CDN (ES Module)
+**Import from CDN as an ES module**
 ```html
 <script type="module">
  import { snapdom } from "https://unpkg.com/@zumer/snapdom/dist/snapdom.mjs";
 </script>
 ```

-### CDN (UMD)
-```html
-<script src="https://unpkg.com/@zumer/snapdom/dist/snapdom.umd.js"></script>
-```
-
-## Quick Start Examples
-
-### Basic Reusable Capture
+**Capture once and export multiple formats**
 ```javascript
-// Create reusable capture object
-const result = await snapdom(document.querySelector('#target'));
-
-// Export to different formats
+const result = await snapdom(document.querySelector("#target"));
 const png = await result.toPng();
-const jpg = await result.toJpg();
 const svg = await result.toSvg();
 const canvas = await result.toCanvas();
-const blob = await result.toBlob();
-
-// Use the result
-document.body.appendChild(png);
 ```

-### One-Step Export
+**One-step PNG export**
 ```javascript
-// Direct export without intermediate object
-const png = await snapdom.toPng(document.querySelector('#target'));
-const svg = await snapdom.toSvg(element);
+const png = await snapdom.toPng(document.querySelector("#target"));
 ```

-### Download Element
+**Download an element**
 ```javascript
-// Automatically download as file
-await snapdom.download(element, 'screenshot.png');
-await snapdom.download(element, 'image.svg');
+await snapdom.download(document.querySelector("#target"), "screenshot.png");
 ```

-### With Options
+**Set scale and dimensions**
 ```javascript
-const result = await snapdom(element, {
-  scale: 2,                    // 2x resolution
-  width: 800,                  // Custom width
-  height: 600,                 // Custom height
-  embedFonts: true,            // Include @font-face
-  exclude: '.no-capture',      // Hide elements
-  useProxy: true,              // Enable CORS proxy
-  straighten: true,            // Remove transforms
-  noShadows: false             // Keep shadows
-});
-
-const png = await result.toPng({ quality: 0.95 });
-```
-
-## Essential Options Reference
-
-| Option | Type | Purpose |
-|--------|------|---------|
-| `scale` | Number | Scale output (e.g., 2 for 2x resolution) |
-| `width` | Number | Custom output width in pixels |
-| `height` | Number | Custom output height in pixels |
-| `embedFonts` | Boolean | Include non-icon @font-face rules |
-| `useProxy` | String\|Boolean | Enable CORS proxy (URL or true for default) |
-| `exclude` | String | CSS selector for elements to hide |
-| `straighten` | Boolean | Remove translate/rotate transforms |
-| `noShadows` | Boolean | Strip shadow effects |
-
-## Common Patterns
-
-### Responsive Screenshots
-```javascript
-// Capture at different scales
-const mobile = await snapdom.toPng(element, { scale: 1 });
-const tablet = await snapdom.toPng(element, { scale: 1.5 });
-const desktop = await snapdom.toPng(element, { scale: 2 });
-```
-
-### Exclude Elements
-```javascript
-// Hide specific elements from capture
 const png = await snapdom.toPng(element, {
-  exclude: '.controls, .watermark, [data-no-capture]'
-});
-```
-
-### Fixed Dimensions
-```javascript
-// Capture with specific size
-const result = await snapdom(element, {
+  scale: 2,
  width: 1200,
-  height: 630  // Standard social media size
+  height: 630,
 });
 ```

-### CORS Handling
+**Exclude UI controls**
 ```javascript
-// Fallback for CORS-blocked resources
 const png = await snapdom.toPng(element, {
-  useProxy: 'https://cors.example.com/?' // Custom proxy
+  exclude: ".controls, [data-no-capture]",
 });
 ```

-### Plugin System (Beta)
+**Use a CORS proxy fallback**
 ```javascript
-// Extend with custom exporters
-snapdom.plugins([pluginFactory, { colorOverlay: true }]);
-
-// Hook into lifecycle
-defineExports(context) {
-  return {
-    pdf: async (ctx, opts) => { /* generate PDF */ }
-  };
-}
-
-// Lifecycle hooks available:
-// beforeSnap → beforeClone → afterClone →
-// beforeRender → beforeExport → afterExport
+const png = await snapdom.toPng(element, {
+  useProxy: "https://cors.example.com/?",
+});
 ```

-## Performance Comparison
+## Examples

-SnapDOM significantly outperforms html2canvas:
+### Example 1: Social Card Export

-| Scenario | SnapDOM | html2canvas | Improvement |
-|----------|---------|-------------|-------------|
-| Small (200×100) | 1.6ms | 68ms | 42x faster |
-| Medium (800×600) | 12ms | 280ms | 23x faster |
-| Large (4000×2000) | 171ms | 1,800ms | 10x faster |
+- Input: element `#card`, target size `1200x630`, PNG output.
+- Steps:
+  1. Ensure fonts and images are loaded.
+  2. Capture with explicit `width`, `height`, and `scale`.
+  3. Download or upload the resulting PNG.
+- Expected output / acceptance: exported image matches the card bounds and excludes editor controls.

-## Development
+### Example 2: SVG Snapshot for Documentation

-### Setup
-```bash
-git clone https://github.com/zumerlab/snapdom.git
-cd snapdom
-npm install
-```
+- Input: styled component preview.
+- Steps:
+  1. Call `snapdom(element)`.
+  2. Export `toSvg()` for scalable documentation output.
+  3. Inspect missing fonts/assets if the snapshot differs from the page.
+- Expected output / acceptance: SVG preserves visible styles and remains inspectable as a vector artifact.

-### Build
-```bash
-npm run compile
-```
+### Example 3: CORS Asset Triage

-### Testing
-```bash
-npm test
-```
+- Input: export shows missing remote images.
+- Steps:
+  1. Confirm whether assets are same-origin and CORS-enabled.
+  2. Retry with `useProxy` or replace remote assets with local/same-origin URLs.
+  3. Validate final output in the target browser.
+- Expected output / acceptance: missing images are attributed to CORS, loading, or selector/sizing issues.

-## Browser Support
+## References

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Mobile browsers (iOS Safari 14+, Chrome Mobile)
+- `references/index.md`: local snapDOM reference navigation.
+- `references/other.md`: generated upstream notes and API details.

-## Resources
+## Maintenance

-### Documentation
- **Official Website:** https://snapdom.dev/
- **GitHub Repository:** https://github.com/zumerlab/snapdom
- **NPM Package:** https://www.npmjs.com/package/@zumer/snapdom
- **License:** MIT
-
-### scripts/
-Add helper scripts here for automation, e.g.:
- `batch-screenshot.js` - Capture multiple elements
- `pdf-export.js` - Convert snapshots to PDF
- `compare-outputs.js` - Compare SVG vs PNG quality
-
-### assets/
-Add templates and examples:
- HTML templates for common capture scenarios
- CSS frameworks pre-configured with snapdom
- Boilerplate projects integrating snapdom
-
-## Related Tools
-
- **html2canvas** - Alternative DOM capture (slower but more compatible)
- **Orbit CSS Toolkit** - Companion toolkit by Zumerlab (https://github.com/zumerlab/orbit)
-
-## Tips & Best Practices
-
-1. **Performance**: Use `scale` instead of `width`/`height` for better performance
-2. **Fonts**: Set `embedFonts: true` to ensure custom fonts appear correctly
-3. **CORS Issues**: Use `useProxy: true` if images fail to load
-4. **Large Elements**: Break into smaller chunks for complex pages
-5. **Quality**: For PNG/JPG, use `quality: 0.95` for best quality
-6. **SVG Vectors**: Prefer SVG export for charts and graphics
-
-## Troubleshooting
-
-### Elements Not Rendering
- Check if element has sufficient height/width
- Verify CSS is fully loaded before capture
- Try `straighten: false` if transforms are causing issues
-
-### Missing Fonts
- Set `embedFonts: true`
- Ensure fonts are loaded before calling snapdom
- Check browser console for font loading errors
-
-### CORS Issues
- Enable `useProxy: true`
- Use custom proxy URL if default fails
- Check if resources are from same origin
-
-### Performance Issues
- Reduce `scale` value
- Use `noShadows: true` to skip shadow rendering
- Consider splitting large captures into smaller sections
+- Sources: local `references/` extracted from snapDOM documentation.
+- Last updated: 2026-04-28
+- Known limits: screenshot fidelity depends on browser support, loaded assets, CORS, fonts, and installed snapDOM version.