@hypertools/sdk 0.3.2 → 0.4.0

package/examples/react-landing/src/App.tsx

@@ -0,0 +1,483 @@
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { ExperienceController } from '@hypertools/sdk';
+import type { ExportedExperienceElement } from '@hypertools/sdk';
+import './App.css';
+
+/**
+ * React Landing Page with HyperTools Experience Background
+ *
+ * This example shows how to:
+ * 1. Use an exported HyperTools experience as a background
+ * 2. Control it programmatically via ExperienceController from @hypertools/sdk
+ * 3. Build CUSTOM features on top that the platform doesn't provide
+ */
+
+// === CUSTOM FEATURE: Preset configurations ===
+const PRESETS = {
+  default: { birdCount: 810, rainbowMode: true, displayText: 'HYPERTOOLS' },
+  calm: { birdCount: 100, rainbowMode: false, displayText: 'ZEN' },
+  party: { birdCount: 800, rainbowMode: true, displayText: 'PARTY!' },
+  chaos: { birdCount: 1000, rainbowMode: true, displayText: 'CHAOS' },
+  minimal: { birdCount: 50, rainbowMode: false, displayText: '' },
+};
+
+type PresetName = keyof typeof PRESETS;
+
+// === CUSTOM FEATURE: Time-based themes ===
+const getTimeBasedTheme = () => {
+  const hour = new Date().getHours();
+  if (hour >= 6 && hour < 12) return { name: 'Morning', displayText: 'RISE & SHINE' };
+  if (hour >= 12 && hour < 17) return { name: 'Afternoon', displayText: 'PRODUCTIVE' };
+  if (hour >= 17 && hour < 21) return { name: 'Evening', displayText: 'GOLDEN HOUR' };
+  return { name: 'Night', displayText: 'DREAM MODE' };
+};
+
+function App() {
+  const experienceRef = useRef<ExportedExperienceElement>(null);
+  const controllerRef = useRef<ExperienceController | null>(null);
+
+  // Track some params for the UI
+  const [birdCount, setBirdCount] = useState(810);
+  const [rainbowMode, setRainbowMode] = useState(true);
+  const [displayText, setDisplayText] = useState('HYPERTOOLS');
+  const [isReady, setIsReady] = useState(false);
+
+  // === CUSTOM FEATURE: Selected preset tracking ===
+  const [selectedPreset, setSelectedPreset] = useState<PresetName | null>('default');
+
+  // === CUSTOM FEATURE: Auto-pilot mode ===
+  const [autoPilot, setAutoPilot] = useState(false);
+  const autoPilotRef = useRef<number | null>(null);
+
+  // === CUSTOM FEATURE: Keyboard shortcuts ===
+  const [showShortcuts, setShowShortcuts] = useState(false);
+
+  // === CUSTOM FEATURE: Click-to-form mode ===
+  const [clickToForm, setClickToForm] = useState(false);
+
+  // === CUSTOM FEATURE: Idle screensaver ===
+  const [idleMode, setIdleMode] = useState(false);
+  const idleTimerRef = useRef<number | null>(null);
+  const IDLE_TIMEOUT = 10000; // 10 seconds of inactivity
+
+  // === Check if current values match any preset ===
+  const detectCurrentPreset = useCallback((): PresetName | null => {
+    for (const [name, preset] of Object.entries(PRESETS)) {
+      if (
+        preset.birdCount === birdCount &&
+        preset.rainbowMode === rainbowMode &&
+        preset.displayText === displayText
+      ) {
+        return name as PresetName;
+      }
+    }
+    return null; // Custom configuration
+  }, [birdCount, rainbowMode, displayText]);
+
+  // Update selected preset when values change
+  useEffect(() => {
+    setSelectedPreset(detectCurrentPreset());
+  }, [detectCurrentPreset]);
+
+  // Connect SDK controller when component mounts
+  useEffect(() => {
+    const element = experienceRef.current;
+    if (!element) return;
+
+    const onReady = () => {
+      // Connect ExperienceController from @hypertools/sdk
+      const controller = new ExperienceController({
+        element,
+        initialParams: {
+          birdCount: 810,
+          rainbowMode: true,
+          displayText: 'HYPERTOOLS',
+        },
+      });
+
+      // Listen to param changes
+      controller.on('paramChange', (event) => {
+        console.log('Param changed:', event.key, '=', event.value);
+      });
+
+      controllerRef.current = controller;
+      setIsReady(true);
+      console.log('ExperienceController connected!');
+      console.log('Available params:', controller.getParamDefs());
+    };
+
+    // Check if already ready or wait for ready event
+    if ((element as any)._cleanup) {
+      onReady();
+    } else {
+      element.addEventListener('ready', onReady, { once: true });
+    }
+
+    return () => {
+      element.removeEventListener('ready', onReady);
+      controllerRef.current?.destroy();
+    };
+  }, []);
+
+  // Handlers for UI controls
+  const handleBirdCountChange = (value: number) => {
+    setBirdCount(value);
+    controllerRef.current?.setParam('birdCount', value);
+  };
+
+  const handleRainbowToggle = () => {
+    const newValue = !rainbowMode;
+    setRainbowMode(newValue);
+    controllerRef.current?.setParam('rainbowMode', newValue);
+  };
+
+  const handleTextChange = (value: string) => {
+    setDisplayText(value);
+    controllerRef.current?.setParam('displayText', value);
+  };
+
+  const handleReset = () => {
+    controllerRef.current?.resetParams();
+    // Sync local state with defaults
+    const defs = controllerRef.current?.getParamDefs();
+    if (defs) {
+      setBirdCount(defs.birdCount?.value as number ?? 100);
+      setRainbowMode(defs.rainbowMode?.value as boolean ?? false);
+      setDisplayText(defs.displayText?.value as string ?? '');
+    }
+  };
+
+  // Trigger formation by dispatching synthetic mouse events
+  const handleTriggerFormation = useCallback(() => {
+    const controller = controllerRef.current;
+    if (!controller) return;
+
+    // Simulate long press: mousedown -> wait 600ms -> mouseup
+    controller.dispatchToCanvas('mousedown', { clientX: 400, clientY: 300 });
+    setTimeout(() => {
+      controller.dispatchToCanvas('mouseup', { clientX: 400, clientY: 300 });
+    }, 600);
+  }, []);
+
+  // === CUSTOM FEATURE: Apply preset ===
+  const applyPreset = useCallback((presetName: PresetName) => {
+    const preset = PRESETS[presetName];
+    controllerRef.current?.setParams(preset);
+    setBirdCount(preset.birdCount);
+    setRainbowMode(preset.rainbowMode);
+    setDisplayText(preset.displayText);
+    setSelectedPreset(presetName);
+  }, []);
+
+  // === CUSTOM FEATURE: Reset to default ===
+  const handleResetToDefault = useCallback(() => {
+    applyPreset('default');
+  }, [applyPreset]);
+
+  // === CUSTOM FEATURE: Share configuration URL ===
+  const handleShareConfig = useCallback(() => {
+    const config = { birdCount, rainbowMode, displayText };
+    const params = new URLSearchParams({
+      config: btoa(JSON.stringify(config))
+    });
+    const url = `${window.location.origin}${window.location.pathname}?${params}`;
+    navigator.clipboard.writeText(url);
+    alert('Configuration URL copied to clipboard!');
+  }, [birdCount, rainbowMode, displayText]);
+
+  // === CUSTOM FEATURE: Load config from URL on mount ===
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    const configParam = params.get('config');
+    if (configParam && isReady) {
+      try {
+        const config = JSON.parse(atob(configParam));
+        if (config.birdCount) handleBirdCountChange(config.birdCount);
+        if (config.rainbowMode !== undefined) {
+          setRainbowMode(config.rainbowMode);
+          controllerRef.current?.setParam('rainbowMode', config.rainbowMode);
+        }
+        if (config.displayText !== undefined) handleTextChange(config.displayText);
+      } catch (e) {
+        console.warn('Invalid config in URL');
+      }
+    }
+  }, [isReady]);
+
+  // === CUSTOM FEATURE: Apply time-based theme ===
+  const applyTimeTheme = useCallback(() => {
+    const theme = getTimeBasedTheme();
+    handleTextChange(theme.displayText);
+  }, []);
+
+  // === CUSTOM FEATURE: Auto-pilot cycling through presets ===
+  useEffect(() => {
+    if (!autoPilot || !isReady) {
+      if (autoPilotRef.current) {
+        clearInterval(autoPilotRef.current);
+        autoPilotRef.current = null;
+      }
+      return;
+    }
+
+    const presetNames = Object.keys(PRESETS) as (keyof typeof PRESETS)[];
+    let index = 0;
+
+    const cycle = () => {
+      applyPreset(presetNames[index]);
+      // Trigger formation on each cycle
+      setTimeout(handleTriggerFormation, 500);
+      index = (index + 1) % presetNames.length;
+    };
+
+    cycle(); // Apply first preset immediately
+    autoPilotRef.current = window.setInterval(cycle, 4000);
+
+    return () => {
+      if (autoPilotRef.current) {
+        clearInterval(autoPilotRef.current);
+      }
+    };
+  }, [autoPilot, isReady, applyPreset, handleTriggerFormation]);
+
+  // === CUSTOM FEATURE: Idle screensaver mode ===
+  useEffect(() => {
+    const resetIdleTimer = () => {
+      if (idleTimerRef.current) clearTimeout(idleTimerRef.current);
+      if (idleMode) {
+        setIdleMode(false);
+        setAutoPilot(false);
+      }
+      idleTimerRef.current = window.setTimeout(() => {
+        setIdleMode(true);
+        setAutoPilot(true); // Start auto-pilot when idle
+      }, IDLE_TIMEOUT);
+    };
+
+    const events = ['mousemove', 'mousedown', 'keydown', 'touchstart', 'scroll'];
+    events.forEach((event) => window.addEventListener(event, resetIdleTimer));
+    resetIdleTimer();
+
+    return () => {
+      events.forEach((event) => window.removeEventListener(event, resetIdleTimer));
+      if (idleTimerRef.current) clearTimeout(idleTimerRef.current);
+    };
+  }, [idleMode, IDLE_TIMEOUT]);
+
+  // === CUSTOM FEATURE: Click-to-form (click anywhere to trigger formation at that position) ===
+  useEffect(() => {
+    if (!clickToForm || !isReady) return;
+
+    const handleClick = (e: MouseEvent) => {
+      // Ignore clicks on the control panel
+      if ((e.target as HTMLElement).closest('.control-panel')) return;
+
+      const controller = controllerRef.current;
+      if (!controller) return;
+
+      // Trigger formation at click position
+      controller.dispatchToCanvas('mousedown', { clientX: e.clientX, clientY: e.clientY });
+      setTimeout(() => {
+        controller.dispatchToCanvas('mouseup', { clientX: e.clientX, clientY: e.clientY });
+      }, 600);
+    };
+
+    window.addEventListener('click', handleClick);
+    return () => window.removeEventListener('click', handleClick);
+  }, [clickToForm, isReady]);
+
+  // === CUSTOM FEATURE: Keyboard shortcuts ===
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (!isReady) return;
+      // Ignore if typing in input
+      if (e.target instanceof HTMLInputElement) return;
+
+      switch (e.key.toLowerCase()) {
+        case ' ':
+          e.preventDefault();
+          handleTriggerFormation();
+          break;
+        case 'arrowup':
+          e.preventDefault();
+          handleBirdCountChange(Math.min(birdCount + 50, 1000));
+          break;
+        case 'arrowdown':
+          e.preventDefault();
+          handleBirdCountChange(Math.max(birdCount - 50, 10));
+          break;
+        case 'r':
+          setRainbowMode((prev) => {
+            const newValue = !prev;
+            controllerRef.current?.setParam('rainbowMode', newValue);
+            return newValue;
+          });
+          break;
+        case 's':
+          handleShareConfig();
+          break;
+        case 'a':
+          setAutoPilot((prev) => !prev);
+          break;
+        case '1':
+          applyPreset('calm');
+          break;
+        case '2':
+          applyPreset('party');
+          break;
+        case '3':
+          applyPreset('chaos');
+          break;
+        case '4':
+          applyPreset('minimal');
+          break;
+        case '?':
+          setShowShortcuts((prev) => !prev);
+          break;
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [isReady, birdCount, handleTriggerFormation, handleShareConfig, applyPreset]);
+
+  return (
+    <div className="landing-page">
+      {/* Background: Exported HyperTools Experience */}
+      <div className="experience-background">
+        {/* @ts-expect-error - Custom element */}
+        <boids-flocking-project ref={experienceRef} />
+      </div>
+
+      {/* Foreground: Control Panel at bottom center */}
+      <div className="landing-content">
+        {!isReady && <p className="loading">Loading experience...</p>}
+
+        {/* Demo: Programmatic control via ExperienceController */}
+        <section className="control-panel">
+          <div className="panel-header">
+            <h2>Control the Background</h2>
+            <button className="help-button" onClick={() => setShowShortcuts(true)}>?</button>
+          </div>
+          <p className="sdk-info">Custom features built with @hypertools/sdk</p>
+
+          {/* === CUSTOM FEATURE: Preset buttons with selection indicator === */}
+          <div className="preset-group">
+            {(Object.keys(PRESETS) as PresetName[]).map((preset) => (
+              <button
+                key={preset}
+                className={`preset-button ${selectedPreset === preset ? 'selected' : ''}`}
+                onClick={() => applyPreset(preset)}
+              >
+                {preset}
+              </button>
+            ))}
+          </div>
+          {selectedPreset === null && (
+            <p className="custom-config-hint">Custom configuration</p>
+          )}
+
+          <div className="control-group">
+            <label>
+              Bird Count: {birdCount}
+              <input
+                type="range"
+                min={10}
+                max={1000}
+                step={10}
+                value={birdCount}
+                onChange={(e) => handleBirdCountChange(Number(e.target.value))}
+              />
+            </label>
+          </div>
+
+          <div className="control-group">
+            <label>
+              <input
+                type="checkbox"
+                checked={rainbowMode}
+                onChange={handleRainbowToggle}
+              />
+              Rainbow Mode
+            </label>
+          </div>
+
+          <div className="control-group">
+            <label>
+              Display Text:
+              <input
+                type="text"
+                value={displayText}
+                onChange={(e) => handleTextChange(e.target.value)}
+              />
+            </label>
+          </div>
+
+          {/* === CUSTOM FEATURES: Action buttons === */}
+          <div className="button-group">
+            <button className="action-button" onClick={handleTriggerFormation}>
+              Formation
+            </button>
+            <button
+              className={`action-button ${clickToForm ? 'active' : ''}`}
+              onClick={() => setClickToForm(!clickToForm)}
+              title="Click anywhere to trigger formation at that position"
+            >
+              {clickToForm ? 'Click: ON' : 'Click Mode'}
+            </button>
+          </div>
+
+          <div className="button-group">
+            <button
+              className={`action-button ${autoPilot ? 'active' : ''}`}
+              onClick={() => setAutoPilot(!autoPilot)}
+            >
+              {autoPilot ? 'Stop Auto' : 'Auto-pilot'}
+            </button>
+            <button className="action-button" onClick={applyTimeTheme}>
+              Time Theme
+            </button>
+          </div>
+
+          <div className="button-group">
+            <button className="action-button" onClick={handleShareConfig}>
+              Share Config
+            </button>
+            <button className="reset-button" onClick={handleResetToDefault}>
+              Reset
+            </button>
+          </div>
+
+          {/* === Idle mode indicator === */}
+          {idleMode && (
+            <p className="idle-indicator">Screensaver mode active</p>
+          )}
+        </section>
+      </div>
+
+      {/* === CUSTOM FEATURE: Keyboard shortcuts overlay === */}
+      {showShortcuts && (
+        <div className="shortcuts-overlay" onClick={() => setShowShortcuts(false)}>
+          <div className="shortcuts-panel" onClick={(e) => e.stopPropagation()}>
+            <h3>Keyboard Shortcuts</h3>
+            <p className="shortcuts-subtitle">Custom controls built on top of the SDK</p>
+            <ul>
+              <li><kbd>Space</kbd> Trigger formation</li>
+              <li><kbd>↑</kbd> / <kbd>↓</kbd> Adjust bird count</li>
+              <li><kbd>R</kbd> Toggle rainbow mode</li>
+              <li><kbd>S</kbd> Share config URL</li>
+              <li><kbd>A</kbd> Toggle auto-pilot</li>
+              <li><kbd>1-4</kbd> Apply presets</li>
+              <li><kbd>?</kbd> Show/hide this help</li>
+            </ul>
+            <button className="close-button" onClick={() => setShowShortcuts(false)}>
+              Close
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default App;

package/examples/react-landing/src/main.tsx

@@ -0,0 +1,9 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

package/examples/react-landing/src/types.d.ts

@@ -0,0 +1,24 @@
+// Type definitions for the exported web component
+export interface BoidsFlockingProjectElement extends HTMLElement {
+  setParam(key: string, value: unknown): void;
+  setParams(params: Record<string, unknown>): void;
+  getParams(): Record<string, unknown>;
+  getParamDefs(): Record<string, { type: string; value: unknown; [key: string]: unknown }>;
+}
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'boids-flocking-project': React.DetailedHTMLProps<
+        React.HTMLAttributes<BoidsFlockingProjectElement> & {
+          ref?: React.Ref<BoidsFlockingProjectElement>;
+        },
+        BoidsFlockingProjectElement
+      >;
+    }
+  }
+
+  interface HTMLElementTagNameMap {
+    'boids-flocking-project': BoidsFlockingProjectElement;
+  }
+}

