domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/specs/2026-03-12-form-followup-actions-design.md

@@ -0,0 +1,152 @@
+# Form Follow-Up: Success States & Action Triggers
+
+**Date:** 2026-03-12
+**Status:** Approved
+
+---
+
+## Problem
+
+The `[form]` shortcode stores submissions but provides no visible follow-up to the visitor and no automatic way to trigger a CMS Action after a submission. Admins know forms have built-in email/webhook support, but there is no bridge to the Actions pipeline and no client-side success UX.
+
+---
+
+## Solution Overview
+
+Three connected improvements:
+
+1. **Action auto-trigger on submission** - add an optional `actionSlug` field to form settings; the submission pipeline executes the named Action server-side after storing the entry.
+2. **Configurable visitor success UX** - add an optional `successRedirect` URL field; client redirects if set, otherwise fades the form out and shows `successMessage` inline.
+3. **Example page + tutorial** - a working public example and admin tutorial covering the full flow.
+
+---
+
+## Data Flow
+
+```
+[form] shortcode (public page)
+    ↓  visitor submits
+    ↓  site.js intercepts submit, POST /api/forms/submit/:slug
+    ↓  validate fields
+    ↓  store entry to collection
+    ↓  fire email action (if configured)
+    ↓  fire webhook action (if configured)
+    ↓  executeAction(actionSlug, entry.id)   ← NEW - service-to-service, no auth needed
+    ↓  return { success, message, redirect } ← redirect field is NEW
+Client:
+    if redirect  → window.location.href = redirect
+    else         → fade form out, show successMessage inline
+```
+
+---
+
+## Form Settings Changes
+
+Two new optional fields in each form's JSON (`content/forms/{slug}.json`):
+
+| Field | Type | Default | Purpose |
+|---|---|---|---|
+| `actionSlug` | `string \| null` | `null` | CMS Action slug to execute after submission |
+| `successRedirect` | `string \| null` | `null` | URL to redirect visitor on success |
+
+**Priority rule:** `successRedirect` takes precedence over `successMessage` if both are set.
+
+Existing fields unchanged: `successMessage`, `submitText`, `layout`, `honeypot`, `rateLimitPerMinute`, `actions.email`, `actions.webhook`.
+
+---
+
+## Admin UI Changes
+
+**Form editor - Settings tab:** two new fields added after the existing `successMessage` field:
+
+- **"Action on Submit"** - `<select>` populated from `GET /api/actions`. Options: blank (none) + each action's label and slug.
+- **"Success Redirect URL"** - text input (e.g. `/thank-you`). Helper text: *"Takes priority over the success message if set."*
+
+---
+
+## Server Changes
+
+**`server/routes/api/forms.js` - submission handler:**
+
+After the existing webhook step, add:
+
+```js
+// Execute CMS Action if configured
+if (formDef.actionSlug) {
+    try {
+        await executeAction(formDef.actionSlug, entry.id, { user: null });
+    } catch (err) {
+        console.warn(`[forms] Action "${formDef.actionSlug}" failed for form "${slug}":`, err.message);
+        // Non-fatal - submission already stored
+    }
+}
+```
+
+Return value gains a `redirect` field:
+
+```js
+return {
+    success: true,
+    message: formDef.settings?.successMessage || 'Thank you.',
+    redirect: formDef.settings?.successRedirect || null
+};
+```
+
+---
+
+## Client Changes
+
+**`public/js/site.js` - form submission handler:**
+
+Intercept `submit` on elements rendered by the `[form]` shortcode. On success response:
+
+- If `redirect` is set → `window.location.href = redirect`
+- Else → hide the form element, show `successMessage` in its place (simple fade, no library needed)
+
+On error → display validation/server errors inline beneath the relevant fields.
+
+---
+
+## Example Page
+
+**`content/pages/contact.md`** - updated to use:
+- `[form slug="enquiries"]` shortcode
+- The enquiries form configured with:
+  - Email notification to admin
+  - `actionSlug: "new-enquiry"`
+  - `successMessage: "Thanks - we'll be in touch shortly."`
+
+**Sample Action** - `new-enquiry` action with a single webhook step pointing to a placeholder URL, demonstrating the pattern.
+
+---
+
+## Tutorial (admin/js/templates/tutorials.html)
+
+New collapsible card: **"Form Follow-Up: Notifications & Actions"**
+
+Sections:
+1. Configuring email notification on a form
+2. Creating an Action with one or more steps
+3. Wiring the Action to the form via "Action on Submit"
+4. Choosing between inline success message and redirect
+5. Execution order: store → email → webhook → action
+
+---
+
+## Documentation (admin/js/templates/documentation.html)
+
+Short addition to the Forms section referencing the two new fields and pointing to the Actions section for step configuration.
+
+---
+
+## Files Modified
+
+| File | Change |
+|---|---|
+| `server/routes/api/forms.js` | Add action execution + redirect to response |
+| `admin/js/views/formEditor.js` | Add actionSlug + successRedirect fields to settings tab |
+| `public/js/site.js` | Handle form submit, success/redirect/error states |
+| `content/pages/contact.md` | Updated example using form + action |
+| `content/collections/actions/data.json` | Seed `new-enquiry` sample action |
+| `admin/js/templates/tutorials.html` | New tutorial card |
+| `admin/js/templates/documentation.html` | New docs entry under Forms |

