feat: Add embed blocks support with EmbedType enum (v0.17.0)

- Add embed_block() helper for embedding external content
- Add EmbedType enum (YOUTUBE, FIGMA, VIMEO, CODESANDBOX, GITHUB_GIST, MIRO, IFRAME)
- Automatic URL transformation for YouTube, Figma, and GitHub Gist
- Add EmbedBlockNode, EmbedBlockAttrs, EmbedBlockData types
- Add 18 unit tests and 1 integration test
- Add embed_blocks_example.py example
- Update documentation (guides, API reference, enums)
- Add enum documentation standards to project rules
- Compact JSON serialization for embed data
- Auto-generate UIDs using _generate_uid() for consistency

Author: m-brtn

.cursor/rules/project-standards.mdc

@@ -49,6 +49,62 @@ Follow this checklist to ensure completeness:
    - [ ] Use existing enums instead of primitive types where applicable (e.g., `AvatarMode` instead of `int`)
    - [ ] Reuse shared models from `vaiz/models/base.py` (e.g., `ColorInfo` for color configurations)
 
+### Enums Documentation
+
+When adding new enums, follow these documentation standards:
+
+**1. Code Implementation:**
+- Export enum from `vaiz/__init__.py` for easy access
+- Use `str, Enum` inheritance for string enums
+- Use descriptive names matching API values
+
+**2. Documentation Structure:**
+
+In **`docs-site/docs/api-reference/enums.md`**:
+```markdown
+## EnumName
+
+Brief description of what the enum represents:
+
+```python
+from vaiz import EnumName  # or from vaiz.models.enums
+
+EnumName.VALUE1  # Description
+EnumName.VALUE2  # Description
+```
+
+**Usage:**
+
+```python
+from vaiz import function_name, EnumName
+
+# Show real-world example
+function_name(
+    param=EnumName.VALUE1
+)
+```
+```
+
+In **Guide Pages** (`docs-site/docs/guides/*.md`):
+- Show simple usage WITHOUT explicit enum references in examples
+- Add link to enum documentation: `See [EnumName](../api-reference/enums#enumname)`
+- Focus on functionality, not enum details
+
+**Example:**
+
+```python
+# ✅ Good - Guide page example (simple)
+embed_block(url="https://youtube.com/...")
+
+# ❌ Bad - Don't show enum in guides
+embed_block(url="...", embed_type=EmbedType.YOUTUBE)
+```
+
+**3. References:**
+- Always link to enum documentation: `[EnumName](../api-reference/enums#enumname)`
+- Mention enum exists but show simple usage first
+- Full enum examples only in `enums.md` and examples files
+
 ## Changelog
 
 **Keep CHANGELOG.md user-focused and concise:**

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.17.0] - 2025-10-24
+
+### Added
+
+- **🎬 Embed Blocks**: Support for embedding external content (YouTube, Figma, CodeSandbox, etc.)
+  - `embed_block(url, embed_type, size, is_content_hidden)` - Create embed blocks for external content
+  - `EmbedType` enum - Type-safe embed types (YOUTUBE, FIGMA, VIMEO, CODESANDBOX, GITHUB_GIST, MIRO, IFRAME)
+
 ## [0.16.0] - 2025-10-24
 
 ### Changed

docs-site/docs/api-reference/document-structure.md

@@ -1242,6 +1242,87 @@ client.replace_json_document(document_id, content)
 
 ---
 
