@hypertools/sdk 0.3.3 → 0.4.0

package/README.md

@@ -402,10 +402,185 @@ controls.refresh();
 controls.dispose();
 ```
 
+## Using Exported HyperTools Experiences
+
+When you export a project from [HyperTools](https://hypertools.dev), you get a standalone web component that can be embedded anywhere. Use `ExperienceController` from this SDK to control it programmatically.
+
+### Setup
+
+1. **Get your exported experience** - Export from HyperTools to get a JS file (e.g., `my-experience.js`)
+
+2. **Load the experience** in your HTML:
+```html
+<script src="./my-experience.js"></script>
+<my-experience></my-experience>
+```
+
+3. **Install the SDK** to control it:
+```bash
+npm install @hypertools/sdk
+```
+
+### Basic Control
+
+```typescript
+import { ExperienceController } from '@hypertools/sdk';
+
+// Get reference to the web component
+const element = document.querySelector('my-experience');
+
+// Connect the controller
+const controller = new ExperienceController({
+  element,
+  initialParams: {
+    speed: 5,
+    color: '#ff0000',
+  },
+});
+
+// Control parameters
+controller.setParam('speed', 10);
+controller.setParams({ speed: 8, color: '#00ff00' });
+
+// Get current values
+const params = controller.getParams();
+const paramDefs = controller.getParamDefs();
+
+// Reset to defaults
+controller.resetParams();
+
+// Listen to changes
+controller.on('paramChange', (event) => {
+  console.log(`${event.key} changed to ${event.value}`);
+});
+
+// Cleanup when done
+controller.destroy();
+```
+
+### Dispatching Events
+
+Trigger interactions programmatically by dispatching synthetic events:
+
+```typescript
+// Simulate a click
+controller.dispatchToCanvas('click', { clientX: 400, clientY: 300 });
+
+// Simulate a long press (e.g., for formation triggers)
+controller.dispatchToCanvas('mousedown', { clientX: 400, clientY: 300 });
+setTimeout(() => {
+  controller.dispatchToCanvas('mouseup', { clientX: 400, clientY: 300 });
+}, 600);
+
+// Keyboard events
+controller.dispatchToCanvas('keydown', { key: 'Space' });
+
+// Custom events
+controller.dispatchCustomEvent('myEvent', { data: 'hello' });
+```
+
+### React Integration
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
+import { ExperienceController } from '@hypertools/sdk';
+import type { ExportedExperienceElement } from '@hypertools/sdk';
+
+function App() {
+  const experienceRef = useRef<ExportedExperienceElement>(null);
+  const controllerRef = useRef<ExperienceController | null>(null);
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    const element = experienceRef.current;
+    if (!element) return;
+
+    const onReady = () => {
+      controllerRef.current = new ExperienceController({ element });
+      setIsReady(true);
+    };
+
+    element.addEventListener('ready', onReady, { once: true });
+
+    return () => {
+      element.removeEventListener('ready', onReady);
+      controllerRef.current?.destroy();
+    };
+  }, []);
+
+  return (
+    <div>
+      {/* @ts-expect-error - Custom element */}
+      <my-experience ref={experienceRef} />
+
+      {isReady && (
+        <button onClick={() => controllerRef.current?.setParam('speed', 10)}>
+          Speed Up
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### ExperienceController API
+
+```typescript
+// Constructor options
+interface ExperienceControllerConfig {
+  element: ExportedExperienceElement;  // The web component
+  initialParams?: Record<string, unknown>;  // Override initial values
+  autoConnect?: boolean;  // Connect immediately (default: true)
+}
+
+// Methods
+controller.connect();      // Connect to element
+controller.disconnect();   // Disconnect from element
+controller.destroy();      // Full cleanup
+
+controller.setParam(key, value);
+controller.setParams(params);
+controller.getParams();
+controller.getParamDefs();
+controller.resetParams();
+
+controller.on(event, handler);   // Subscribe
+controller.once(event, handler); // Subscribe once
+controller.off(event, handler);  // Unsubscribe
+
+controller.dispatchToCanvas(eventType, eventInit);  // Dispatch to canvas
+controller.dispatchToElement(eventType, eventInit); // Dispatch to element
+controller.dispatchCustomEvent(type, detail);       // Custom event
+
+controller.getCanvas();  // Get canvas element
+controller.getMount();   // Get mount element
+
+// Properties
+controller.element;      // The web component
+controller.isConnected;  // Connection status
+controller.isDestroyed;  // Destroyed status
+
+// Static factories
+ExperienceController.fromSelector('my-experience');
+await ExperienceController.whenDefined('my-experience');
+```
+
+### Building Custom Features
+
+See [`examples/react-landing/`](./examples/react-landing/) for a complete example showing how to build custom features on top of exported experiences:
+
+- **Preset System** - Pre-configured settings with visual selection
+- **Click-to-Form Mode** - Click anywhere to trigger interactions at that position
+- **Auto-pilot Mode** - Automatically cycle through presets
+- **Idle Screensaver** - Start animations after inactivity
+- **Share Configuration** - Generate shareable URLs with encoded settings
+- **Keyboard Shortcuts** - Custom keyboard controls
+
 ## Examples
 
 See the `/examples` directory for complete working examples:
 
+- `examples/react-landing/` - **React app with exported experience as background + custom features**
 - `examples/vanilla-canvas/` - Pure Canvas API
 - `examples/p5js/` - p5.js sketch
 - `examples/threejs/` - Three.js scene

package/examples/README.md

@@ -0,0 +1,84 @@
+# @hypertools/sdk Examples
+
+Working examples demonstrating different SDK features and integrations.
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [vanilla-canvas](./vanilla-canvas/) | Pure Canvas API with particle system |
+| [p5js](./p5js/) | p5.js generative art integration |
+| [threejs](./threejs/) | Three.js 3D scene with particles |
+| [react](./react/) | React hooks integration |
+| [recording](./recording/) | Video capture & timeline animation |
+
+## Running Examples
+
+These examples use TypeScript and require a bundler. You can run them with:
+
+### Using Vite (recommended)
+
+```bash
+# Install vite
+npm install -g vite
+
+# Run an example
+cd examples/vanilla-canvas
+vite
+```
+
+### Using esbuild + serve
+
+```bash
+# Install dependencies
+npm install -g esbuild serve
+
+# Build and serve
+cd examples/vanilla-canvas
+esbuild main.ts --bundle --outfile=main.js --format=esm
+serve .
+```
+
+### Using Bun
+
+```bash
+cd examples/vanilla-canvas
+bun run --bun vite
+```
+
+## Example Structure
+
+Each example contains:
+
+- `index.html` - HTML entry point
+- `main.ts` or `main.tsx` - TypeScript source code
+
+## Dependencies
+
+Some examples require peer dependencies:
+
+- **p5js**: Requires p5.js (loaded via CDN in example)
+- **threejs**: Requires `three` package
+- **react**: Requires `react` and `react-dom`
+
+## Creating Your Own
+
+Use these examples as templates for your own experiences:
+
+```typescript
+import { Experience } from '@hypertools/sdk';
+
+new Experience({
+  mount: document.getElementById('container')!,
+  paramDefs: {
+    // Define your parameters
+  },
+  setup(context) {
+    // Your creative code here
+
+    return () => {
+      // Cleanup
+    };
+  },
+});
+```

package/examples/p5js/index.html

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>HyperTool SDK - p5.js Example</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: system-ui, sans-serif;
+      background: #0f0f1a;
+      color: #fff;
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      padding: 2rem;
+    }
+    h1 { margin-bottom: 1rem; }
+    #sketch-container {
+      border-radius: 8px;
+      overflow: hidden;
+    }
+    .info {
+      margin-top: 1rem;
+      font-size: 0.9rem;
+      color: #888;
+    }
+  </style>
+</head>
+<body>
+  <h1>p5.js Generative Art</h1>
+  <div id="sketch-container"></div>
+  <p class="info">Move your mouse to influence the pattern. Parameters are reactive!</p>
+
+  <script src="https://cdn.jsdelivr.net/npm/p5@1.9.0/lib/p5.min.js"></script>
+  <script type="module" src="./main.ts"></script>
+</body>
+</html>

package/examples/p5js/main.ts

@@ -0,0 +1,136 @@
+/**
+ * p5.js Example
+ *
+ * Demonstrates @hypertools/sdk integration with p5.js.
+ * Creates a generative art piece with reactive parameters.
+ */
+
+import { Experience } from '@hypertools/sdk';
+import type p5 from 'p5';
+
+// Declare p5 as global (loaded via CDN)
+declare const p5: typeof import('p5');
+
+new Experience({
+  mount: document.getElementById('sketch-container')!,
+  paramDefs: {
+    backgroundColor: {
+      type: 'color',
+      value: '#0f0f1a',
+      label: 'Background',
+    },
+    primaryColor: {
+      type: 'color',
+      value: '#ff6b6b',
+      label: 'Primary Color',
+    },
+    secondaryColor: {
+      type: 'color',
+      value: '#4ecdc4',
+      label: 'Secondary Color',
+    },
+    shapeCount: {
+      type: 'number',
+      value: 50,
+      min: 10,
+      max: 200,
+      step: 10,
+      label: 'Shape Count',
+    },
+    noiseScale: {
+      type: 'number',
+      value: 0.01,
+      min: 0.001,
+      max: 0.05,
+      step: 0.001,
+      label: 'Noise Scale',
+    },
+    rotationSpeed: {
+      type: 'number',
+      value: 0.5,
+      min: 0,
+      max: 2,
+      step: 0.1,
+      label: 'Rotation Speed',
+    },
+    animate: {
+      type: 'boolean',
+      value: true,
+      label: 'Animate',
+    },
+  },
+  setup(context) {
+    let sketch: p5;
+    let time = 0;
+
+    new p5((p: p5) => {
+      sketch = p;
+
+      p.setup = () => {
+        p.createCanvas(800, 600);
+        p.colorMode(p.HSB, 360, 100, 100, 100);
+        p.noStroke();
+      };
+
+      p.draw = () => {
+        if (!context.params.animate) return;
+
+        // Background with slight transparency for trails
+        p.background(context.params.backgroundColor as string);
+
+        const count = context.params.shapeCount as number;
+        const noiseScale = context.params.noiseScale as number;
+        const rotSpeed = context.params.rotationSpeed as number;
+
+        p.push();
+        p.translate(p.width / 2, p.height / 2);
+
+        // Mouse influence
+        const mx = p.map(p.mouseX, 0, p.width, -1, 1);
+        const my = p.map(p.mouseY, 0, p.height, -1, 1);
+
+        for (let i = 0; i < count; i++) {
+          const angle = p.map(i, 0, count, 0, p.TWO_PI);
+          const noiseVal = p.noise(
+            p.cos(angle) * noiseScale * 100 + time,
+            p.sin(angle) * noiseScale * 100 + time,
+            time * 0.5
+          );
+
+          const radius = 100 + noiseVal * 150 + mx * 50;
+          const x = p.cos(angle + time * rotSpeed) * radius;
+          const y = p.sin(angle + time * rotSpeed) * radius;
+
+          // Alternate colors
+          const color = i % 2 === 0
+            ? context.params.primaryColor
+            : context.params.secondaryColor;
+
+          p.fill(color as string);
+
+          const size = 10 + noiseVal * 30 + my * 10;
+          p.ellipse(x, y, size, size);
+
+          // Inner ring
+          const innerRadius = radius * 0.6;
+          const ix = p.cos(angle - time * rotSpeed * 0.5) * innerRadius;
+          const iy = p.sin(angle - time * rotSpeed * 0.5) * innerRadius;
+
+          p.fill(color as string);
+          p.ellipse(ix, iy, size * 0.5, size * 0.5);
+        }
+
+        p.pop();
+
+        time += 0.01;
+      };
+    }, context.mount);
+
+    // Register the p5 instance for external access
+    context.registerObject('p5Instance', sketch!, { type: 'p5' });
+
+    return () => {
+      sketch?.remove();
+    };
+  },
+});

package/examples/react/index.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>HyperTool SDK - React Example</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: system-ui, sans-serif;
+      background: #1a1a2e;
+      color: #fff;
+      min-height: 100vh;
+    }
+    #root { padding: 2rem; }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="./main.tsx"></script>
+</body>
+</html>