package/docs/superpowers/specs/2026-03-12-page-editor-form-insert-and-per-page-theme-design.md

@@ -0,0 +1,115 @@
+# Page Editor: Form Insert & Per-Page Theme - Design
+
+**Date:** 2026-03-12
+
+## Overview
+
+Two additions to the page editor:
+
+1. **Insert Form** - a new entry in the Insert dropdown that embeds a form into page content via a server-side shortcode
+2. **Per-page theme** - an optional `theme` frontmatter field that overrides the global site theme for a single page
+
+---
+
+## Feature 1: Insert Form
+
+### Shortcode
+
+```
+[form slug="to-do"]
+[form slug="contact" title="Get in Touch"]
+```
+
+Optional `title` attribute overrides the form's own display title. Slug is required.
+
+### Server-side processing
+
+**File:** `server/services/markdown.js`
+
+- New `processFormBlocks()` function
+- Runs in the existing shortcode pipeline before `marked.parse()`, after `processDConfigBlocks()`
+- Reads `content/forms/{slug}.json`
+- If the form is not found, renders a visible error placeholder - no crash
+- Base64-encodes the form JSON and outputs:
+
+```html
+<div class="cms-form-embed" data-form-inline="BASE64"></div>
+```
+
+- If `title` attribute is provided, it overrides `form.title` in the encoded schema before encoding
+
+### Client-side hydration
+
+**File:** `public/js/site.js`
+
+- On DOM ready, find all `[data-form-inline]` elements
+- Decode the base64 schema
+- Call `F.render(el, blueprint, {}, settings)` - same call used by the admin preview
+
+### Admin insert UI
+
+**File:** `admin/js/lib/markdown-toolbar.js`
+
+- New "Form" entry in the Insert dropdown (alongside Collection, View, etc.)
+- Clicking opens a picker modal:
+  - Fetches available forms from `GET /api/forms`
+  - Lists form titles with their slugs
+  - Selecting a form inserts `[form slug="selected-slug"]` at the cursor position
+- No additional options at insert time (title override is manual if needed)
+
+---
+
+## Feature 2: Per-page Theme
+
+### Data model
+
+New optional field in page YAML frontmatter:
+
+```yaml
+theme: "ocean-dark"
+```
+
+Omitted or blank = use global `site.json` theme. No migration needed - absence is the default.
+
+### Renderer
+
+**File:** `server/services/renderer.js`
+
+- After reading page frontmatter, check `page.theme`
+- If set, substitute it in place of `site.theme` for `activeTheme` / `dommaTheme` / `customThemeClass` computation
+- Applies to the whole page (navbar, footer, content area)
+- No structural change - just a different source value for the existing theme variables
+
+### Admin UI
+
+**File:** `admin/js/templates/page-editor.html`
+
+- Add a "Theme" `<select>` in the Page Details tab
+- Options: blank "- Use site default -" plus all Domma themes:
+  - charcoal-dark, charcoal-light, ocean-dark, ocean-light, forest-dark, forest-light, sunset-dark, sunset-light, royal-dark, royal-light, lemon-dark, lemon-light, silver-dark, silver-light, grayve-dark, grayve-light
+
+**File:** `admin/js/views/page-editor.js` (or equivalent)
+
+- Read `page.theme` on load, set the select value (blank if absent)
+- Write `theme` field on save (omit the key entirely if blank, to keep frontmatter clean)
+
+---
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `server/services/markdown.js` | Add `processFormBlocks()`, call in pipeline |
+| `public/js/site.js` | Hydrate `[data-form-inline]` embeds on DOM ready |
+| `admin/js/lib/markdown-toolbar.js` | Add Form entry to Insert dropdown + picker modal |
+| `server/services/renderer.js` | Check `page.theme` before falling back to `site.theme` |
+| `admin/js/templates/page-editor.html` | Add Theme select in Page Details tab |
+| `admin/js/views/page-editor.js` | Read/write `theme` field on load/save |
+
+---
+
+## Out of Scope
+
+- Form SSR (full `<form>` HTML generation) - client hydration from inline schema is sufficient
+- Per-page overrides beyond theme - YAGNI
+- Theme preview in admin - out of scope for now