+## Embed Block
+
+Embed external content from various platforms (YouTube, Figma, Vimeo, CodeSandbox, GitHub Gist, Miro, Iframe).
+
+**Structure:**
+```json
+{
+  "type": "embed",
+  "attrs": {
+    "uid": "uniqueIdXYZ",
+    "custom": 1,
+    "contenteditable": "false",
+    "size": "medium",
+    "isContentHidden": false
+  },
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"type\":\"YouTube\",\"url\":\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\",\"extractedUrl\":\"https://www.youtube.com/watch?v=dQw4w9WgXcQ\"}"
+    }
+  ]
+}
+```
+
+**Embed Data Fields:**
+- `type` - Embed type: `"YouTube"`, `"Figma"`, `"Vimeo"`, `"CodeSandbox"`, `"GitHub Gist"`, `"Miro"`, `"Iframe"`
+- `url` - URL of content to embed
+- `extractedUrl` - Extracted/processed URL (usually same as url)
+- `isContentHidden` - Optional, for Figma/Miro to hide content by default
+
+**Attributes:**
+- `uid` - Unique block identifier
+- `custom` - Always 1 for custom blocks
+- `contenteditable` - Should be "false"
+- `size` - Display size: `"small"`, `"medium"`, or `"large"`
+- `isContentHidden` - Whether content is hidden by default
+
+**Using Helper (Recommended):**
+```python
+from vaiz import embed_block, heading, paragraph, horizontal_rule
+
+content = [
+    heading(1, "Project Resources"),
+    
+    # YouTube video
+    heading(2, "Demo Video"),
+    embed_block(
+        url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+        size="large"
+    ),
+    
+    horizontal_rule(),
+    
+    # Figma design
+    heading(2, "Design Files"),
+    embed_block(
+        url="https://www.figma.com/file/example",
+        size="large",
+        is_content_hidden=True
+    ),
+    
+    horizontal_rule(),
+    
+    # Live code sandbox
+    heading(2, "Code Example"),
+    embed_block(url="https://codesandbox.io/s/example")
+]
+
+client.replace_json_document(document_id, content)
+```
+
+See [EmbedType enum](./enums#embedtype) for type-safe values.
+
+**Parameters:**
+- `url` - URL of content to embed
+- `embed_type` - Type of embed (optional, see [EmbedType](./enums#embedtype))
+- `size` - Display size: `"small"`, `"medium"`, `"large"` (default: `"medium"`)
+- `is_content_hidden` - Hide content by default (default: `False`)
+
+---
+
 ## Image Block
 
 Embedded images in documents and task descriptions.

docs-site/docs/api-reference/enums.md

@@ -82,6 +82,46 @@ CommentReactionType.PARTY        # 🎉
 
 ---
 
+## EmbedType
+
+Embed content types for document embed blocks:
+
+```python
+from vaiz import EmbedType
+
+EmbedType.YOUTUBE       # YouTube videos
+EmbedType.FIGMA         # Figma design files
+EmbedType.VIMEO         # Vimeo videos
+EmbedType.CODESANDBOX   # CodeSandbox code sandboxes
+EmbedType.GITHUB_GIST   # GitHub Gists
+EmbedType.MIRO          # Miro whiteboards
+EmbedType.IFRAME        # Generic iframe (default)
+```
+
+**Usage:**
+
+```python
+from vaiz import embed_block, EmbedType
+
+# YouTube video
+embed_block(
+    url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+    embed_type=EmbedType.YOUTUBE
+)
+
+# Figma design
+embed_block(
+    url="https://www.figma.com/file/example",
+    embed_type=EmbedType.FIGMA,
+    is_content_hidden=True
+)
+
+# Default to Iframe when embed_type not specified
+embed_block(url="https://example.com/embed")
+```
+
+---
+
 ## Kind
 
 Entity types for history and documents:

docs-site/docs/guides/document-structure-helpers.md

@@ -1116,6 +1116,76 @@ client.replace_json_document(document_id, content)
 - Optional language specification
 - Automatic formatting
 
+### Embed Block - External Content
+
+Embed external content from various platforms:
+
+```python
+from vaiz import embed_block, heading, paragraph, horizontal_rule
+
+content = [
+    heading(1, "Project Resources"),
+    
+    # YouTube video
+    heading(2, "Demo Video"),
+    paragraph("Watch our product demo:"),
+    embed_block(
+        url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+        size="large"
+    ),
+    
+    horizontal_rule(),
+    
+    # Figma design
+    heading(2, "Design Mockups"),
+    paragraph("View the design files:"),
+    embed_block(
+        url="https://www.figma.com/file/example",
+        size="large",
+        is_content_hidden=True
+    ),
+    
+    horizontal_rule(),
+    
+    # CodeSandbox
+    heading(2, "Live Code Example"),
+    paragraph("Try the code live:"),
+    embed_block(url="https://codesandbox.io/s/example"),
+    
+    horizontal_rule(),
+    
+    # Generic iframe (default)
+    heading(2, "External Tool"),
+    embed_block(url="https://example.com/embed")
+]
+
+client.replace_json_document(document_id, content)
+```
+
+**Supported Embed Types:**
+- YouTube - YouTube videos
+- Figma - Figma design files
+- Vimeo - Vimeo videos
+- CodeSandbox - Interactive code sandboxes
+- GitHub Gist - GitHub code snippets
+- Miro - Miro whiteboards
+- Iframe - Generic iframe embeds (default)
+
+See [EmbedType enum](../api-reference/enums#embedtype) for type-safe values.
+
+**Parameters:**
+- `url` - URL of content to embed
+- `embed_type` - Type of embed (optional, see [EmbedType](../api-reference/enums#embedtype))
+- `size` - Display size: `"small"`, `"medium"`, `"large"` (default: `"medium"`)
+- `is_content_hidden` - Hide content by default for Figma/Miro (default: `False`)
+
+**Use Cases:**
+- Video tutorials and demos
+- Design system documentation
+- Live code examples
+- Interactive prototypes
+- External tool integrations
+
 ### Complete Navigation Example
 
 Combine all navigation blocks for optimal user experience:
@@ -1190,6 +1260,7 @@ All helper functions create nodes compatible with the document editor:
 - ✅ `image_block()` - Embed images
 - ✅ `files_block()` - Attach files
 - ✅ `code_block()` - Code with syntax highlighting
+- ✅ `embed_block()` - Embed external content (YouTube, Figma, etc.)
 
 ### Navigation Blocks
 - ✅ `toc_block()` - Automatic table of contents

docs-site/docs/patterns/ready-to-run.md

@@ -47,6 +47,7 @@ The SDK includes a collection of ready-to-run examples in the [`/examples`](http
 - **`advanced_mention_usage.py`** - Advanced usage of mentions in tables, lists, and complex documents
 - **`document_navigation_blocks.py`** - TOC, Anchors, and Siblings navigation blocks
 - **`document_with_code_blocks.py`** - Code blocks with syntax highlighting
+- **`embed_blocks_example.py`** - Embed external content (YouTube, Figma, CodeSandbox, etc.)
 
 ## Custom Fields
 

docs-site/docusaurus.config.ts

@@ -206,8 +206,8 @@ const config: Config = {
       },
       items: [
         {
-          label: "v0.16.0",
-          href: "https://pypi.org/project/vaiz-sdk/0.16.0/",
+          label: "v0.17.0",
+          href: "https://pypi.org/project/vaiz-sdk/0.17.0/",
           position: "left",
         },
         {