domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/specs/2026-04-17-components-area-design.md

@@ -0,0 +1,368 @@
+# Components Area - Design Spec
+
+**Date:** 2026-04-17
+**Status:** Draft - ready for implementation planning
+**Scope:** New "Components" feature under the admin **Data** section, alongside Collections, Forms, Views, Actions, and Blocks.
+
+## 1. Intent
+
+Add a first-class **Components** area to Domma CMS. Authors can **collect, edit, and inject** Domma components - Vue-style Custom Elements built with Domma's component factory (`Domma.component(tagName, {…})`) - into public pages.
+
+Unlike **Blocks** (static HTML + `{{placeholder}}` substitution), Components ship executable JavaScript: template + reactive `data()` + computed properties + methods + scoped styles + lifecycle hooks. They render on the public site as real Custom Elements with Shadow DOM isolation.
+
+### Constraints and decisions
+
+| Decision | Choice |
+|---|---|
+| Primary surface | Public site. Admin-side consumption is out of scope for v1 but the design must not preclude it. |
+| Authoring model | Developer-level editor (admin authors write the full component) + seeded shipped library. |
+| On-disk shape | SFC-style single file (`.dmc`) with `<template>`, `<props>`, `<script>`, `<style>` blocks. |
+| Page injection | Shortcode (`[component name="x" …]`) is the page-editor default; raw custom-element tags (`<dm-x …>`) are also accepted. |
+| Runtime loading | Per-page. Renderer scans used components; injects only the scripts needed. |
+| Insertion UX | Slideover with gallery → props form → live iframe preview → insert. |
+| Permissions | New `components` resource in `permissionRegistry`. Super-admin default; loosenable via Roles UI. |
+
+## 2. File format: `.dmc`
+
+One `.dmc` file per component at `content/components/<name>.dmc`. Companion `<name>.meta.json` holds `{ bundled: true }` for shipped starters (same pattern as blocks).
+
+```
+<template>
+  <div class="dm-counter">
+    <div class="value">{{count}}</div>
+    <button data-action="inc">+</button>
+    <button data-action="dec">-</button>
+    {{#if showReset}}<button data-action="reset">Reset</button>{{/if}}
+  </div>
+</template>
+
+<props>
+{
+  "initial":   { "type": "number",  "default": 0, "label": "Initial value" },
+  "step":      { "type": "number",  "default": 1, "label": "Step size" },
+  "showReset": { "type": "boolean", "default": false, "label": "Show reset button" }
+}
+</props>
+
+<script>
+export default {
+  data() { return { count: this.props.initial }; },
+  methods: {
+    inc()   { this.set({ count: this.data.count + this.props.step }); },
+    dec()   { this.set({ count: this.data.count - this.props.step }); },
+    reset() { this.set({ count: this.props.initial }); }
+  },
+  onMount() {
+    this.el.addEventListener('click', e => {
+      const action = e.target.dataset.action;
+      if (action && this[action]) this[action]();
+    });
+  }
+};
+</script>
+
+<style>
+.dm-counter .value { font-size: 2rem; font-weight: 700; }
+.dm-counter button { margin-right: .25rem; }
+</style>
+```
+
+### Block semantics
+
+| Block | Required | Purpose |
+|---|---|---|
+| `<template>` | yes | Mustache-style template string passed to `Domma.component`. |
+| `<props>` | yes | Machine-readable JSON props schema. Drives the page-editor props form and validation. |
+| `<script>` | yes | ES module with `export default { data, computed, methods, lifecycle hooks }`. Runtime behaviour. |
+| `<style>` | no | CSS injected into the Custom Element's Shadow DOM. |
+
+`<props>` is deliberately separate from any `props:` key inside `<script>`. **`<props>` is the UI contract; `<script>` is the runtime.** If both are present and diverge, compilation emits a warning; `<props>` wins for the editor UI, `<script>` for runtime coercion. Authors are expected to keep them aligned; a future v1.1 compiler macro can generate one from the other.
+
+### Name validation
+
+Component name regex: `^[a-z][a-z0-9-]*$`. Registered Custom Element tag is always `dm-<name>` - enforces the hyphen required by Custom Elements and reserves a single predictable namespace.
+
+## 3. Server pipeline
+
+Two new files carry the server work:
+
+- **`server/services/components.js`** - file I/O, compiler, cache, plugin hook wiring.
+- **`server/routes/api/components.js`** - HTTP surface.
+
+### 3.1 Compiler
+
+`compileComponent(source, name) → { js, errors }`:
+
+1. **Split blocks** via a single tolerant regex pass. Each of the four block tags is matched with `/<(template|props|script|style)>([\s\S]*?)<\/\1>/g`. A full HTML parser is unwarranted - files are admin-authored and small.
+2. **Validate `<props>` JSON.** Must parse; must be an object; each entry must declare `type ∈ {string, number, boolean, array, object}`.
+3. **Emit a JS module.** The `<script>` body is transformed by stripping its `export default` keyword and capturing the remaining object expression - `export default { … }` becomes `const definition = { … }`. This keeps `<script>` readable by a JS-aware editor (LSP/syntax highlighting) while allowing the compiler to produce a self-contained module that registers the component directly, with no external imports:
+
+    ```js
+    const template = `…`;        // <template> body
+    const style    = `…`;        // <style> body, or empty
+    const props    = { … };      // parsed <props> JSON
+    const definition = { … };    // <script> body with `export default` stripped
+
+    Domma.component('dm-<name>', { template, style, props, ...definition });
+    ```
+
+Compile errors are structured:
+
+```js
+{ type: 'MISSING_BLOCK' | 'INVALID_PROPS_JSON' | 'SCRIPT_SYNTAX',
+  message: '…', line?: number, column?: number }
+```
+
+### 3.2 Caching
+
+Compiled output is held in an in-memory `Map` keyed by `name`, with entry `{ js, mtime }`. `saveComponent()` invalidates the entry for that name; `deleteComponent()` removes it. No disk cache.
+
+### 3.3 API surface
+
+Mirrors `/api/blocks` closely.
+
+| Method | Route | Auth | Purpose |
+|---|---|---|---|
+| GET | `/api/components` | `components.read` | List: `[{name, size, updatedAt, bundled, props}]`. |
+| GET | `/api/components/:name` | `components.read` | Raw `.dmc` source + parsed `props`. |
+| GET | `/api/components/:name.js` | **none (public)** | Compiled JS module. Served with `Cache-Control` and a content hash. |
+| POST | `/api/components/compile` | `components.update` | Transient compile of a source body. Body: `{ source, name }`. Returns `{ js, errors }`. Used by the editor for live-preview compilation without touching disk. |
+| GET | `/api/components/:name/export` | `components.read` | Download as `.dmcomponent.json` bundle. |
+| POST | `/api/components/import` | `components.update` | Import bundle. 409 on collision unless `overwrite: true`. |
+| PUT | `/api/components/:name` | `components.update` | Upsert. Body: `{ source, bundled }`. **Compile runs before write**; malformed sources never reach disk. |
+| DELETE | `/api/components/:name` | `components.delete` | Delete `.dmc` + companion `.meta.json`. |
+
+Admin-side `api.js` helpers wrap these as `api.components.{list, get, compile, put, delete, exportBundle, importBundle}`. The JS method names differ from route verbs intentionally, matching the existing `api.blocks.*` convention.
+
+`.dmcomponent.json` export bundle shape (format version 1):
+
+```js
+{ format: 1, name: 'counter', source: '<full .dmc source>', bundled: false }
+```
+
+### 3.4 Plugin hook
+
+One new hook in `server/services/hooks.js`: `registerComponent({ name, source })`. Plugins can bundle `.dmc` sources that compile on startup and appear in the library as read-only entries (the list API flags them with `bundled: true, source: 'plugin'`).
+
+## 4. Renderer integration
+
+### 4.1 Scan pass (added to `server/services/markdown.js`)
+
+A new processor `collectComponents(markdown)` runs after the existing shortcode passes. It does two jobs:
+
+1. Rewrite `[component name="x" attr="y" /]` shortcodes to `<dm-x attr="y">…</dm-x>` tags (attribute flattening identical to the existing `[block]` and `[form]` processors).
+2. Collect every `<dm-([a-z][a-z0-9-]*)` token encountered in the source into a de-duplicated `Set`.
+
+The `Set` is attached to the page object as `page._usedComponents` for the renderer.
+
+### 4.2 Sanitiser config
+
+Props become kebab-case HTML attributes on the custom element (`<dm-counter initial="5" show-reset="true">`). The sanitiser must allow:
+
+1. **Tags:** the `dm-*` tag family. Preferred: wildcard via `ADD_TAGS: ['dm-*']` **if DOMPurify supports it**. If not, the components service exposes `getRegisteredTagNames()` and the sanitiser config is hydrated from it at startup (and invalidated on create/delete).
+2. **Attributes on those tags:** any attribute, because prop names are author-defined and enumerating them at render time has no security benefit. The strategy is a custom `uponSanitizeAttribute` hook that **unconditionally permits attributes whose parent element matches `/^dm-[a-z0-9-]+$/`**, while leaving attribute sanitisation on all other tags untouched. This is safe because a custom element attribute cannot execute JavaScript on its own - `on*` handlers and `javascript:` URLs are still stripped by the hook's default pass for any tag.
+
+Both points are flagged as implementation-time verifications (DOMPurify capability checks). Custom-element tags themselves are HTML-safe - the browser will not execute anything until a matching class is `customElements.define`'d - so the allowlist does not open a fresh XSS surface.
+
+### 4.3 Script injection (in `server/services/renderer.js`)
+
+For each name in `page._usedComponents`, the renderer emits:
+
+```html
+<script type="module" src="/api/components/<name>.js"></script>
+```
+
+These scripts are concatenated into the existing `bodyEndInject` slot, in this order:
+
+1. `domma.min.js` (existing)
+2. `site.js` - guarantees `window.Domma.component` is defined (existing)
+3. **Component scripts** (new)
+4. Plugin body-end snippets (existing)
+
+### 4.4 Missing-component graceful degradation
+
+If a page references a component whose `.dmc` no longer exists:
+
+- `/api/components/<name>.js` returns 404.
+- The corresponding `<dm-name>` tag remains inert in the DOM (browser doesn't upgrade an unknown custom element).
+- **Public pages still render cleanly.** The page editor's preview shows an inline warning banner listing unresolved component names.
+
+### 4.5 Flash-of-unrendered-custom-element
+
+Custom elements upgrade after their defining script runs (deferred module loading introduces a small delay). A single CSS rule in `public/css/site.css` mitigates flash for above-the-fold uses:
+
+```css
+:not(:defined) { visibility: hidden; }
+```
+
+## 5. Admin UI
+
+### 5.1 Sidebar entry
+
+Under the **Data** heading, immediately after **Blocks**:
+
+```js
+{ id: 'components', text: 'Components', icon: 'puzzle', url: '#/components',
+  section: '#/components', badge: badge(counts.components) }
+```
+
+Icon `puzzle` registered via `I.register` on first mount (same pattern as `blocks.js`). Visibility gated by `components.read`.
+
+### 5.2 List view - `admin/js/views/components.js`
+
+Route `#/components`. Table columns: **Name / Props / Size / Updated / Actions**. The **Props** column shows a compact pill list of declared prop names (from the parsed `<props>` block). Top bar: **New Component**, **Import**. Per-row actions: **Edit**, **Export**, **Delete**.
+
+Pattern follows `admin/js/views/blocks.js` nearly line-for-line.
+
+### 5.3 Component editor - `admin/js/views/component-editor.js`
+
+Route `#/components/edit/:name` (and `#/components/new` for creation). Full-page view. Layout:
+
+- **Header bar:** name, Custom Element tag preview (`<dm-foo>`), Export button, Bundled toggle, Save button.
+- **Left pane:** tabbed code editor with four tabs matching the four SFC blocks (`<template>` / `<props>` / `<script>` / `<style>`). Each tab reuses the block editor's primitives: line numbers, cursor readout, tab-key indent, undo/redo toolbar.
+- **Right pane:** live iframe preview (see section 6) driven by an auto-generated "Preview props" panel below it. Props panel inputs are typed by the `<props>` JSON.
+- **Status bar:** compile indicator. Green + line count when OK; red + expandable error when not. Save is disabled while compile is failing.
+
+Debounced recompile and iframe remount at ~300 ms since last keystroke. The editor **posts the draft source to `POST /api/components/compile`** rather than compiling client-side - this keeps the compiler single-sourced on the server and guarantees the preview uses the exact same module the public site would serve on save. Response shape is the same `{ js, errors }` the `PUT` endpoint validates against.
+
+### 5.4 Insertion flow - slideover in the page editor
+
+A new toolbar button **Insert Component** (alongside Insert Block / Insert Form) opens a Domma slideover (`size="lg"`, `position="right"`). Slideover is preferred over modal because:
+
+- Page context remains visible behind the panel.
+- The gallery + props form + preview fit comfortably side-by-side.
+- Multi-stage flow (pick → configure → preview → insert) suits a persistent panel.
+
+Stages inside the slideover:
+
+1. **Gallery.** Card grid; each card shows a thumbnail (auto-generated screenshot of the default-props preview iframe, cached per component mtime) + name + short description.
+2. **Props form.** After selection, a `F.create()` form is rendered from the `<props>` JSON blueprint.
+3. **Preview.** An iframe instance (same preview bootstrap as the editor) remounts on prop changes.
+4. **Insert.** On confirm, the shortcode form `[component name="<x>" attr="y" /]` is inserted at the cursor. An overflow menu offers "Insert as raw tag" for power users.
+
+Caveat: `E.slideover()` may share the `E.modal().setContent()` gotcha (HTML stripped via `textContent`). The iframe is a single DOM node so the light-DOM append pattern (`.element.appendChild(iframe)`) is the safe path. Implementation must verify this behaviour.
+
+## 6. Preview sandbox
+
+Admin-authored JS runs in both previews (editor + insertion slideover). A buggy `onMount()` or runaway `setInterval()` must not brick the admin session. Solution: **iframe sandbox, same-origin, with `postMessage` protocol.**
+
+### 6.1 Bootstrap file
+
+A single static document at `admin/preview/component-preview.html`:
+
+- Loads Domma CSS + JS (DOMPurify is **not** needed here - the iframe runs only admin-authored, pre-compiled modules; there is no untrusted HTML to sanitise inside the preview surface).
+- Contains a `#mount` div.
+- Listens for `postMessage` from the parent admin window; mounts the compiled component with the supplied tag name and props.
+- Posts ready/error/resize events back.
+
+### 6.2 Protocol
+
+| Direction | Message | Payload |
+|---|---|---|
+| admin → iframe | `mount` | `{ compiledJs, tagName, props }` |
+| admin → iframe | `updateProps` | `{ props }` - surgical attribute update, no remount |
+| admin → iframe | `remount` | - triggered by template/script/style edits |
+| iframe → admin | `ready` | `{ height }` |
+| iframe → admin | `error` | `{ message, stack, line?, col? }` |
+| iframe → admin | `resize` | `{ height }` |
+
+### 6.3 Safety properties
+
+- Runaway timers and memory leaks die with the iframe on the next remount.
+- Navigation attempts (`window.location = …`) navigate the **iframe**, not the admin.
+- Uncaught exceptions inside the component surface as structured `error` messages, not as admin-level errors.
+- Same-origin is deliberate: we need convenient `postMessage` and DOM access for auto-sizing. `sandbox="allow-scripts"` is not used because it would complicate communication without adding protection against super-admin-authored code, which we trust at the boundary.
+
+### 6.4 Auto-sizing
+
+The iframe `ResizeObserver`s its own body and posts `resize` height back. The admin container uses the posted height directly so tall components (e.g., carousels) are not clipped.
+
+## 7. Permissions
+
+New `components` resource in `server/services/permissionRegistry.js`:
+
+```js
+components: {
+  read:   ['admin', 'super-admin'],
+  create: ['super-admin'],
+  update: ['super-admin'],
+  delete: ['super-admin']
+}
+```
+
+- Route guards use `requirePermission('components', 'read'|'create'|'update'|'delete')`.
+- Sidebar entry and page-editor Insert Component button gate on `components.read`.
+- `/api/components/:name.js` is public (no auth) - it's static output served to every page visitor.
+- Because permissions live in the registry rather than being hard-coded, future roles can be granted component authoring via the Roles UI without a code change.
+
+## 8. Seeded starter library
+
+Five components seeded on first run by `seedDefaultComponents()` (same pattern as `seedDefaultBlocks()` - never overwrites existing files). Each ships with `bundled: true` in its `.meta.json`.
+
+| Name | Demonstrates |
+|---|---|
+| `counter` | Minimal stateful component - data, methods, template bindings. |
+| `copy-button` | One-shot action - clipboard API, computed, transient state. |
+| `reveal-panel` | Progressive disclosure - boolean state, `{{#if}}` structural binding, default slot projection. |
+| `testimonial-card` | Pure-presentational with rich props (quote, author, avatar). |
+| `countdown-timer` | Lifecycle - `onMount` / `onUnmount` with `setInterval` cleanup. |
+
+These collectively cover every meaningful shape of component (stateful, side-effecting, props-only, lifecycle) and double as living documentation.
+
+The seed names (`counter`, `copy-button`, `reveal-panel`, `testimonial-card`, `countdown-timer`) are deliberately distinct from existing files in `content/blocks/` (which currently holds `contact-info`, `contact-card`, `cta-banner`, `enquiry-card`, `feedback-card`, `note-card`, `todo-item`) - even though the namespaces are separate on disk, keeping the human-facing names unambiguous avoids documentation confusion.
+
+## 9. YAGNI - explicitly out of scope for v1
+
+- Component-to-component composition (`<dm-foo>` using `<dm-bar>` internally). Technically supported by the factory; no dedicated UI or docs until demand surfaces.
+- Named slots in the props schema. Default slot (children) works naturally via Custom Elements.
+- Scoped-styles flag. Component `<style>` already lives in Shadow DOM via the factory - encapsulation is automatic.
+- TypeScript / JSDoc validation of `<script>`. Plain JS; trust model is the admin boundary.
+- Visual `<props>` schema builder. Hand-written JSON for v1; builder deferred to v1.1 if painful.
+- Component usage analytics as a dashboard. Can be derived from grepping `content/pages/`.
+- Live hot-reload of public pages on component edit. Refresh is sufficient for v1.
+- Cross-site component sync beyond the existing export/import bundle.
+- Versioning of component history. Components are code; git is the versioning story. `content/versions/` remains page-scoped.
+
+## 10. Risks and open verifications
+
+1. **DOMPurify custom-element allowlist.** Depends on DOMPurify's support for wildcard `ADD_TAGS`. Verify during implementation; fall back to explicit name enumeration from the components service if wildcards are unsupported.
+2. **`E.slideover()` interactive-content handling.** May share the modal's HTML-stripping behaviour. Implementation must test that an iframe inserted via `.element.appendChild` survives slideover open/close cycles.
+3. **Shadow DOM theming.** Components inherit via `getThemeVariables()` from Domma's base. Verify site-level CSS custom properties reach component styles consistently.
+4. **Deferred module load timing.** `<script type="module">` tags are deferred. For above-the-fold components, `:not(:defined) { visibility: hidden; }` is applied site-wide to mask the pre-upgrade flash.
+
+## 11. Files introduced / modified
+
+**New files:**
+
+- `content/components/` - seeded `.dmc` files and `.meta.json` companions.
+- `server/services/components.js` - compiler, CRUD, cache, seed.
+- `server/routes/api/components.js` - HTTP routes.
+- `admin/preview/component-preview.html` - iframe bootstrap.
+- `admin/js/views/components.js` - list view.
+- `admin/js/templates/components.html` - list view template.
+- `admin/js/views/component-editor.js` - editor view.
+- `admin/js/templates/component-editor.html` - editor view template.
+
+**Modified files:**
+
+- `server/server.js` - registers the components route; calls `seedDefaultComponents()` on startup.
+- `server/services/markdown.js` - new `collectComponents()` pass; sanitiser config update.
+- `server/services/renderer.js` - injects per-page component script tags into `bodyEndInject`.
+- `server/services/hooks.js` - adds `registerComponent` hook.
+- `server/services/permissionRegistry.js` - adds `components` resource.
+- `admin/js/views/index.js` - registers `components` + `componentEditor` views.
+- `admin/js/config/sidebar-config.js` - adds the sidebar entry.
+- `admin/js/app.js` - extends `fetchSidebarCounts()` with `api.components.list()`.
+- `admin/js/api.js` - adds `api.components.{list,get,put,delete,exportBundle,importBundle}`.
+- `admin/js/views/page-editor.js` - adds the "Insert Component" toolbar button and slideover wiring.
+- `public/css/site.css` - adds `:not(:defined) { visibility: hidden; }`.
+
+## 12. Success criteria
+
+1. An authorised user can create a `.dmc` file in the admin, have it compile and appear in the library list.
+2. Embedding the component on a page via the Insert Component slideover results in the component rendering correctly on the public site, with only its own script loaded (not the library as a whole).
+3. A compile error in the editor is visibly surfaced, save is blocked, and the existing disk source is untouched.
+4. Deleting or renaming a referenced component degrades gracefully: public pages still render, the `<dm-x>` tag remains inert, and the page editor preview shows a warning.
+5. Runaway JS in a component's preview does not bring down the admin session.
+6. Export and re-import of `.dmcomponent.json` round-trips the component losslessly.
+7. The five seeded starter components install on a fresh CMS and remain editable.

package/docs/superpowers/specs/2026-05-02-effects-slideover-overhaul-design.md

@@ -0,0 +1,193 @@
+# Effects slideover overhaul - design
+
+**Date:** 2026-05-02
+**Status:** Approved (pending implementation plan)
+**Scope:** Phase 2 of the Effects work begun on 2026-05-02 (Phase 1 - `[ticker-tape]` shortcode - already shipped on `main`).
+
+## Background
+
+The page-editor toolbar currently exposes Domma effects through a flat dropdown menu (`effectsMenuItems` in `admin/js/lib/markdown-toolbar.js`). Each entry inserts a basic snippet at the cursor with no parameter UI and no preview. The reference documentation sits in a separate Effects view (`admin/js/templates/effects.html`).
+
+The CMS now supports nine of Domma's ten canvas/JS effects via shortcodes (`reveal`, `breathe`, `pulse`, `scribe`, `reveal`, `scramble`, `counter`, `ripple`, `shake`, `twinkle`, `ticker-tape`) plus four CSS-based ones (`animate`, `ambient`, `firework`, `fireworks`) and the canvas `celebrate`. The dropdown does not scale well as the catalogue grows, and writing effect attributes by hand is error-prone.
+
+This spec describes a unified slideover that replaces the dropdown, adds a parameter UI for every effect, and extends the row-reveal injection pattern to other host shortcodes so effects can be applied to a `[card]`, `[hero]`, etc. without an extra wrapper.
+
+## Goals
+
+- Replace the Effects dropdown with a unified `E.slideover`-based UI that lists all effects, exposes their parameters, and previews their output.
+- Allow effects to be **injected** as flag-attributes on host shortcodes (`[card]`, `[hero]`, `[banner]`, `[col]`, `[button]`) - extending the existing `[row reveal …]` pattern.
+- Support **edit-in-place** of an existing effect block when the cursor is inside one.
+- Keep all current shortcode syntax working unchanged. The new UI is additive; hand-written shortcodes continue to render identically.
+
+## Non-goals (YAGNI)
+
+- Drag-and-drop reordering of effects in the rail.
+- Effect favourites / recents tracking.
+- A UI for stacking multiple effects on one block. The underlying syntax permits it (e.g. `[card reveal pulse]…[/card]`); users who want this can hand-edit.
+- Keyboard shortcuts beyond `Esc`-to-close (relies on Domma slideover's default close-on-Esc behaviour; verify during implementation).
+- Live render preview for effects that don't translate to a small viewport (full-page `[ticker-tape /]`, `[celebrate]`). Those get a static "this runs full-page on the published site" placeholder.
+
+## Decisions taken during brainstorm
+
+| # | Question | Decision |
+|---|----------|----------|
+| 1 | Slideover shape | Option **X** - unified slideover with category rail + effect list on the left, parameters + preview on the right. Replaces the dropdown entirely. |
+| 2 | Preview style | **Shortcode preview always (Option A)**, plus a **live render preview where it works (Option C)** as a secondary feature. Shortcode preview is the primary affordance - it supports the copy-paste-and-amend workflow. |
+| 3 | Phase scoping | **All-in-one (Option i)** - slideover overhaul and effect injection ship together. |
+| 4 | Edit-existing | Slideover detects an effect block at the cursor and opens populated for editing; Insert button becomes Update. |
+| 5 | Reference docs | Existing `admin/js/templates/effects.html` reference is **kept** as a hand-syntax cheatsheet alongside the slideover. No content removed. |
+
+## User experience
+
+### Entry points
+
+- **Toolbar** - the existing `sparkles` Effects button (`markdown-toolbar.js`) opens the slideover instead of a dropdown.
+- **Cursor-aware behaviour** - when the slideover opens, it inspects the textarea selection/cursor:
+  - Inside an existing effect block (e.g. `[reveal …]…[/reveal]`) → opens on that effect, fields populated, **Insert** button becomes **Update**.
+  - Inside a host shortcode (`[card …]`, `[hero …]`, `[banner …]`, `[col …]`, `[button …]`) → opens on the last-used effect with scope set to *Inject into [host]*.
+  - Otherwise → opens on the last-used effect (or Reveal as default), scope = *Standalone*.
+
+### Slideover anatomy
+
+`E.slideover({ title: 'Effects', size: 'lg', position: 'right' })` - Domma's native slideover, not a custom modal.
+
+Body content is a two-column grid:
+
+**Left rail (~170px wide, sticky):**
+
+- Five category headings: Entrance, Animation, Text, Visual, Celebrations.
+- Effects under each. Initial catalogue:
+  - **Entrance:** Reveal, Row reveal
+  - **Animation:** Breathe, Pulse, Shake, CSS animate
+  - **Text:** Scribe, Scramble, Counter
+  - **Visual:** Ripple, Twinkle, Ambient bg
+  - **Celebrations:** Firework, Fireworks, Celebrate, Ticker tape
+- Active effect highlighted; clicking another effect swaps the right pane without closing the slideover.
+
+**Right pane (flex, scrollable):**
+
+1. Effect name (`h3`) and one-line description.
+2. **Scope selector** - a two-button toggle:
+   - *Standalone block* (always available)
+   - *Inject into [host]* - present only if the cursor is inside a host that supports this effect (per the matrix below). When unavailable, an explanatory caption replaces the toggle.
+   Default scope: *Inject* if the cursor is inside a compatible host that does not yet have this effect injected; otherwise *Standalone*.
+3. **Form fields** - one input per attribute, two per row where they fit. Field types: `text`, `number`, `select`, `checkbox`, `colour`. Sensible defaults pre-filled from each effect's `attrs[].default`. Fields are declared in `effect-defs.js` (see below).
+4. **Shortcode preview (always visible)** - monospace block, updates live on every field change. When scope is *Inject*, the preview shows the host shortcode with effect flag-attributes embedded; when *Standalone*, it shows the standalone form. Read-only - the textarea cursor is the source of truth for editing.
+5. **Live preview (effects flagged `previewable: true`)** - small render area with a *Replay* button to re-trigger one-shot animations. Effects flagged `previewable: false` (full-page only) show a static placeholder explaining where the effect actually runs.
+6. **Footer** - *Cancel* and *Insert* (or *Update* in edit mode). Submitting writes the generated shortcode to the textarea via the existing `insertAtCursor` helper, then closes the slideover.
+
+## Server-side: effect injection
+
+### Mechanism
+
+Effect injection means that compatible host shortcodes accept effect-flag attributes and emit a host element that is *also* a `dm-fx-*` element. The client-side `public/js/effects.js` matches on the `.dm-fx-*` class - it does not care whether the class lives on a standalone div or on a `[card]` wrapper, so no client-side changes are needed for injection.
+
+Each affected host processor in `server/services/markdown.js` is updated once to:
+
+1. Detect the presence of any flag-attribute belonging to an injectable effect (e.g. `reveal`, `breathe`, etc.).
+2. Add the matching `dm-fx-<effect>` class to the rendered host element's `class` list, alongside the host's own classes.
+3. Convert effect-prefixed attributes (e.g. `reveal-animation="slide-up"`) to `data-fx-animation="slide-up"` on the same element.
+4. Strip the flag-attribute and prefixed attributes from the host's normal attribute pipeline so they do not leak into output as raw HTML attributes.
+
+The existing `processGridBlocks` row-reveal handling stays as-is - it predates this design and uses the same shape (`reveal`, `reveal-animation`, etc. mapped to `dm-fx-reveal` + `data-fx-*`).
+
+### Host / effect compatibility matrix
+
+| Host | reveal | breathe | pulse | shake | twinkle | ticker-tape | ambient | animate | ripple |
+|------|:------:|:-------:|:-----:|:-----:|:-------:|:-----------:|:-------:|:-------:|:------:|
+| `[card]` | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| `[hero]` | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | - |
+| `[banner]` | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ | - |
+| `[col]` | ✓ | ✓ | - | - | - | - | - | ✓ | ✓ |
+| `[button]` | - | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ |
+
+`[row]` already supports row-level reveal with its own multi-child stagger logic - left untouched.
+
+`scribe`, `scramble`, `counter`, `firework`, `fireworks`, `celebrate` are **always standalone**. They either replace text content (text effects) or are page-level decoration (celebrations) and have no meaningful "host" pairing.
+
+### Syntax
+
+Mirrors the existing `[row reveal reveal-animation="..."]` shape:
+
+```
+[card title="Welcome" reveal reveal-animation="slide-up" reveal-duration="600"]
+Card body
+[/card]
+
+[hero title="Welcome" twinkle twinkle-count="100" twinkle-colour="#fff"]
+Hero body
+[/hero]
+
+[button label="Click me" pulse pulse-scale="1.05"]
+```
+
+Attribute naming pattern: `<effect>` (flag, presence-only) and `<effect>-<attr>` for parameterised values. The flag is required; it's the trigger that tells the host's processor to enter injection mode.
+
+## Components and files
+
+### New
+
+| File | Purpose |
+|------|---------|
+| `admin/js/lib/effect-defs.js` | Declarative effect catalogue. Single source of truth consumed by the slideover. Each entry:<br>`{ name, label, category, description, attrs: [{ name, label, type, default, options?, hint? }], hosts: [...], previewable: boolean }` |
+| `admin/js/lib/effects-builder.js` | Slideover module. Exports `EffectsBuilder.open(textarea, options?)`. Encapsulates: cursor inspection, scope detection, form rendering, shortcode generation, edit-mode handling, live and shortcode preview. Uses helpers from `admin/js/lib/shortcode-modal.js` (`makeField`, `makeSelect`, etc.) for form fields. |
+
+### Modified
+
+| File | Change |
+|------|--------|
+| `admin/js/lib/markdown-toolbar.js` | Remove `effectsMenuItems` and `openEffectsDropdown`. Effects button stays; its handler delegates to the registered `handlers.effects(ta)` callback (already wired). |
+| `admin/js/views/page-editor.js` | Register `toolbar.onEffects(ta => EffectsBuilder.open(ta, …))`. Add new imports for `effects-builder.js?v=1` and `effect-defs.js?v=1`. Bump the toolbar import's `?v=N` if the toolbar handler signature changes. |
+| `server/services/markdown.js` | Extend `processCardBlocks`, `processHeroBlocks`, `processBannerBlocks`, the `[col]` handling inside `processGridBlocks`, and the button shortcode processor to detect injectable effect-flag attributes and stamp `dm-fx-*` class + `data-fx-*` attributes onto the rendered host element. Add a small shared helper (`extractInjectedEffects(attrs, allowedEffects)`) so each host processor uses the same logic. |
+
+### Unchanged
+
+- `public/js/effects.js` - no changes needed. Class-based selection finds injected effects automatically.
+- `admin/js/templates/effects.html` - kept as a hand-syntax cheatsheet alongside the slideover. The Ticker tape section added in Phase 1 stays put.
+- `admin/js/views/effects.js` - no changes; settings tab is untouched.
+
+## Data flow
+
+### Insertion (standalone)
+
+1. User clicks Effects button → `handlers.effects(ta)` → `EffectsBuilder.open(ta)`.
+2. Builder inspects `ta.selectionStart` against `ta.value`. No effect block, no host detected → opens with scope = Standalone, default effect = last-used or Reveal.
+3. User adjusts fields. Each field change calls `_rebuildShortcode()` → updates the live shortcode preview pane (Option A) and, if `previewable`, re-mounts the live render preview (Option C).
+4. User clicks Insert. Builder calls `insertAtCursor(ta, generatedShortcode)`, closes slideover.
+
+### Insertion (injection)
+
+1. Same as above through step 1.
+2. Builder detects the cursor sits inside `[card …]…[/card]`. Opens with scope = *Inject into [card]*, default effect = last-used or Reveal (filtered to effects valid for the detected host).
+3. The generated shortcode rewrites the host's opening tag, adding flag attributes. Preview shows the rewritten host tag.
+4. Insert replaces the host's opening tag in `ta.value` (range computed from cursor position) - not via `insertAtCursor`.
+
+### Edit-in-place
+
+1. Cursor sits inside `[reveal animation="fade"]…[/reveal]`. Builder identifies the enclosing block by scanning backwards from the cursor for `[reveal` and forwards for `[/reveal]`. The body content between is preserved verbatim.
+2. The opening tag is parsed via `parseShortcodeAttrs` (existing helper exported from `server/services/markdown.js` - but the admin UI re-implements it client-side as a small standalone helper, since admin code does not import server modules).
+3. Form fields populate; button label switches to *Update*.
+4. Update replaces the existing `[reveal …]…[/reveal]` block in `ta.value` with the regenerated form. Selection is restored to the inside of the new block.
+
+## Edge cases and behaviours
+
+- **Multiple cursors / no selection** - builder uses `ta.selectionStart` only; no multi-selection support.
+- **Cursor inside a code block** - builder still opens but disables Insert with a caption explaining that effects inside fenced code are inert. Not blocking.
+- **Cursor inside a host that already has an effect injected** - edit-mode wins; the existing effect's fields populate, and the user can change it or remove flags by clearing the attribute fields.
+- **Reduced motion preview** - the live render preview honours `prefers-reduced-motion` (skips animation, shows the result frame). The published page already handles this via `effects.js`.
+- **Slideover reopened after navigation** - only the last-used effect *name* is persisted via `S.set('effects-builder-last', name)`; field values reset to defaults each open. This avoids stale numeric values bleeding across unrelated pages.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Markdown parser performance regression from the new `extractInjectedEffects` pass on five host processors. | The pass operates on already-parsed attribute objects (cheap), not on the raw markdown. No new regex passes. |
+| Effect injection produces invalid output when multiple effects are flagged on one host (e.g. `[card reveal pulse]`). | `extractInjectedEffects` allows multiple effects in principle but the slideover only emits one at a time. Hand-written multiple-effect cases get `dm-fx-reveal dm-fx-pulse` on the same div - verified to work because `effects.js` initialisers are independent. Document this in the cheatsheet. |
+| Live preview of `[scribe]` in the slideover competes with the `scribe-composer.js` slideover already used for the Insert → Scribe path. | The Effects slideover's Scribe form uses simple-mode fields only (speed, cursor, loop). Users who need the action-script composer use Insert → Scribe instead. Cross-link in the Scribe form's description text. |
+| Cache-busters drift if implementation lands across multiple commits. | Bump `?v=N` in the same commit that touches the imported module. Already part of the project convention (see `MEMORY.md`). |
+
+## Open follow-ups (not in this spec)
+
+- Phase 4: a search/filter input on the slideover's left rail once the catalogue grows past ~20 effects.
+- Phase 4: optional plugin-defined effects appearing in the slideover via a registry call.
+- Phase 4: extending the cheatsheet template to be auto-generated from `effect-defs.js`.