package/docs/superpowers/specs/2026-03-17-nav-hidden-items-design.md

@@ -0,0 +1,85 @@
+# Nav Hidden Items - Design Spec
+
+**Date:** 2026-03-17
+**Status:** Approved
+
+## Overview
+
+Add a "hidden" toggle to the navigation editor so menu items and footer links can be suppressed from the public site without being deleted. Hidden items are preserved in `navigation.json` and `site.json` for easy re-enabling, but are stripped server-side before the public page receives them.
+
+## Scope
+
+- Main menu items (including children)
+- Footer links (`site.footer.links`)
+
+## Data Model
+
+Both `navigation.json` items and `site.json` footer links gain an optional `"hidden": true` flag:
+
+```json
+{ "text": "About", "url": "/about", "icon": "info", "hidden": true }
+```
+
+- Absent key = visible (backwards compatible, no migration needed)
+- Children can be hidden independently of their parent
+- If a parent item is hidden, the **entire entry is stripped** from the public output, including all its children - child `hidden` flags are irrelevant when the parent is hidden
+- The admin GET/PUT API is untouched - it always works with raw data, hidden flags included
+
+## Admin Editor UI
+
+### Saving behaviour
+
+The hidden toggle is **UI-state only** - it updates the in-memory `flatItems` array but does not auto-save. The user must press the existing Save button to persist. On save failure, the existing error toast fires; no optimistic revert is needed because nothing has been written to disk.
+
+### Per-row toggle button (menu items)
+
+Each `nav-item-row` gains a second action button using the `eye-off` icon (already registered in the Domma icon set), placed **to the left** of the existing trash button. Clicking it:
+
+1. Flips the item's `hidden` state in the `flatItems` array
+2. Calls `renderItems()` to re-render the full list
+
+`renderItems()` writes a `data-hidden="true|false"` attribute on the toggle button from the model. `syncFromDom()` reads `$(this).find('.btn-toggle-hidden').data('hidden') === 'true'` (string comparison - DOM data attributes are strings) to populate `hidden` on each flat item before a save.
+
+### Per-row toggle button (footer links)
+
+Footer link rows receive identical treatment: an `eye-off` toggle button to the left of the trash button. `renderFooterLinks()` writes `data-hidden` from the model. `syncFooterFromDom()` reads it to populate `hidden` on each footer link before a save.
+
+### Visual treatment
+
+Hidden rows receive a `.nav-item-row--hidden` CSS class (in `admin/css/admin.css`):
+
+- Row is dimmed (e.g. `opacity: 0.45`)
+- Label input text has a strikethrough (e.g. `text-decoration: line-through`)
+
+The eye-off button itself gets an `.active` class when the item is hidden, so it appears pressed/highlighted.
+
+### Column header
+
+The `nav-items-header` in `navigation.html` gains a narrow column label (e.g. "Vis.") above the new toggle button column to keep the layout aligned.
+
+## Server-Side Filtering
+
+In `server/services/renderer.js`, before serialising `__CMS_NAV__` into the page:
+
+1. Filter `nav.items` - remove entries where `hidden === true` (this removes the parent and all its children)
+2. For each remaining parent item, filter its `items` children - remove children where `hidden === true`
+3. Filter `site.footer.links` - remove entries where `hidden === true`
+
+No changes to any API route. Filtering happens at render time only.
+
+**Note:** The `[footer]` tag in Markdown is a card sub-tag only (it renders a `<div class="card-footer">`). It has no connection to `site.footer.links` and is unaffected by this change.
+
+## Files Affected
+
+| File | Change |
+|------|--------|
+| `admin/js/views/navigation.js` | `flatItems` gains `hidden` field; `syncFromDom`, `nestItems`, `renderItems` updated; footer equivalents updated |
+| `admin/js/templates/navigation.html` | Column header updated for new button column |
+| `admin/css/admin.css` | `.nav-item-row--hidden` style added |
+| `server/services/renderer.js` | Filter hidden items/links before injecting `__CMS_NAV__` |
+
+## Out of Scope
+
+- Hiding items per-role or per-user
+- Scheduled visibility (show/hide on a date)
+- Any `[footer]` or `[header]` shortcode behaviour (unrelated to `site.footer.links`)

