dreamstack/docs/integration.md

DreamStack Integration Guide

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

Quick Start

1. Iframe Embed

<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

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

3. JavaScript API

<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

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

<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

# 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:

// 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%