# DreamStack Integration Guide

Embed DreamStack apps into any website with the standalone SDK (~3KB).

## Quick Start

### 1. Iframe Embed

```html
<iframe src="https://your-dreamstack-app.com"
  style="border:none; width:100%; height:400px; border-radius:12px;"
  sandbox="allow-scripts allow-same-origin"
  loading="lazy">
</iframe>
```

### 2. Web Component

```html
<script src="dreamstack-embed.js"></script>
<ds-stream src="https://your-app.com" height="500px"></ds-stream>
```

### 3. JavaScript API

```html
<div id="app"></div>
<script src="dreamstack-embed.js"></script>
<script>
  // Simple embed
  DreamStack.embed('https://your-app.com', '#app', {
    width: '100%',
    height: '500px'
  });

  // With bidirectional signals
  const ds = DreamStack.connect('https://your-app.com', '#app');
  ds.send('theme', 'dark');
  ds.on('score', (value) => console.log('Score:', value));
  ds.on('*', (name, value) => console.log(name, '=', value));
</script>
```

## Framework Examples

### React
```jsx
import { useEffect, useRef } from 'react';

function DreamStackEmbed({ src }) {
  const ref = useRef(null);
  useEffect(() => {
    const handle = DreamStack.connect(src, ref.current);
    return () => handle.destroy();
  }, [src]);
  return <div ref={ref} />;
}
```

### Vue
```vue
<template>
  <div ref="container" />
</template>
<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
const container = ref(null);
let handle;
onMounted(() => {
  handle = DreamStack.connect(props.src, container.value);
});
onUnmounted(() => handle?.destroy());
</script>
```

## Build Flags

```bash
# Standard build
dreamstack build app.ds

# Minified (strips whitespace, ~17% smaller)
dreamstack build app.ds --minify

# Both optimizations are always active:
# - DOM helpers (shorthand functions, ~3KB saved)
# - Tree-shaking (unused runtime features stripped, ~40-50% saved)
```

## Signal Bridge Protocol

DreamStack apps communicate via `postMessage`:

```js
// Send to DreamStack app
iframe.contentWindow.postMessage({
  type: 'ds:signal',
  name: 'playerName',
  value: 'Alice'
}, '*');

// Receive from DreamStack app
window.addEventListener('message', (e) => {
  if (e.data?.type === 'ds:signal') {
    console.log(e.data.name, '=', e.data.value);
  }
});
```

## Size Budget

| Build Mode | Size | Reduction |
|---|---|---|
| Default | ~95 KB | baseline |
| DOM helpers (auto) | ~95 KB | -3% |
| Tree-shaken (auto) | ~52 KB | -46% |
| + Minified | ~44 KB | -54% |
| Gzipped | ~8 KB | ~92% |