@modyo/mcp 0.1.0

package/docs/channels/snippets/overview.md

@@ -0,0 +1,631 @@
+# Modyo Snippets Architecture
+
+## Overview
+
+Snippets are reusable Liquid template blocks that power Modyo's rendering engine. They are the foundation of how widgets, grids, and page components are rendered.
+
+---
+
+## What are Snippets?
+
+**Snippets** are small, reusable pieces of Liquid code that can be included in layouts, pages, and other templates using the `{% snippet 'name' %}` tag.
+
+### Key Characteristics
+
+- **Reusable**: Can be included in multiple templates
+- **Liquid-based**: Use Liquid markup language
+- **Organized by groups**: general, grids, widgets, notifications, service_worker
+- **System-managed**: Core snippets are non-deletable (`deletable: false`)
+- **Versioned**: Support workflow and publishing like other Modyo resources
+
+---
+
+## Snippet Types and API Endpoints
+
+Modyo has **two types of snippets** with different API endpoints:
+
+### System Snippets (`/templates/snippets`)
+
+**API Endpoint**: `/api/admin/sites/{site_id}/templates/snippets`
+
+**Characteristics**:
+- ✅ Provided by Modyo (built-in)
+- ✅ Editable (can modify content)
+- ❌ Cannot be deleted (`deletable: false`)
+- 🔧 Structural base parts of the site
+- 🏗️ Header, footer, grids, and core rendering logic
+
+**Purpose**: Global structural components that define how the site works
+
+### Custom Snippets (`/templates/custom_snippets`)
+
+**API Endpoint**: `/api/admin/sites/{site_id}/templates/custom_snippets`
+
+**Characteristics**:
+- ✅ User-created
+- ✅ Fully editable (`deletable: true`)
+- 🎨 Reusable UI components
+- 🔄 Can be created, updated, and deleted
+
+**Purpose**: Custom reusable components for your specific site needs
+
+---
+
+## System Snippets (Built-in Structural Components)
+
+**From**: `/api/admin/sites/{site_id}/templates/snippets`
+
+### 1. General Snippets
+Global structural elements used across all pages:
+
+- **`head`** - HTML head section with meta tags
+- **`header`** - Site header/navigation
+- **`footer`** - Site footer
+- **`menu`** - Navigation menu rendering
+- **`seo`** - SEO meta tags
+- **`session`** - User session information
+- **`body_tag_manager`** - Analytics in body
+- **`head_tag_manager`** - Analytics in head
+
+### 2. Grid Snippets
+Define how widgets are laid out on pages:
+
+- **`full_grid`** - Single column (column 0)
+- **`full_two_cols_grid`** - Two columns (0, 1)
+- **`full_three_cols_grid`** - Three columns (0, 1, 2)
+- **`side_left_grid`** - Sidebar left + main
+- **`side_right_grid`** - Main + sidebar right
+- **`side_left_one_col_grid`** - Narrow left sidebar
+- **`side_right_one_col_grid`** - Narrow right sidebar
+- **`side_left_three_cols_grid`** - Left sidebar + 2 columns
+- **`side_right_three_cols_grid`** - 2 columns + right sidebar
+
+### 3. Widget Snippets
+Handle widget rendering based on type:
+
+- **`custom_widget`** - Renders custom widgets (normal or CLI)
+- **`rich_text_widget`** - Renders rich text content
+- **`text_widget`** - Renders plain text content
+
+### 4. Notification Snippets
+System notifications:
+
+- **`notifications_html`** - Notification HTML structure
+- **`notifications_css`** - Notification styles
+- **`notifications_js`** - Notification JavaScript
+
+### 5. Service Worker Snippets
+Progressive Web App support:
+
+- **`service_worker_js`** - Service worker code
+- **`register_js`** - Service worker registration
+
+**All system snippets** have `deletable: false` - their content can be edited and customized, but they cannot be deleted from the system
+
+---
+
+## Critical Snippet: `custom_widget`
+
+This is the **most important snippet** for understanding widget rendering.
+
+### Full Code
+
+```liquid
+<script nonce="{{csp_nonce}}">
+  window['resourceBasePath-{{widget.wid}}'] = "{{site.url}}/widget_manager/{{widget.wid}}/{{widget.version}}/";
+</script>
+
+{% if widget.sync %}
+  <style nonce="{{csp_nonce}}">
+    {{ widget.css }}
+  </style>
+  {{ widget.html }}
+  <script nonce="{{csp_nonce}}">
+    (function(){
+      {{ widget.js }}
+    })();
+  </script>
+
+{% else %}
+<section class="widget-definition widget-{{ widget.name | replace: ' ','-' | replace: 'ñ','n' | downcase }}" id="modyo-{{widget.manager_uuid}}/{{widget.version}}"></section>
+<script nonce="{{csp_nonce}}">
+  (function(){
+    var css_url = "{{site.url}}/widget_manager/{{widget.manager_uuid}}/{{widget.version}}.css";
+    var css;
+    css = document.createElement('link');
+    css.rel = 'stylesheet';
+    css.type = 'text/css';
+    css.media = "all";
+    css.href = css_url;
+    css.nonce = '{{ csp_nonce }}';
+    document.getElementsByTagName("head")[0].appendChild(css);
+  })();
+</script>
+
+{% endif %}
+```
+
+### Behavior Analysis
+
+#### When `widget.sync = true` (Synchronous)
+
+**What happens**:
+1. CSS injected inline in `<style>` tag
+2. HTML rendered directly in page
+3. JavaScript executed immediately in inline `<script>` tag
+4. All happens during page render (render-blocking)
+
+**Result**: Widget content appears immediately with page load but blocks rendering.
+
+#### When `widget.sync = false` (Asynchronous)
+
+**What happens**:
+1. Empty `<section>` placeholder created with widget ID
+2. CSS loaded asynchronously via dynamically created `<link>` tag
+3. HTML and JS loaded after page renders (via widget manager endpoint)
+4. Widget populates placeholder after page is already visible
+
+**Result**: Page renders faster, widget content appears shortly after (non-blocking).
+
+### Key Variables Available in Snippet
+
+```liquid
+{{ widget.wid }}            // Widget instance ID
+{{ widget.version }}        // Widget version number
+{{ widget.sync }}           // Boolean: sync/async mode
+{{ widget.css }}            // Widget CSS code
+{{ widget.html }}           // Widget HTML code
+{{ widget.js }}             // Widget JavaScript code
+{{ widget.name }}           // Widget name
+{{ widget.manager_uuid }}   // Widget definition UUID (OID)
+{{ site.url }}              // Site base URL
+{{ csp_nonce }}             // Content Security Policy nonce
+```
+
+---
+
+## Critical Snippet: Grid Layouts
+
+Grid snippets define how widgets are positioned on pages.
+
+### Example: `full_grid`
+
+```liquid
+{% for widget in page_grid.main_widgets %}
+{% snippet widget %}
+{% endfor %}
+```
+
+**Behavior**:
+- Loops through all widgets in `main_widgets` array
+- Renders each widget using appropriate snippet (custom_widget, rich_text_widget, etc.)
+- Single column layout (all widgets in column 0)
+
+### Example: `full_three_cols_grid`
+
+```liquid
+<div class="row">
+  <div class="col-md-4">
+    {% for widget in page_grid.column_0 %}
+    {% snippet widget %}
+    {% endfor %}
+  </div>
+  <div class="col-md-4">
+    {% for widget in page_grid.column_1 %}
+    {% snippet widget %}
+    {% endfor %}
+  </div>
+  <div class="col-md-4">
+    {% for widget in page_grid.column_2 %}
+    {% snippet widget %}
+    {% endfor %}
+  </div>
+</div>
+```
+
+**Behavior**:
+- Three columns using Bootstrap grid
+- Each column renders its own widgets array
+- Widgets positioned in columns 0, 1, 2
+
+### Available Grid Variables
+
+```liquid
+{{ page_grid.main_widgets }}   // All widgets (for single column)
+{{ page_grid.column_0 }}       // Widgets in column 0
+{{ page_grid.column_1 }}       // Widgets in column 1
+{{ page_grid.column_2 }}       // Widgets in column 2
+{{ page_grid.sidebar }}        // Sidebar widgets (for side_* grids)
+```
+
+---
+
+## How Snippets are Used
+
+### In Layouts
+
+Layouts use snippets to compose the complete HTML structure:
+
+```liquid
+{{ html5.open_tag }}
+<head>
+  {% snippet 'head' %}
+  {% snippet 'seo' %}
+</head>
+<body>
+  {% snippet 'header' %}
+  <main>
+    {{ content_for_layout }}
+  </main>
+  {% snippet 'footer' %}
+</body>
+{{ html5.close_tag }}
+```
+
+### In Pages
+
+Grid snippets are automatically invoked by `content_for_layout` based on page's `grid_type`:
+
+```typescript
+// When page has grid_type: "full_grid"
+// content_for_layout renders: {% snippet 'full_grid' %}
+
+// When page has grid_type: "full_three_cols_grid"
+// content_for_layout renders: {% snippet 'full_three_cols_grid' %}
+```
+
+### Complete Widget Rendering Flow
+
+```
+1. Browser requests page (e.g., /homepage)
+2. Modyo selects layout (e.g., layouts/default.liquid)
+3. Layout renders, encounters {{ content_for_layout }}
+4. Modyo checks page.grid_type (e.g., "full_three_cols_grid")
+5. Modyo builds page_grid object from page.widgets
+6. Modyo invokes grid snippet: {% snippet 'full_three_cols_grid' %}
+7. Grid snippet loops through page_grid.column_0, column_1, column_2
+8. For each widget, renders: {% snippet widget %}
+9. Widget snippet determines type (custom_widget, rich_text, etc.)
+10. If custom_widget:
+    a. Check widget.sync
+    b. If sync=true: inline CSS/HTML/JS (render-blocking)
+    c. If sync=false: placeholder + async CSS loading
+11. Final HTML sent to browser
+12. Async widgets load after page renders
+```
+
+---
+
+## Snippet Properties
+
+From the API, snippets have these properties:
+
+```typescript
+{
+  id: number,              // Snippet ID (CHANGES after publishing - see Versioning below)
+  uuid: string,            // Snippet UUID (STABLE - use for references)
+  type: string,            // "html", "css", "javascript"
+  path: string,            // File path in Modyo
+  status: string,          // "published", "draft"
+  deletable: boolean,      // Can be deleted (false for system snippets)
+  name: string,            // Snippet name (used in {% snippet 'name' %})
+  group: string,           // Category: general, grids, widgets, etc.
+  body: string,            // Liquid template code
+  workflow: object,        // Publishing workflow
+  lock_info: object        // Edit lock information
+}
+```
+
+### Critical: Versioning and ID Stability
+
+**IMPORTANT**: When a snippet or widget is published in Modyo:
+
+1. **ID Changes**: The `id` field will change because Modyo creates a new version
+2. **UUID Stable**: The `uuid` field remains constant across versions
+3. **Old Version Stored**: Previous version is stored for rollback/history
+4. **Rollback Available**: Can revert to previous versions via Modyo UI
+
+**Why This Matters**:
+```typescript
+// ❌ WRONG - Don't store or reference by ID
+const snippetId = 123;
+template-update({ templateId: snippetId, ... });  // May fail after publish
+
+// ✅ CORRECT - Always use UUID for references
+const snippetUuid = "abc123-def456-...";
+// Use UUID to find current ID, then update
+```
+
+**Versioning Workflow**:
+```
+1. Create snippet (id: 100, uuid: "abc123")
+2. Edit snippet (still id: 100, uuid: "abc123")
+3. Publish snippet → Creates version
+   - Old version archived (id: 100, version: 1)
+   - New published version (id: 101, uuid: "abc123")
+4. Edit again (id: 101, uuid: "abc123")
+5. Publish again → Creates another version
+   - Version 1 archived (id: 100)
+   - Version 2 archived (id: 101)
+   - New published version (id: 102, uuid: "abc123")
+```
+
+**Rollback Behavior**:
+- Can revert to version 1 (id: 100) or version 2 (id: 101)
+- After rollback, a new version is created with new ID
+- UUID always remains "abc123" throughout all versions
+
+**Best Practices**:
+- ✅ Use `uuid` for stable references across versions
+- ✅ Fetch current version by UUID before operations
+- ✅ Store UUIDs in external systems, not IDs
+- ❌ Don't hardcode snippet/widget IDs
+- ❌ Don't assume IDs remain constant after publishing
+
+---
+
+## Custom Snippets (User-Created)
+
+**From**: `/api/admin/sites/{site_id}/templates/custom_snippets`
+
+Custom snippets are reusable components you create for your specific site needs. Unlike system snippets, these are fully editable and deletable.
+
+### Use Cases for Custom Snippets
+
+- **UI Components**: Product cards, banners, buttons
+- **Repeated Layouts**: Article previews, testimonials, pricing tables
+- **Reusable Blocks**: Call-to-action sections, social media embeds
+- **Conditional Content**: A/B test variations, personalized content blocks
+
+### Creating Custom Snippets
+
+**Via Tools**:
+```typescript
+template-create({
+  platformSlug: "fed-team",
+  siteId: 4605,
+  name: "product_card",
+  type: "custom_snippet",
+  body: `
+    <div class="product-card">
+      <img src="{{ product.image }}" alt="{{ product.name }}">
+      <h3>{{ product.name }}</h3>
+      <p>{{ product.description }}</p>
+      <span class="price">{{ product.price | money }}</span>
+    </div>
+  `
+})
+```
+
+**Via API**: `POST /api/admin/sites/{site_id}/templates`
+```json
+{
+  "type": "custom_snippet",
+  "name": "product_card",
+  "body": "<!-- Liquid code here -->"
+}
+```
+
+### Custom Snippet Example
+
+**Snippet Code** (`custom_snippets/product_card`):
+```liquid
+<div class="product-card">
+  <img src="{{ product.image }}" alt="{{ product.name }}">
+  <h3>{{ product.name }}</h3>
+  <p>{{ product.description }}</p>
+  <span class="price">{{ product.price | money }}</span>
+
+  {% if product.on_sale %}
+    <span class="badge sale">On Sale!</span>
+  {% endif %}
+</div>
+```
+
+**Usage in Page/Layout/Widget**:
+```liquid
+<!-- Loop through products -->
+{% for product in products %}
+  {% snippet 'product_card' with product %}
+{% endfor %}
+
+<!-- Or pass parameters -->
+{% snippet 'product_card', product: featured_product %}
+```
+
+### System vs Custom Snippets
+
+| Aspect | System Snippets | Custom Snippets |
+|--------|----------------|-----------------|
+| **API Endpoint** | `/templates/snippets` | `/templates/custom_snippets` |
+| **Source** | Modyo built-in | User-created |
+| **Editable** | ✅ Content can be customized | ✅ Fully editable |
+| **Deletable** | ❌ `deletable: false` | ✅ `deletable: true` |
+| **Purpose** | Site structure (header, footer, grids) | Reusable UI components |
+| **Examples** | `header`, `footer`, `full_grid`, `custom_widget` | `product_card`, `banner`, `cta_section` |
+| **Usage** | `{% snippet 'header' %}` | `{% snippet 'product_card' %}` |
+
+### Managing Custom Snippets
+
+**List custom snippets**:
+```typescript
+template-list-custom-snippets({
+  platformSlug: "fed-team",
+  siteId: 4605
+})
+```
+
+**Update custom snippet**:
+```typescript
+template-update({
+  platformSlug: "fed-team",
+  siteId: 4605,
+  templateId: 123,
+  template: { body: "<!-- Updated code -->" }
+})
+```
+
+**Delete custom snippet**:
+```typescript
+template-delete({
+  platformSlug: "fed-team",
+  siteId: 4605,
+  templateId: 123
+})
+```
+
+### Best Practices for Custom Snippets
+
+1. **Naming**: Use descriptive names (`product_card`, not `snippet1`)
+2. **Parameters**: Design snippets to accept parameters for flexibility
+3. **Documentation**: Add comments explaining expected parameters
+4. **Reusability**: Keep snippets focused on single responsibility
+5. **Testing**: Test snippets with various data inputs
+
+**Example with Documentation**:
+```liquid
+{%- comment -%}
+  Product Card Snippet
+
+  Parameters:
+    - product: Product object with name, image, price, description
+    - show_badge (optional): Boolean to show/hide sale badge
+
+  Usage:
+    {% snippet 'product_card', product: my_product, show_badge: true %}
+{%- endcomment -%}
+
+<div class="product-card">
+  <!-- Snippet code -->
+</div>
+```
+
+---
+
+## Snippet vs Widget
+
+Understanding the difference:
+
+| Feature | Snippet | Widget |
+|---------|---------|--------|
+| **Purpose** | Reusable Liquid template | Interactive component |
+| **Technology** | Liquid markup | HTML/CSS/JS (can be React/Vue/Angular) |
+| **Rendering** | Server-side (always) | Server-side or client-side |
+| **Positioning** | Included anywhere via `{% snippet %}` | Positioned in grid columns |
+| **Use Case** | Templates, layouts, common elements | Interactive features, micro frontends |
+| **Can contain** | Liquid code, HTML | Full JavaScript applications |
+| **Sync/Async** | N/A (always synchronous) | Configurable via `sync` parameter |
+
+---
+
+## Important Notes
+
+### 1. System Snippets are Read-Only
+
+Core snippets like `custom_widget`, grid snippets, etc. have `deletable: false`. These are maintained by Modyo and define core platform behavior.
+
+### 2. Snippet Rendering is Server-Side
+
+All snippets are rendered server-side by Modyo's Liquid engine before HTML is sent to browser. This is different from widgets which can load asynchronously.
+
+### 3. Grid Snippets Match grid_type
+
+The page's `grid_type` parameter determines which grid snippet is used:
+
+```typescript
+grid_type: "full_grid" → {% snippet 'full_grid' %}
+grid_type: "full_three_cols_grid" → {% snippet 'full_three_cols_grid' %}
+grid_type: "side_left_grid" → {% snippet 'side_left_grid' %}
+```
+
+### 4. Widget Snippet Handles Both Normal and CLI Widgets
+
+The `custom_widget` snippet works for:
+- Normal widgets (editable in Modyo)
+- CLI widgets (read_only, deployed via CLI)
+- Bundle format (`zip: false`)
+- Zip format (`zip: true`)
+
+The snippet checks `widget.sync` to determine rendering mode, regardless of widget type.
+
+---
+
+## Security: CSP Nonce
+
+Notice `{{ csp_nonce }}` throughout snippet code:
+
+```liquid
+<script nonce="{{csp_nonce}}">
+  // JavaScript code
+</script>
+```
+
+**Purpose**: Content Security Policy (CSP) nonce for inline scripts/styles
+**Behavior**: Modyo generates unique nonce per request
+**Why**: Prevents XSS attacks while allowing inline code
+
+---
+
+## Performance Implications
+
+### Synchronous Widgets (`widget.sync = true`)
+
+**Pros**:
+- Content appears immediately
+- No layout shift
+- Critical content visible instantly
+
+**Cons**:
+- Blocks page rendering
+- Slower Time to First Byte (TTFB)
+- All CSS/JS inline (larger HTML)
+
+### Asynchronous Widgets (`widget.sync = false`)
+
+**Pros**:
+- Faster page rendering
+- Better Core Web Vitals
+- Progressive enhancement
+- CSS loaded separately (cacheable)
+
+**Cons**:
+- Potential layout shift
+- Content appears after page load
+- Placeholder visible briefly
+
+---
+
+## Tools Integration
+
+When working with Modyo MCP tools:
+
+### Reading Snippets
+```typescript
+template-list-snippets({ platformSlug, siteId })
+// Returns all snippets
+
+template-get({ platformSlug, siteId, templateId })
+// Returns snippet with body code
+```
+
+### Modifying Snippets
+```typescript
+template-update({ platformSlug, siteId, templateId, template: { body } })
+// Update snippet code
+
+template-save({ platformSlug, siteId, templateId, body })
+// Save snippet body
+```
+
+### Creating Custom Snippets
+```typescript
+template-create({
+  platformSlug,
+  siteId,
+  name: "product_card",
+  type: "custom_snippet",
+  body: "<!-- Liquid code here -->"
+})
+```
+
+---