package/docs/superpowers/specs/2026-03-19-accordion-insert-design.md

@@ -0,0 +1,175 @@
+# Accordion Insert - Design Spec
+
+**Date:** 2026-03-19
+**Status:** Approved
+
+## Overview
+
+Add an "Accordion" entry to the Page Editor Insert dropdown. The insert dialog supports two modes:
+- **Static** - user defines items manually (titles + placeholder body content)
+- **Collection** - bind to a CMS collection; entries are rendered as accordion items using nominated fields
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `server/services/markdown.js` | Add `display="accordion"` to `processCollectionBlocks()` |
+| `admin/js/lib/markdown-toolbar.js` | Register icon, add action, export `onAccordion` |
+| `admin/js/views/page-editor.js` | Implement `toolbar.onAccordion(...)` dialog |
+
+---
+
+## Section 1 - Server-side (`markdown.js`)
+
+### New helper: `renderCollectionAccordion`
+
+```
+renderCollectionAccordion(entries, titleField, bodyField, multiple, emptyMsg)
+```
+
+- Produces identical HTML to `processAccordionBlocks()` so existing accordion CSS/JS handles it with no extra work
+- Wraps output in `<div class="accordion"[ data-multi="true"]>`
+- Each entry → `<div class="accordion-item">`:
+  - Header: `<h3 class="accordion-header"><button class="accordion-button" type="button">{title}<span class="accordion-icon" data-icon="chevron-down"></span></button></h3>`
+  - Body: `<div class="accordion-body"><div class="accordion-content">{bodyHtml}</div></div>`
+- `titleField` - entry field used as header text; falls back to entry `id` if field is absent
+- `bodyField` - entry field rendered as body content (escaped text); falls back to empty string
+- `multiple` - `true` adds `data-multi="true"` on wrapper
+- Empty state: same `dm-collection-display dm-collection-empty` pattern as other display modes
+
+### Change to `processCollectionBlocks`
+
+Add a new branch alongside `cards`, `list`, `block`:
+
+```js
+} else if (display === 'accordion') {
+    const titleField = attrs['title-field'] || 'title';
+    const bodyField  = attrs['body-field']  || 'description';
+    const multiple   = attrs.multiple === 'true';
+    replacement = renderCollectionAccordion(entries, titleField, bodyField, multiple, emptyMsg);
+}
+```
+
+### Shortcode signature
+
+```
+[collection slug="faq" display="accordion" title-field="title" body-field="description" limit="10" multiple="true" /]
+```
+
+All attributes except `slug` and `display` are optional.
+
+---
+
+## Section 2 - Toolbar (`markdown-toolbar.js`)
+
+### New icon: `accordion-insert`
+
+Register a stacked-chevrons SVG icon (visually distinct from the `layout-list` tabs icon).
+
+### Changes to `executeAction`
+
+Add `else if (action === 'accordion')` branch:
+- If `handlers.accordion` is set, delegate to it
+- Fallback: insert a 2-item static snippet directly
+
+```
+[accordion]
+[item title="Item 1"]Content here.[/item]
+[item title="Item 2"]Content here.[/item]
+[/accordion]
+```
+
+### Changes to `buttons` array (Insert dropdown)
+
+Add after the Tabs entry:
+```js
+{label: 'Accordion', icon: 'accordion-insert', action: 'accordion'},
+```
+
+### Changes to `handlers` object and `createToolbar` return
+
+- Add `accordion: null` to handlers
+- Export `onAccordion(cb) { handlers.accordion = cb; }` from the returned object
+
+---
+
+## Section 3 - Dialog (`page-editor.js`)
+
+### Handler: `toolbar.onAccordion(async (ta) => { ... })`
+
+Follows the same light-DOM modal pattern as `onTabs` and `onCollection`.
+
+### Dialog structure
+
+```
+┌─ Insert Accordion ────────────────────┐
+│  [Static]  [Collection]               │  ← segmented toggle
+│                                       │
+│  ── Static panel (default) ────────── │
+│  Item 1: [___________________]        │
+│  Item 2: [___________________]        │
+│  [+ Add Item]                         │
+│  □ Allow multiple open                │
+│                                       │
+│  ── Collection panel (hidden) ─────── │
+│  Collection:  [select ▾]              │
+│  Title field: [select ▾]              │
+│  Body field:  [select ▾]              │
+│  Limit:       [      ]  (optional)    │
+│  □ Allow multiple open                │
+│                                       │
+│                   [Insert Accordion]  │
+└───────────────────────────────────────┘
+```
+
+### Mode toggle behaviour
+
+- Two buttons styled as a segmented control (`btn-group` or inline toggle)
+- Clicking "Collection" hides the static panel and shows the collection panel, and vice versa
+- Active mode state is a local variable used by the Insert button
+
+### Static panel behaviour
+
+- Starts with two item rows, each containing a single text input (placeholder: `Item title`)
+- "Add Item" appends a new row (no maximum enforced)
+- "Allow multiple open" checkbox, unchecked by default
+
+### Collection panel behaviour
+
+- Collection `<select>` populated from `api.collections.list()` (fetched once on dialog open)
+- On collection change: call `api.collections.get(slug)`, extract `schema.fields[]`, populate both field selects
+  - Title field: pre-select field named `title` if present; otherwise first field; label shows field name
+  - Body field: pre-select field named `description` if present; otherwise second field (or `- none -`)
+- Limit `<input type="number">`, optional, placeholder "All"
+- "Allow multiple open" checkbox, unchecked by default
+
+### Snippet generation (Insert button)
+
+**Static mode:**
+```
+[accordion multiple="true"]
+[item title="Item 1"]Content here.[/item]
+[item title="Item 2"]Content here.[/item]
+[/accordion]
+```
+- Skips blank-title rows
+- Falls back to "Item N" if title input is empty
+
+**Collection mode:**
+```
+[collection slug="faq" display="accordion" title-field="title" body-field="description" /]
+```
+- Appends `limit="N"` if limit input is non-empty
+- Appends `multiple="true"` if checkbox is checked
+
+---
+
+## Edge Cases
+
+| Scenario | Behaviour |
+|----------|-----------|
+| No collections exist | Collection select shows "No collections found"; Insert disabled |
+| Schema fetch fails | Field selects show single option "- unknown -"; Insert still enabled |
+| Static mode, all titles blank | Inserts snippet with "Item 1", "Item 2" fallback labels |
+| Collection with no fields | Field selects populated with `- none -`; shortcode emitted without `title-field`/`body-field` |
+| `body-field` on server but field missing on entry | Renders empty body gracefully (no crash) |

