@hypertools/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 HyperTool Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,443 @@
+# @hypertool/sdk
+
+Vanilla-first SDK for embedding interactive creative coding experiences. Works with p5.js, Three.js, WebGL, Canvas, and any other rendering library.
+
+[![npm version](https://img.shields.io/npm/v/@hypertool/sdk.svg)](https://www.npmjs.com/package/@hypertool/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@hypertool/sdk.svg)](https://www.npmjs.com/package/@hypertool/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Framework-agnostic** - Works with p5.js, Three.js, vanilla Canvas, WebGL, or any rendering library
+- **Reactive parameters** - Define control parameters that automatically trigger updates
+- **Video & image capture** - Built-in recording with MediaRecorder and canvas capture
+- **Timeline animations** - Keyframe-based animation system with easing functions
+- **React integration** - Optional React hooks and components
+- **TypeScript first** - Full type definitions included
+- **Zero dependencies** - Core SDK has no runtime dependencies
+
+## Installation
+
+```bash
+# npm
+npm install @hypertool/sdk
+
+# yarn
+yarn add @hypertool/sdk
+
+# pnpm
+pnpm add @hypertool/sdk
+
+# bun
+bun add @hypertool/sdk
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { Experience } from '@hypertool/sdk';
+
+const experience = new Experience({
+  mount: document.getElementById('canvas-container'),
+  paramDefs: {
+    color: { type: 'color', value: '#ff0000', label: 'Color' },
+    speed: { type: 'number', value: 5, min: 1, max: 10, label: 'Speed' },
+    showGrid: { type: 'boolean', value: true, label: 'Show Grid' },
+  },
+  setup(context) {
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    canvas.width = 800;
+    canvas.height = 600;
+    context.mount.appendChild(canvas);
+
+    // Access reactive parameters
+    console.log(context.params.color);   // '#ff0000'
+    console.log(context.params.speed);   // 5
+    console.log(context.params.showGrid); // true
+
+    // Draw loop
+    function draw() {
+      ctx.fillStyle = context.params.color;
+      ctx.fillRect(0, 0, canvas.width, canvas.height);
+    }
+
+    // Listen to frame events
+    context.experience.on('frame', draw);
+
+    // Return cleanup function
+    return () => {
+      canvas.remove();
+    };
+  },
+});
+
+// Control playback
+experience.play();
+experience.pause();
+
+// Update parameters programmatically
+experience.setParam('color', '#00ff00');
+experience.setParams({ speed: 8, showGrid: false });
+
+// Capture images
+const blob = await experience.captureImage('png');
+
+// Clean up when done
+experience.destroy();
+```
+
+### With p5.js
+
+```typescript
+import { Experience } from '@hypertool/sdk';
+import p5 from 'p5';
+
+new Experience({
+  mount: document.getElementById('sketch'),
+  paramDefs: {
+    backgroundColor: { type: 'color', value: '#1a1a2e' },
+    circleCount: { type: 'number', value: 10, min: 1, max: 50 },
+    animate: { type: 'boolean', value: true },
+  },
+  setup(context) {
+    let sketch;
+
+    new p5((p) => {
+      sketch = p;
+
+      p.setup = () => {
+        p.createCanvas(800, 600);
+      };
+
+      p.draw = () => {
+        if (!context.params.animate) return;
+
+        p.background(context.params.backgroundColor);
+
+        for (let i = 0; i < context.params.circleCount; i++) {
+          p.circle(
+            p.random(p.width),
+            p.random(p.height),
+            p.random(20, 50)
+          );
+        }
+      };
+    }, context.mount);
+
+    return () => sketch?.remove();
+  },
+});
+```
+
+### With Three.js
+
+```typescript
+import { Experience } from '@hypertool/sdk';
+import * as THREE from 'three';
+
+new Experience({
+  mount: document.getElementById('scene'),
+  paramDefs: {
+    rotationSpeed: { type: 'number', value: 0.01, min: 0, max: 0.1, step: 0.001 },
+    cubeColor: { type: 'color', value: '#00ff88' },
+    wireframe: { type: 'boolean', value: false },
+  },
+  setup(context) {
+    const scene = new THREE.Scene();
+    const camera = new THREE.PerspectiveCamera(75, 800 / 600, 0.1, 1000);
+    const renderer = new THREE.WebGLRenderer();
+
+    renderer.setSize(800, 600);
+    context.mount.appendChild(renderer.domElement);
+
+    const geometry = new THREE.BoxGeometry();
+    const material = new THREE.MeshBasicMaterial({
+      color: context.params.cubeColor,
+      wireframe: context.params.wireframe,
+    });
+    const cube = new THREE.Mesh(geometry, material);
+    scene.add(cube);
+
+    camera.position.z = 5;
+
+    // Register object for external access
+    context.registerObject('mainCube', cube);
+
+    // Animation loop
+    context.experience.on('frame', () => {
+      cube.rotation.x += context.params.rotationSpeed;
+      cube.rotation.y += context.params.rotationSpeed;
+      material.color.set(context.params.cubeColor);
+      material.wireframe = context.params.wireframe;
+      renderer.render(scene, camera);
+    });
+
+    return () => {
+      renderer.dispose();
+      geometry.dispose();
+      material.dispose();
+    };
+  },
+});
+```
+
+## Entry Points
+
+The SDK is modular - import only what you need:
+
+| Entry | Purpose |
+|-------|---------|
+| `@hypertool/sdk` | Core Experience class + utilities |
+| `@hypertool/sdk/controls` | Tweakpane-based control panel (requires `tweakpane` peer dep) |
+| `@hypertool/sdk/recording` | Video/image capture & timeline |
+| `@hypertool/sdk/react` | React hooks & components (requires `react` peer dep) |
+| `@hypertool/sdk/capture` | Low-level capture utilities |
+
+## API Reference
+
+### Experience
+
+The main class for creating interactive experiences.
+
+```typescript
+interface ExperienceConfig {
+  mount: HTMLElement;              // Container element
+  paramDefs?: ParamDefinitions;    // Parameter schema
+  initialParams?: Record<string, unknown>;  // Override defaults
+  setup: SetupFunction;            // Your code
+  autoplay?: boolean;              // Start immediately (default: true)
+  frameRate?: number;              // Target FPS (default: 60)
+  background?: string;             // CSS background
+}
+```
+
+#### Methods
+
+```typescript
+// Playback
+experience.play();
+experience.pause();
+experience.toggle();
+
+// Parameters
+experience.setParam('key', value);
+experience.setParams({ key1: value1, key2: value2 });
+experience.getParams();  // Get all current values
+experience.resetParams(); // Reset to defaults
+
+// Object registry (Spline-like API)
+experience.registerObject('name', object, metadata);
+experience.findObjectByName('name');
+experience.findObjectById('id');
+experience.getAllObjects();
+
+// Events
+experience.on('ready', () => {});
+experience.on('frame', ({ frame, deltaTime }) => {});
+experience.on('paramChange', ({ key, value, previousValue }) => {});
+experience.on('resize', ({ width, height }) => {});
+experience.on('error', ({ error }) => {});
+experience.once('ready', () => {});
+experience.off('ready', handler);
+
+// Capture
+const blob = await experience.captureImage('png');
+
+// Cleanup
+experience.destroy();
+```
+
+#### Properties
+
+```typescript
+experience.isReady;      // boolean
+experience.isPlaying;    // boolean
+experience.isDestroyed;  // boolean
+experience.currentFrame; // number
+experience.params;       // Reactive proxy
+experience.mount;        // HTMLElement
+```
+
+### Parameter Types
+
+```typescript
+// Number
+{ type: 'number', value: 5, min: 0, max: 10, step: 0.1, label: 'Speed' }
+
+// Color
+{ type: 'color', value: '#ff0000', label: 'Background' }
+
+// Boolean
+{ type: 'boolean', value: true, label: 'Show Grid' }
+
+// String
+{ type: 'string', value: 'hello', label: 'Text' }
+
+// Select
+{ type: 'select', value: 'option1', options: [
+  { label: 'Option 1', value: 'option1' },
+  { label: 'Option 2', value: 'option2' },
+], label: 'Mode' }
+```
+
+### Recording Module
+
+```typescript
+import { VideoRecorder, ImageCapture, Timeline } from '@hypertool/sdk/recording';
+
+// Video recording
+const recorder = VideoRecorder.start(canvas, {
+  format: 'webm',      // 'webm' | 'mp4'
+  quality: 0.9,        // 0-1
+  frameRate: 60,       // FPS
+});
+
+// Later...
+const videoBlob = await recorder.stop();
+
+// Image capture
+const imageBlob = await ImageCapture.capture(canvas, 'png');
+
+// Timeline animation
+const timeline = new Timeline({
+  loop: true,
+  duration: 5000,  // 5 seconds
+});
+
+timeline
+  .addKeyframe(0, { opacity: 0, scale: 0.5 })
+  .addKeyframe(1000, { opacity: 1, scale: 1 }, 'easeOutBack')
+  .addKeyframe(4000, { opacity: 1, scale: 1 })
+  .addKeyframe(5000, { opacity: 0, scale: 0.5 }, 'easeInQuad');
+
+timeline.onUpdate((params) => {
+  experience.setParams(params);
+});
+
+timeline.play();
+timeline.pause();
+timeline.seek(2500);  // Jump to 2.5s
+```
+
+### React Integration
+
+```tsx
+import { useExperience, ExperienceView } from '@hypertool/sdk/react';
+
+function MyVisualization() {
+  const {
+    experience,
+    isReady,
+    isPlaying,
+    params,
+    setParam,
+    play,
+    pause,
+    toggle,
+  } = useExperience({
+    paramDefs: {
+      color: { type: 'color', value: '#ff0000' },
+      speed: { type: 'number', value: 5, min: 1, max: 10 },
+    },
+    setup(context) {
+      // Your setup code
+    },
+  });
+
+  return (
+    <div>
+      <ExperienceView
+        experience={experience}
+        className="w-full h-96"
+      />
+
+      <div className="controls">
+        <button onClick={toggle}>
+          {isPlaying ? 'Pause' : 'Play'}
+        </button>
+
+        <input
+          type="color"
+          value={params.color}
+          onChange={(e) => setParam('color', e.target.value)}
+        />
+
+        <input
+          type="range"
+          min={1}
+          max={10}
+          value={params.speed}
+          onChange={(e) => setParam('speed', Number(e.target.value))}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Controls Module (Tweakpane)
+
+Add a visual control panel with Tweakpane:
+
+```typescript
+import { HypertoolControls } from '@hypertool/sdk/controls';
+
+const controls = new HypertoolControls({
+  container: document.getElementById('controls'),
+  definitions: {
+    color: { type: 'color', value: '#ff0000' },
+    speed: { type: 'number', value: 5, min: 1, max: 10 },
+  },
+  onChange: (key, value) => {
+    console.log(`${key} changed to ${value}`);
+  },
+});
+
+// Programmatic updates
+controls.set('color', '#00ff00');
+controls.refresh();
+controls.dispose();
+```
+
+## Examples
+
+See the `/examples` directory for complete working examples:
+
+- `examples/vanilla-canvas/` - Pure Canvas API
+- `examples/p5js/` - p5.js sketch
+- `examples/threejs/` - Three.js scene
+- `examples/react/` - React integration
+- `examples/recording/` - Video capture & timeline
+
+## Browser Support
+
+- Chrome 80+
+- Firefox 78+
+- Safari 14+
+- Edge 80+
+
+## TypeScript
+
+Full TypeScript support with type definitions included.
+
+```typescript
+import type {
+  Experience,
+  ExperienceConfig,
+  ExperienceContext,
+  ParamDefinitions,
+  ParamValues,
+  ExperienceEvent,
+} from '@hypertool/sdk';
+```
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

package/dist/capture/CaptureManager.d.ts

@@ -0,0 +1,55 @@
+/**
+ * CaptureManager - Rendering-target agnostic capture system
+ *
+ * Supports capturing from ANY rendering target:
+ * - Canvas (2D, WebGL, WebGPU)
+ * - SVG elements
+ * - HTML elements (via html2canvas-like approach)
+ * - Custom targets via handlers
+ */
+import type { CaptureFormat, CaptureResult, CaptureHandler, CaptureConfig } from './types';
+export declare class CaptureManager {
+    private config;
+    private customHandler;
+    constructor(config?: CaptureConfig);
+    /**
+     * Register a custom capture handler
+     * Use this to support any rendering target
+     */
+    registerHandler(handler: CaptureHandler): void;
+    /**
+     * Capture image from the render target
+     */
+    capture(container: HTMLElement, format?: CaptureFormat): Promise<CaptureResult | null>;
+    /**
+     * Find the render target in a container
+     * Priority: custom selector > canvas > svg > container itself
+     */
+    private findRenderTarget;
+    /**
+     * Detect the type of an element
+     */
+    private detectType;
+    /**
+     * Capture from canvas element
+     */
+    private captureCanvas;
+    /**
+     * Capture from SVG element
+     */
+    private captureSvg;
+    /**
+     * Convert SVG to raster image via canvas
+     */
+    private svgToRaster;
+    /**
+     * Capture from HTML element
+     * Uses a simple approach - for complex HTML, consider html2canvas
+     */
+    private captureHtml;
+    /**
+     * Get MIME type for format
+     */
+    private getMimeType;
+}
+//# sourceMappingURL=CaptureManager.d.ts.map

package/dist/capture/CaptureManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CaptureManager.d.ts","sourceRoot":"","sources":["../../src/capture/CaptureManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EAEd,MAAM,SAAS,CAAC;AAEjB,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAA+B;gBAExC,MAAM,GAAE,aAAkB;IAYtC;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAI9C;;OAEG;IACG,OAAO,CACX,SAAS,EAAE,WAAW,EACtB,MAAM,GAAE,aAAkD,GACzD,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA4BhC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA8BxB;;OAEG;IACH,OAAO,CAAC,UAAU;IAMlB;;OAEG;YACW,aAAa;IA2B3B;;OAEG;YACW,UAAU;IAsBxB;;OAEG;YACW,WAAW;IAwCzB;;;OAGG;YACW,WAAW;IAwDzB;;OAEG;IACH,OAAO,CAAC,WAAW;CAcpB"}

package/dist/capture/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Capture module - rendering-target agnostic capture system
+ *
+ * This module provides a flexible capture system that works with ANY rendering target:
+ * - Canvas (2D, WebGL, WebGPU)
+ * - SVG elements
+ * - HTML elements
+ * - Custom targets via handlers
+ *
+ * Usage:
+ * ```ts
+ * import { CaptureManager } from '@hypertool/sdk/capture';
+ *
+ * // Auto-detect render target
+ * const capture = new CaptureManager();
+ * const result = await capture.capture(container, 'png');
+ *
+ * // Custom handler for complex scenarios
+ * capture.registerHandler(async (format) => {
+ *   // Your custom capture logic
+ *   return { blob, width, height, format };
+ * });
+ * ```
+ */
+export { CaptureManager } from './CaptureManager';
+export type { CaptureFormat, VideoFormat, CaptureResult, VideoCaptureResult, CaptureHandler, VideoCaptureHandler, RenderTargetType, CaptureConfig, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/capture/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capture/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,aAAa,EACb,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,GACd,MAAM,SAAS,CAAC"}

package/dist/capture/index.js

@@ -0,0 +1,11 @@
+class G{config;customHandler=null;constructor(p={}){if(this.config={defaultFormat:"png",quality:0.92,...p},p.customHandler)this.customHandler=p.customHandler}registerHandler(p){this.customHandler=p}async capture(p,u=this.config.defaultFormat||"png"){if(this.customHandler)return this.customHandler(u);let H=this.findRenderTarget(p);if(!H)return console.warn("[CaptureManager] No render target found in container"),null;let{element:C,type:V}=H;switch(V){case"canvas":return this.captureCanvas(C,u);case"svg":return this.captureSvg(C,u);case"html":return this.captureHtml(C,u);default:return console.warn("[CaptureManager] Unknown render target type:",V),null}}findRenderTarget(p){if(this.config.targetSelector){let C=p.querySelector(this.config.targetSelector);if(C)return{element:C,type:this.config.targetType||this.detectType(C)}}let u=p.querySelector("canvas");if(u)return{element:u,type:"canvas"};let H=p.querySelector("svg");if(H)return{element:H,type:"svg"};return{element:p,type:"html"}}detectType(p){if(p instanceof HTMLCanvasElement)return"canvas";if(p instanceof SVGSVGElement)return"svg";return"html"}async captureCanvas(p,u){let H=this.getMimeType(u),C=u==="jpeg"?this.config.quality:void 0;return new Promise((V)=>{p.toBlob((d)=>{if(!d){V(null);return}V({blob:d,width:p.width,height:p.height,format:u})},H,C)})}async captureSvg(p,u){if(u==="svg"){let C=new XMLSerializer().serializeToString(p),V=new Blob([C],{type:"image/svg+xml"}),d=p.getBBox();return{blob:V,width:d.width||p.clientWidth,height:d.height||p.clientHeight,format:"svg"}}return this.svgToRaster(p,u)}async svgToRaster(p,u){let C=new XMLSerializer().serializeToString(p),V=new Blob([C],{type:"image/svg+xml;charset=utf-8"}),d=URL.createObjectURL(V),R=new Image;return R.src=d,new Promise((A)=>{R.onload=()=>{URL.revokeObjectURL(d);let k=document.createElement("canvas"),y=p.clientWidth||R.width,T=p.clientHeight||R.height;k.width=y,k.height=T;let F=k.getContext("2d");if(!F){A(null);return}F.drawImage(R,0,0,y,T),this.captureCanvas(k,u).then(A)},R.onerror=()=>{URL.revokeObjectURL(d),A(null)}})}async captureHtml(p,u){let H=p,C=H.offsetWidth,V=H.offsetHeight,d=document.createElement("canvas");d.width=C,d.height=V;let R=d.getContext("2d");if(!R)return null;let A=`
+      <svg xmlns="http://www.w3.org/2000/svg" width="${C}" height="${V}">
+        <foreignObject width="100%" height="100%">
+          <div xmlns="http://www.w3.org/1999/xhtml">
+            ${H.outerHTML}
+          </div>
+        </foreignObject>
+      </svg>
+    `,k=new Blob([A],{type:"image/svg+xml;charset=utf-8"}),y=URL.createObjectURL(k),T=new Image;return T.src=y,new Promise((F)=>{T.onload=()=>{URL.revokeObjectURL(y),R.drawImage(T,0,0),this.captureCanvas(d,u).then(F)},T.onerror=()=>{URL.revokeObjectURL(y),console.warn("[CaptureManager] HTML capture failed. Consider using a custom capture handler."),F(null)}})}getMimeType(p){switch(p){case"png":return"image/png";case"jpeg":return"image/jpeg";case"webp":return"image/webp";case"svg":return"image/svg+xml";default:return"image/png"}}}export{G as CaptureManager};
+
+//# debugId=5A7F3124CCD112A664756E2164756E21

package/dist/capture/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../src/capture/CaptureManager.ts"],
+  "sourcesContent": [
+    "/**\n * CaptureManager - Rendering-target agnostic capture system\n *\n * Supports capturing from ANY rendering target:\n * - Canvas (2D, WebGL, WebGPU)\n * - SVG elements\n * - HTML elements (via html2canvas-like approach)\n * - Custom targets via handlers\n */\n\nimport type {\n  CaptureFormat,\n  CaptureResult,\n  CaptureHandler,\n  CaptureConfig,\n  RenderTargetType,\n} from './types';\n\nexport class CaptureManager {\n  private config: CaptureConfig;\n  private customHandler: CaptureHandler | null = null;\n\n  constructor(config: CaptureConfig = {}) {\n    this.config = {\n      defaultFormat: 'png',\n      quality: 0.92,\n      ...config,\n    };\n\n    if (config.customHandler) {\n      this.customHandler = config.customHandler;\n    }\n  }\n\n  /**\n   * Register a custom capture handler\n   * Use this to support any rendering target\n   */\n  registerHandler(handler: CaptureHandler): void {\n    this.customHandler = handler;\n  }\n\n  /**\n   * Capture image from the render target\n   */\n  async capture(\n    container: HTMLElement,\n    format: CaptureFormat = this.config.defaultFormat || 'png'\n  ): Promise<CaptureResult | null> {\n    // Use custom handler if registered\n    if (this.customHandler) {\n      return this.customHandler(format);\n    }\n\n    // Auto-detect render target\n    const target = this.findRenderTarget(container);\n    if (!target) {\n      console.warn('[CaptureManager] No render target found in container');\n      return null;\n    }\n\n    const { element, type } = target;\n\n    switch (type) {\n      case 'canvas':\n        return this.captureCanvas(element as HTMLCanvasElement, format);\n      case 'svg':\n        return this.captureSvg(element as SVGSVGElement, format);\n      case 'html':\n        return this.captureHtml(element, format);\n      default:\n        console.warn('[CaptureManager] Unknown render target type:', type);\n        return null;\n    }\n  }\n\n  /**\n   * Find the render target in a container\n   * Priority: custom selector > canvas > svg > container itself\n   */\n  private findRenderTarget(\n    container: HTMLElement\n  ): { element: Element; type: RenderTargetType } | null {\n    // Use custom selector if specified\n    if (this.config.targetSelector) {\n      const element = container.querySelector(this.config.targetSelector);\n      if (element) {\n        return {\n          element,\n          type: this.config.targetType || this.detectType(element),\n        };\n      }\n    }\n\n    // Auto-detect: canvas first\n    const canvas = container.querySelector('canvas');\n    if (canvas) {\n      return { element: canvas, type: 'canvas' };\n    }\n\n    // Then SVG\n    const svg = container.querySelector('svg');\n    if (svg) {\n      return { element: svg, type: 'svg' };\n    }\n\n    // Fall back to the container itself (HTML capture)\n    return { element: container, type: 'html' };\n  }\n\n  /**\n   * Detect the type of an element\n   */\n  private detectType(element: Element): RenderTargetType {\n    if (element instanceof HTMLCanvasElement) return 'canvas';\n    if (element instanceof SVGSVGElement) return 'svg';\n    return 'html';\n  }\n\n  /**\n   * Capture from canvas element\n   */\n  private async captureCanvas(\n    canvas: HTMLCanvasElement,\n    format: CaptureFormat\n  ): Promise<CaptureResult | null> {\n    const mimeType = this.getMimeType(format);\n    const quality = format === 'jpeg' ? this.config.quality : undefined;\n\n    return new Promise((resolve) => {\n      canvas.toBlob(\n        (blob) => {\n          if (!blob) {\n            resolve(null);\n            return;\n          }\n          resolve({\n            blob,\n            width: canvas.width,\n            height: canvas.height,\n            format,\n          });\n        },\n        mimeType,\n        quality\n      );\n    });\n  }\n\n  /**\n   * Capture from SVG element\n   */\n  private async captureSvg(\n    svg: SVGSVGElement,\n    format: CaptureFormat\n  ): Promise<CaptureResult | null> {\n    // For SVG format, return the SVG directly\n    if (format === 'svg') {\n      const serializer = new XMLSerializer();\n      const svgString = serializer.serializeToString(svg);\n      const blob = new Blob([svgString], { type: 'image/svg+xml' });\n      const bbox = svg.getBBox();\n      return {\n        blob,\n        width: bbox.width || svg.clientWidth,\n        height: bbox.height || svg.clientHeight,\n        format: 'svg',\n      };\n    }\n\n    // For raster formats, render SVG to canvas first\n    return this.svgToRaster(svg, format);\n  }\n\n  /**\n   * Convert SVG to raster image via canvas\n   */\n  private async svgToRaster(\n    svg: SVGSVGElement,\n    format: CaptureFormat\n  ): Promise<CaptureResult | null> {\n    const serializer = new XMLSerializer();\n    const svgString = serializer.serializeToString(svg);\n    const svgBlob = new Blob([svgString], { type: 'image/svg+xml;charset=utf-8' });\n    const url = URL.createObjectURL(svgBlob);\n\n    const img = new Image();\n    img.src = url;\n\n    return new Promise((resolve) => {\n      img.onload = () => {\n        URL.revokeObjectURL(url);\n\n        const canvas = document.createElement('canvas');\n        const width = svg.clientWidth || img.width;\n        const height = svg.clientHeight || img.height;\n        canvas.width = width;\n        canvas.height = height;\n\n        const ctx = canvas.getContext('2d');\n        if (!ctx) {\n          resolve(null);\n          return;\n        }\n\n        ctx.drawImage(img, 0, 0, width, height);\n\n        this.captureCanvas(canvas, format).then(resolve);\n      };\n\n      img.onerror = () => {\n        URL.revokeObjectURL(url);\n        resolve(null);\n      };\n    });\n  }\n\n  /**\n   * Capture from HTML element\n   * Uses a simple approach - for complex HTML, consider html2canvas\n   */\n  private async captureHtml(\n    element: Element,\n    format: CaptureFormat\n  ): Promise<CaptureResult | null> {\n    // Simple approach: use browser's native rendering\n    // For production, you might want to use html2canvas or similar\n\n    const htmlElement = element as HTMLElement;\n    const width = htmlElement.offsetWidth;\n    const height = htmlElement.offsetHeight;\n\n    // Create a canvas and draw the element\n    const canvas = document.createElement('canvas');\n    canvas.width = width;\n    canvas.height = height;\n\n    const ctx = canvas.getContext('2d');\n    if (!ctx) {\n      return null;\n    }\n\n    // Use foreignObject approach\n    const svgString = `\n      <svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${width}\" height=\"${height}\">\n        <foreignObject width=\"100%\" height=\"100%\">\n          <div xmlns=\"http://www.w3.org/1999/xhtml\">\n            ${htmlElement.outerHTML}\n          </div>\n        </foreignObject>\n      </svg>\n    `;\n\n    const svgBlob = new Blob([svgString], { type: 'image/svg+xml;charset=utf-8' });\n    const url = URL.createObjectURL(svgBlob);\n\n    const img = new Image();\n    img.src = url;\n\n    return new Promise((resolve) => {\n      img.onload = () => {\n        URL.revokeObjectURL(url);\n        ctx.drawImage(img, 0, 0);\n        this.captureCanvas(canvas, format).then(resolve);\n      };\n\n      img.onerror = () => {\n        URL.revokeObjectURL(url);\n        // Fallback: return null, user should use custom handler for complex HTML\n        console.warn(\n          '[CaptureManager] HTML capture failed. Consider using a custom capture handler.'\n        );\n        resolve(null);\n      };\n    });\n  }\n\n  /**\n   * Get MIME type for format\n   */\n  private getMimeType(format: CaptureFormat): string {\n    switch (format) {\n      case 'png':\n        return 'image/png';\n      case 'jpeg':\n        return 'image/jpeg';\n      case 'webp':\n        return 'image/webp';\n      case 'svg':\n        return 'image/svg+xml';\n      default:\n        return 'image/png';\n    }\n  }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "5A7F3124CCD112A664756E2164756E21",
+  "names": []
+}

package/dist/capture/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Capture types - rendering-target agnostic capture system
+ *
+ * The capture system supports ANY rendering target:
+ * - Canvas (2D, WebGL, WebGPU)
+ * - SVG
+ * - HTML elements
+ * - Custom render targets
+ */
+/**
+ * Supported capture formats
+ */
+export type CaptureFormat = 'png' | 'jpeg' | 'webp' | 'svg';
+/**
+ * Supported video formats
+ */
+export type VideoFormat = 'webm' | 'mp4';
+/**
+ * Capture result from any render target
+ */
+export interface CaptureResult {
+    /** The captured image as Blob */
+    blob: Blob;
+    /** Image width */
+    width: number;
+    /** Image height */
+    height: number;
+    /** Format used */
+    format: CaptureFormat;
+}
+/**
+ * Video capture result
+ */
+export interface VideoCaptureResult {
+    /** The captured video as Blob */
+    blob: Blob;
+    /** Video duration in seconds */
+    duration: number;
+    /** Format used */
+    format: VideoFormat;
+}
+/**
+ * Custom capture handler function
+ * Implement this to support any rendering target (canvas, SVG, HTML, etc.)
+ */
+export type CaptureHandler = (format: CaptureFormat) => Promise<CaptureResult | null>;
+/**
+ * Custom video capture handler function
+ */
+export type VideoCaptureHandler = () => {
+    start: () => void;
+    stop: () => Promise<VideoCaptureResult>;
+    cancel: () => void;
+};
+/**
+ * Render target types supported out of the box
+ */
+export type RenderTargetType = 'canvas' | 'svg' | 'html' | 'custom';
+/**
+ * Configuration for automatic capture target detection
+ */
+export interface CaptureConfig {
+    /** Preferred render target type (auto-detected if not specified) */
+    targetType?: RenderTargetType;
+    /** Custom CSS selector to find the render target */
+    targetSelector?: string;
+    /** Custom capture handler (overrides automatic detection) */
+    customHandler?: CaptureHandler;
+    /** Default filename for exports */
+    filename?: string;
+    /** Default format for image capture */
+    defaultFormat?: CaptureFormat;
+    /** Quality for JPEG/WebP (0-1) */
+    quality?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/capture/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/capture/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM;IACtC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACxC,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAE9B,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,cAAc,CAAC;IAE/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,uCAAuC;IACvC,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}