package/examples/react-landing/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/examples/react-landing/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+  },
+});

package/examples/recording/index.html

@@ -0,0 +1,113 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>HyperTool SDK - Recording 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;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      padding: 2rem;
+    }
+    h1 { margin-bottom: 0.5rem; }
+    .subtitle { color: #888; margin-bottom: 1.5rem; }
+    #canvas-container {
+      width: 800px;
+      height: 600px;
+      border-radius: 8px;
+      overflow: hidden;
+      background: #000;
+    }
+    .controls {
+      margin-top: 1.5rem;
+      display: flex;
+      gap: 1rem;
+      flex-wrap: wrap;
+      justify-content: center;
+    }
+    button {
+      padding: 0.75rem 1.5rem;
+      border: none;
+      border-radius: 4px;
+      background: #4a4a6a;
+      color: #fff;
+      cursor: pointer;
+      font-size: 1rem;
+      transition: background 0.2s;
+    }
+    button:hover { background: #5a5a7a; }
+    button:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+    button.recording {
+      background: #ff4444;
+      animation: pulse 1s infinite;
+    }
+    button.primary { background: #00ff88; color: #000; }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.7; }
+    }
+    .status {
+      margin-top: 1rem;
+      padding: 1rem;
+      background: #2a2a4a;
+      border-radius: 8px;
+      font-family: monospace;
+      font-size: 0.9rem;
+      min-width: 300px;
+    }
+    .timeline-section {
+      margin-top: 2rem;
+      padding: 1.5rem;
+      background: #2a2a4a;
+      border-radius: 8px;
+      width: 100%;
+      max-width: 800px;
+    }
+    .timeline-section h2 { margin-bottom: 1rem; font-size: 1.2rem; }
+    .timeline-controls { display: flex; gap: 1rem; flex-wrap: wrap; }
+    input[type="range"] { width: 200px; }
+  </style>
+</head>
+<body>
+  <h1>Recording & Timeline Example</h1>
+  <p class="subtitle">Video capture and keyframe animation</p>
+
+  <div id="canvas-container"></div>
+
+  <div class="controls">
+    <button id="capture-png">Capture PNG</button>
+    <button id="start-recording">Start Recording</button>
+    <button id="stop-recording" disabled>Stop Recording</button>
+  </div>
+
+  <div class="status">
+    <div id="status-text">Ready</div>
+    <div id="frame-count">Frame: 0</div>
+  </div>
+
+  <div class="timeline-section">
+    <h2>Timeline Animation</h2>
+    <div class="timeline-controls">
+      <button id="play-timeline" class="primary">Play Timeline</button>
+      <button id="pause-timeline">Pause</button>
+      <button id="reset-timeline">Reset</button>
+      <label>
+        Seek:
+        <input type="range" id="seek-timeline" min="0" max="5000" value="0">
+      </label>
+    </div>
+  </div>
+
+  <script type="module" src="./main.ts"></script>
+</body>
+</html>