package/docs/superpowers/specs/2026-03-25-static-block-shortcode-design.md

@@ -0,0 +1,153 @@
+# Static Block Shortcode - Design Spec
+
+## Context
+
+Blocks in Domma CMS are reusable HTML templates (`content/blocks/*.html`) with `{{placeholder}}` substitution. Today,
+blocks can only be used via `[collection slug="..." display="block" block="post-card" /]`, which fetches entries from a
+Collection at render time.
+
+**Problem**: For one-off content - a single featured post card, a contact highlight, a testimonial - creating an entire
+Collection with one entry is overkill. Users need a way to use block templates with static, inline data entered directly
+in the page editor.
+
+**Solution**: A new `[block]` shortcode that takes a block template name and inline data as attributes, rendered
+server-side using the existing block template infrastructure. A new "Block" item in the page editor's Insert menu
+provides a guided modal with live preview.
+
+---
+
+## Shortcode Syntax
+
+```
+[block template="post-card" title="My Post" author="Jane Doe" excerpt="A quick summary" /]
+```
+
+- **Self-closing** (like `[collection ... /]`)
+- `template` is the only reserved attribute - everything else is data for `{{placeholder}}` substitution
+- Attribute values are HTML-escaped during rendering (reuses existing `escapeHtmlText`)
+- Missing placeholders render as empty strings (consistent with collection block behaviour)
+
+---
+
+## Server-Side Processing
+
+### New function: `processStaticBlocks(content)`
+
+**File**: `server/services/markdown.js`
+
+**Regex**: Matches `[block template="..." key="value" ... /]` - same multi-line attribute parsing approach used by
+`processTextBlocks`.
+
+**Logic**:
+
+1. Extract `template` attribute (required - skip if missing)
+2. Collect all other attributes as key-value data pairs
+3. Load block template via existing `loadBlockTemplate(templateName)` (line 52)
+4. Run `{{placeholder}}` replacement: `template.replace(/\{\{([\w_]+)\}\}/g, ...)` using the attribute data (same regex
+   as `renderCollectionBlocks` line 73)
+5. HTML-escape all values via existing `escapeHtmlText()`
+6. Wrap output in `<div class="dm-static-block">` (distinct from `dm-collection-blocks` since this is a single item, not
+   a collection grid)
+7. On error (template not found), output a visible error comment in dev, empty string in production
+
+**Processing order**: Runs after `processCollectionBlocks` and `processViewBlocks`, before `processDConfigBlocks`.
+Insert at line ~1621 in the pipeline.
+
+### Reused functions (no changes needed)
+
+- `loadBlockTemplate(name)` - `markdown.js:52`
+- `escapeHtmlText(str)` - already used throughout
+- `escapeAttr(str)` - for attribute parsing
+
+---
+
+## Insert Menu Integration
+
+### Toolbar Registration
+
+**File**: `admin/js/lib/markdown-toolbar.js`
+
+1. Add new item to the Insert dropdown (line 937-955), between "Badge" and "Button" (alphabetical):
+   ```js
+   {label: 'Block', icon: 'layout', action: 'block'},
+   ```
+
+2. Add handler registration method alongside existing ones (near line 1135):
+   ```js
+   onBlock(cb) { handlers.block = cb; },
+   ```
+
+3. Add `'block'` case to `executeAction()` that calls the registered handler.
+
+### Modal Handler
+
+**File**: `admin/js/views/page-editor.js`
+
+Register via `toolbar.onBlock(async (ta) => { ... })`.
+
+**Modal layout**: Two-pane - inputs on left, live preview on right.
+
+**Flow**:
+
+1. Fetch block list via `api.blocks.list()`
+2. Show template picker dropdown
+3. On template selection:
+    - Fetch template HTML via `api.blocks.get(name)`
+    - Extract placeholders using same regex as block-editor: `/\{\{([\w_]+)\}\}/g`
+    - Filter out meta placeholders (`_id`, `_createdAt`, `_updatedAt`) - not relevant for static data
+    - Generate labelled input fields for each placeholder
+4. Live preview panel:
+    - On input change, run `{{placeholder}}` replacement client-side with current field values
+    - Display rendered HTML preview (same approach as `block-editor.js` line 202-245)
+5. **Insert** button:
+    - Build shortcode string: `[block template="name" field1="val1" field2="val2" /]`
+    - Escape double quotes in values (replace `"` with `&quot;` in attribute values)
+    - Call `insertAtCursor(ta, shortcode)`
+    - Close modal, dispatch `input` event
+
+**Placeholder-to-label conversion**: `featured_image` → `Featured Image` (split on `_`, capitalise each word) - same
+pattern as block-editor.js `refreshSampleForm`.
+
+---
+
+## CSS
+
+No new CSS required. The `<div class="dm-static-block">` wrapper is intentionally minimal - the block template itself
+contains all styling (using Domma card classes, etc.). This is consistent with how collection blocks work.
+
+---
+
+## Documentation
+
+**File**: `docs/markdown-shortcodes.md`
+
+Add a new section for the `[block]` shortcode with syntax, attributes, and examples. Place it near the `[collection]`
+documentation since they share the block template concept.
+
+---
+
+## Files Modified
+
+| File                               | Change                                                                               |
+|------------------------------------|--------------------------------------------------------------------------------------|
+| `server/services/markdown.js`      | Add `processStaticBlocks()`, add to pipeline                                         |
+| `admin/js/lib/markdown-toolbar.js` | Add "Block" to Insert dropdown, `onBlock` handler registration, `executeAction` case |
+| `admin/js/views/page-editor.js`    | Add `toolbar.onBlock()` modal handler with live preview                              |
+| `docs/markdown-shortcodes.md`      | Document `[block]` shortcode                                                         |
+
+**No new files created. No new APIs. No new CSS files.**
+
+---
+
+## Verification
+
+1. **Server rendering**: Create a test page with
+   `[block template="contact-card" full_name="Jane Doe" phone_number="555-1234" email_address="jane@example.com" /]` and
+   verify it renders the contact-card template with substituted values
+2. **Missing template**: Use a non-existent template name and verify graceful handling (no crash)
+3. **Missing placeholders**: Omit some fields and verify they render as empty strings
+4. **XSS prevention**: Include `<script>alert('xss')</script>` in a field value and verify it's escaped
+5. **Insert modal**: Open page editor → Insert → Block → select a template → verify fields appear → fill in data →
+   verify live preview → click Insert → verify shortcode inserted in editor
+6. **Live preview**: Confirm the editor's split-pane preview renders the block correctly after insertion
+7. **Existing blocks unaffected**: Verify `[collection ... display="block" ...]` still works as before