domma-cms 1.6.60 → 1.7.0

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

@@ -0,0 +1,2335 @@
+# Effects slideover overhaul - implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the page-editor's flat Effects dropdown with a unified `E.slideover` UI that exposes a parameter form, live shortcode preview, and (where applicable) a live render preview for every Domma effect, plus extends the row-reveal injection pattern to `[card]`, `[hero]`, `[banner]`, `[col]`, `[button]`.
+
+**Architecture:** Two new admin lib modules (`effect-defs.js`, `effects-builder.js`) drive the slideover; one shared server-side helper (`extractInjectedEffects`) is wired into five existing host processors in `markdown.js`. The existing `public/js/effects.js` runtime initialiser is reused unchanged - class-based selection means injected effects work for free on the published site.
+
+**Tech Stack:** Fastify 5 (ESM), Domma SPA, `node:test` for server-side unit tests, manual browser verification for slideover UI.
+
+**Special conventions for this project:**
+- **No commits during implementation.** The user commits separately. This plan does **not** include `git commit` steps; instead each phase ends with a User Checkpoint where the user can review/test/commit.
+- **Browser verification is mandatory** for any UI claim. Server-side passing tests do **not** count as "the slideover works". Each phase that ships UI behaviour ends with explicit browser-verification steps to be performed at `http://192.168.1.4:4096/admin`.
+- **Cache-buster discipline.** When a module imported via `import {…} from "../lib/<module>.js?v=N"` is modified, the importer's `?v=N` must be bumped in the same change.
+- **Server is always running on port 4096.** Never kill or start it. To verify endpoints, just `curl`/visit.
+
+---
+
+## File Structure
+
+**New files:**
+- `admin/js/lib/effect-defs.js` - declarative effect catalogue. Pure data export; one entry per effect with `{ name, label, category, description, attrs, hosts, previewable }`. Single source of truth.
+- `admin/js/lib/effects-builder.js` - slideover module. Exports `EffectsBuilder.open(textarea)`. Internally handles cursor inspection, scope detection, form rendering, shortcode generation, edit-mode handling, both preview panes.
+- `tests/markdown/effect-injection.test.js` - `node:test` suite covering host-shortcode injection rendering for all five hosts × applicable effects.
+
+**Modified files:**
+- `server/services/markdown.js` - add `extractInjectedEffects` shared helper; wire into `processCardBlocks`, `processHeroBlocks`, `processBannerBlocks`, `processButtonBlocks`, `[col]` arm of `processGridBlocks`. Migrate the existing ad-hoc `twinkle`/`blobs` injection in `processHeroBlocks` to use the helper. (Existing `[row reveal …]` logic is left untouched - it predates this design and uses `data-reveal-*` rather than `data-fx-*` because of its multi-child stagger semantics.)
+- `admin/js/lib/markdown-toolbar.js` - delete `effectsMenuItems` constant, delete `openEffectsDropdown` function, delete the `else if (action === 'effects')` branch's fallback to the dropdown so the registered `handlers.effects(ta)` callback fires directly.
+- `admin/js/views/page-editor.js` - register `toolbar.onEffects(ta => EffectsBuilder.open(ta))`. Add new imports for `effects-builder.js?v=1`. Bump `markdown-toolbar.js` cache-buster from `?v=12` to `?v=13`.
+
+**Unchanged:**
+- `public/js/effects.js` - class-based selection finds injected effects automatically; no changes needed.
+- `admin/js/templates/effects.html` - kept as the hand-syntax reference cheatsheet.
+- `admin/js/views/effects.js` - settings tab unaffected.
+
+---
+
+## Phase A - Server-side effect injection (TDD)
+
+### Task A1: Test scaffolding
+
+**Files:**
+- Create: `tests/markdown/effect-injection.test.js`
+
+- [ ] **Step 1: Create the test file with the imports and a sanity test.**
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {parseMarkdown} from '../../server/services/markdown.js';
+
+test('parseMarkdown is reachable from the test runner', async () => {
+    const {html} = await parseMarkdown('# hello');
+    assert.match(html, /<h1>hello<\/h1>/);
+});
+```
+
+- [ ] **Step 2: Run the sanity test.**
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: 1 passing test, no failures.
+
+---
+
+### Task A2: `extractInjectedEffects` helper
+
+**Files:**
+- Modify: `server/services/markdown.js` - add helper near the existing `escapeAttr` export (line ~1111)
+- Test: `tests/markdown/effect-injection.test.js`
+
+The helper takes a parsed `attrs` object (output of `parseShortcodeAttrs`) and a list of *allowed* effect names for the host, and returns:
+- `effectClasses` - string array of `dm-fx-<effect>` classes to add
+- `effectDataAttrs` - `data-fx-<attr>="value"` string fragment, ready to splice into the host's opening tag
+- `consumedKeys` - Set of attribute keys that were claimed (so the host can skip them when emitting other attrs)
+
+This is what every host will call. Only effects in `allowed` participate.
+
+- [ ] **Step 1: Write the failing tests.**
+
+Add to `tests/markdown/effect-injection.test.js`:
+
+```js
+import {extractInjectedEffects, parseShortcodeAttrs} from '../../server/services/markdown.js';
+
+test('extractInjectedEffects: no flags → empty result', () => {
+    const attrs = parseShortcodeAttrs('title="Hi"');
+    const out = extractInjectedEffects(attrs, ['reveal', 'pulse']);
+    assert.deepEqual(out.effectClasses, []);
+    assert.equal(out.effectDataAttrs, '');
+    assert.equal(out.consumedKeys.size, 0);
+});
+
+test('extractInjectedEffects: flag with no params → class only', () => {
+    const attrs = parseShortcodeAttrs('title="Hi" reveal');
+    const out = extractInjectedEffects(attrs, ['reveal']);
+    assert.deepEqual(out.effectClasses, ['dm-fx-reveal']);
+    assert.equal(out.effectDataAttrs, '');
+    assert.ok(out.consumedKeys.has('reveal'));
+});
+
+test('extractInjectedEffects: flag with prefixed params → class + data attrs', () => {
+    const attrs = parseShortcodeAttrs(
+        'title="Hi" reveal reveal-animation="slide-up" reveal-duration="600"'
+    );
+    const out = extractInjectedEffects(attrs, ['reveal']);
+    assert.deepEqual(out.effectClasses, ['dm-fx-reveal']);
+    assert.match(out.effectDataAttrs, / data-fx-animation="slide-up"/);
+    assert.match(out.effectDataAttrs, / data-fx-duration="600"/);
+    assert.ok(out.consumedKeys.has('reveal'));
+    assert.ok(out.consumedKeys.has('reveal-animation'));
+    assert.ok(out.consumedKeys.has('reveal-duration'));
+});
+
+test('extractInjectedEffects: disallowed effect ignored', () => {
+    const attrs = parseShortcodeAttrs('title="Hi" pulse');
+    const out = extractInjectedEffects(attrs, ['reveal']); // pulse not allowed
+    assert.deepEqual(out.effectClasses, []);
+    assert.equal(out.consumedKeys.size, 0);
+});
+
+test('extractInjectedEffects: multiple flags compose', () => {
+    const attrs = parseShortcodeAttrs('title="Hi" reveal pulse pulse-scale="1.05"');
+    const out = extractInjectedEffects(attrs, ['reveal', 'pulse']);
+    assert.deepEqual(out.effectClasses.sort(), ['dm-fx-pulse', 'dm-fx-reveal']);
+    assert.match(out.effectDataAttrs, / data-fx-scale="1.05"/);
+    // Note: when two effects share an attr namespace we still emit data-fx-<attr>
+    // - the runtime initialisers each read what they need; collisions are author error.
+});
+
+test('extractInjectedEffects: HTML-escapes attribute values', () => {
+    const attrs = parseShortcodeAttrs('twinkle twinkle-colour=\'red"&\'');
+    const out = extractInjectedEffects(attrs, ['twinkle']);
+    assert.match(out.effectDataAttrs, /data-fx-colour="red&quot;&amp;"/);
+});
+```
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: all six new tests fail with `extractInjectedEffects is not a function` (it's not exported yet).
+
+- [ ] **Step 2: Implement the helper.**
+
+Open `server/services/markdown.js`. Find the `escapeAttr` export (line ~1111). Immediately after it, add:
+
+```js
+/**
+ * Extract injected-effect flag attributes from a parsed shortcode attrs object.
+ *
+ * For each effect in `allowed` whose flag attribute is present in `attrs`,
+ * emit a `dm-fx-<effect>` class and convert all `<effect>-<attr>` keys to
+ * `data-fx-<attr>="<escaped-value>"` fragments. Returns the consumed keys
+ * so the host processor can skip them when emitting its own attributes.
+ *
+ * The flag attribute itself is presence-only (parseShortcodeAttrs returns
+ * an empty string for bare flags). Prefixed attributes carry the value.
+ *
+ * @param {Object<string,string>} attrs - parsed shortcode attribute map
+ * @param {string[]} allowed - effect names this host accepts (e.g. ['reveal','pulse'])
+ * @returns {{effectClasses: string[], effectDataAttrs: string, consumedKeys: Set<string>}}
+ */
+export function extractInjectedEffects(attrs, allowed) {
+    const effectClasses = [];
+    const dataAttrParts = [];
+    const consumedKeys = new Set();
+
+    for (const effect of allowed) {
+        if (!(effect in attrs)) continue;
+        effectClasses.push(`dm-fx-${effect}`);
+        consumedKeys.add(effect);
+
+        const prefix = `${effect}-`;
+        for (const key of Object.keys(attrs)) {
+            if (!key.startsWith(prefix)) continue;
+            const param = key.slice(prefix.length);
+            dataAttrParts.push(` data-fx-${param}="${escapeAttr(String(attrs[key]))}"`);
+            consumedKeys.add(key);
+        }
+    }
+
+    return {
+        effectClasses,
+        effectDataAttrs: dataAttrParts.join(''),
+        consumedKeys,
+    };
+}
+```
+
+- [ ] **Step 3: Run tests.**
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: all 7 tests pass.
+
+---
+
+### Task A3: Inject effects into `[card]`
+
+**Files:**
+- Modify: `server/services/markdown.js` - `processCardBlocks` (function starts at line ~1730)
+- Test: `tests/markdown/effect-injection.test.js`
+
+Allowed effects on `[card]`: `reveal`, `breathe`, `pulse`, `shake`, `twinkle`, `ambient`, `animate`, `ripple`.
+
+- [ ] **Step 1: Write the failing tests.**
+
+Add to `tests/markdown/effect-injection.test.js`:
+
+```js
+test('[card] + reveal injection emits dm-fx-reveal + data-fx-* on card', async () => {
+    const md = `[card title="Welcome" reveal reveal-animation="slide-up" reveal-duration="600"]
+Body content.
+[/card]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-reveal\b[^"]*"/);
+    assert.match(html, /data-fx-animation="slide-up"/);
+    assert.match(html, /data-fx-duration="600"/);
+    // The card's own classes/title still render.
+    assert.match(html, /Welcome/);
+    // The flag itself didn't leak into output as a raw HTML attribute.
+    assert.doesNotMatch(html, /\breveal=/);
+});
+
+test('[card] + pulse injection works alongside title', async () => {
+    const md = `[card title="Welcome" pulse pulse-scale="1.05"]
+Body.
+[/card]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-pulse\b[^"]*"/);
+    assert.match(html, /data-fx-scale="1.05"/);
+});
+
+test('[card] without effects is unchanged', async () => {
+    const md = `[card title="Plain"]
+Body.
+[/card]`;
+    const {html} = await parseMarkdown(md);
+    assert.doesNotMatch(html, /dm-fx-/);
+    assert.doesNotMatch(html, /data-fx-/);
+});
+```
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: card-injection tests fail (no injection logic in `processCardBlocks` yet); existing tests still pass.
+
+- [ ] **Step 2: Locate the card emit site.**
+
+In `server/services/markdown.js`, `processCardBlocks` is large but its emit point is where it builds the final `<div class="card …">…</div>` string. Read the function and find the line that assembles the `class` array and the line that emits the opening `<div`. Make a note of the variable names - typically `classes` for the class array and a template string with `class="${classes.join(' ')}"`.
+
+- [ ] **Step 3: Wire injection into card emit.**
+
+Inside `processCardBlocks`'s replace callback, near the top after `const attrs = parseShortcodeAttrs(attrStr);`, add:
+
+```js
+const CARD_INJECTABLE = ['reveal', 'breathe', 'pulse', 'shake', 'twinkle', 'ambient', 'animate', 'ripple'];
+const injected = extractInjectedEffects(attrs, CARD_INJECTABLE);
+```
+
+Then where the card's `classes` array is built, append `...injected.effectClasses`:
+
+```js
+classes.push(...injected.effectClasses);
+```
+
+Then where the opening `<div` tag is emitted with class/id/etc, splice `${injected.effectDataAttrs}` into the attribute slot. For example:
+
+```js
+return `<div class="${classes.join(' ')}"${idAttr}${injected.effectDataAttrs}…>…</div>`;
+```
+
+(Place `${injected.effectDataAttrs}` after the `class` and `id` attributes but before any `style` or other host-specific attrs - order doesn't matter functionally but keep it readable.)
+
+- [ ] **Step 4: Run tests.**
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: all card tests now pass; previous tests still pass.
+
+---
+
+### Task A4: Inject effects into `[hero]` (refactor)
+
+**Files:**
+- Modify: `server/services/markdown.js` - `processHeroBlocks` (line ~2586)
+- Test: `tests/markdown/effect-injection.test.js`
+
+Allowed effects on `[hero]`: `reveal`, `breathe`, `pulse`, `twinkle`, `ticker-tape`, `ambient`, `animate`. Note: `[hero]` already has bespoke twinkle and blobs handling - replace the twinkle bit with the generic helper, keep blobs as-is.
+
+- [ ] **Step 1: Write the failing tests.**
+
+Add to `tests/markdown/effect-injection.test.js`:
+
+```js
+test('[hero] + reveal injection', async () => {
+    const md = `[hero title="Welcome" reveal reveal-animation="zoom"]
+Tagline
+[/hero]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-reveal\b[^"]*"/);
+    assert.match(html, /data-fx-animation="zoom"/);
+});
+
+test('[hero] + twinkle still works after refactor (regression)', async () => {
+    const md = `[hero title="Stars" twinkle twinkle-count="100" twinkle-colour="#fff"]
+Hero body.
+[/hero]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-twinkle\b[^"]*"/);
+    assert.match(html, /data-fx-count="100"/);
+    assert.match(html, /data-fx-colour="#fff"/);
+});
+
+test('[hero] + ticker-tape injection', async () => {
+    const md = `[hero title="Party" ticker-tape ticker-tape-palette="festive"]
+Body.
+[/hero]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-ticker-tape\b[^"]*"/);
+    assert.match(html, /data-fx-palette="festive"/);
+});
+```
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: hero-reveal test fails; hero-twinkle test currently passes (existing bespoke logic); ticker-tape test fails.
+
+- [ ] **Step 2: Refactor `processHeroBlocks`.**
+
+In `processHeroBlocks`, find the existing twinkle handling block (around line 2606-2635). Replace it with the generic helper.
+
+Before:
+
+```js
+const twinkle = 'twinkle' in attrs;
+const twinkleCount = attrs['twinkle-count'] || '';
+const twinkleColour = attrs['twinkle-colour'] || '';
+const blobs = 'blobs' in attrs;
+const blobsType = attrs['blobs-type'] || 'float-blobs';
+…
+if (twinkle) classes.push('dm-fx-twinkle');
+if (blobs) classes.push(`bg-ambient-${blobsType}`);
+…
+const twinkleAttrs = twinkle
+    ? (twinkleCount ? ` data-fx-count="${escapeAttr(twinkleCount)}"` : '') +
+      (twinkleColour ? ` data-fx-colour="${escapeAttr(twinkleColour)}"` : '')
+    : '';
+…
+return `<div class="${classes.join(' ')}"${idAttr}${style}${twinkleAttrs}>${inner}</div>\n`;
+```
+
+After:
+
+```js
+const HERO_INJECTABLE = ['reveal', 'breathe', 'pulse', 'twinkle', 'ticker-tape', 'ambient', 'animate'];
+const injected = extractInjectedEffects(attrs, HERO_INJECTABLE);
+
+// Legacy ad-hoc 'blobs' flag - keep for backward compat. Different keyspace
+// (bg-ambient-* CSS class), not folded into the generic helper.
+const blobs = 'blobs' in attrs;
+const blobsType = attrs['blobs-type'] || 'float-blobs';
+…
+classes.push(...injected.effectClasses);
+if (blobs) classes.push(`bg-ambient-${blobsType}`);
+…
+return `<div class="${classes.join(' ')}"${idAttr}${style}${injected.effectDataAttrs}>${inner}</div>\n`;
+```
+
+The `twinkleAttrs` variable goes away entirely.
+
+- [ ] **Step 3: Run tests.**
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: all hero tests pass; card tests still pass.
+
+---
+
+### Task A5: Inject effects into `[banner]`
+
+**Files:**
+- Modify: `server/services/markdown.js` - `processBannerBlocks` (line ~2690)
+- Test: `tests/markdown/effect-injection.test.js`
+
+Allowed effects on `[banner]`: `reveal`, `pulse`, `shake`, `ambient`, `animate`.
+
+- [ ] **Step 1: Write the failing tests.**
+
+Add to `tests/markdown/effect-injection.test.js`:
+
+```js
+test('[banner] + reveal injection', async () => {
+    const md = `[banner type="info" reveal reveal-animation="fade"]
+Heads up.
+[/banner]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-reveal\b[^"]*"/);
+    assert.match(html, /data-fx-animation="fade"/);
+});
+
+test('[banner] + pulse injection', async () => {
+    const md = `[banner type="warning" pulse]
+Important.
+[/banner]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-pulse\b[^"]*"/);
+});
+
+test('[banner] disallowed effect (twinkle) is ignored', async () => {
+    const md = `[banner type="info" twinkle]
+Body.
+[/banner]`;
+    const {html} = await parseMarkdown(md);
+    assert.doesNotMatch(html, /dm-fx-twinkle/);
+});
+```
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: banner injection tests fail; the disallowed test currently passes by coincidence (no injection logic at all yet).
+
+- [ ] **Step 2: Wire injection into banner emit.**
+
+In `processBannerBlocks`, after `const attrs = parseShortcodeAttrs(attrStr);` add:
+
+```js
+const BANNER_INJECTABLE = ['reveal', 'pulse', 'shake', 'ambient', 'animate'];
+const injected = extractInjectedEffects(attrs, BANNER_INJECTABLE);
+```
+
+Then where the `classes` array is built, append:
+
+```js
+classes.push(...injected.effectClasses);
+```
+
+Then in the final returned template string, splice `${injected.effectDataAttrs}` into the outer `<div class="…">` - change:
+
+```js
+return (
+    `<div class="${classes.join(' ')}">\n` +
+    `  ${iconHtml}<div class="dm-banner__body">\n` +
+    …
+);
+```
+
+to:
+
+```js
+return (
+    `<div class="${classes.join(' ')}"${injected.effectDataAttrs}>\n` +
+    `  ${iconHtml}<div class="dm-banner__body">\n` +
+    …
+);
+```
+
+- [ ] **Step 3: Run tests.**
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: all banner tests pass.
+
+---
+
+### Task A6: Inject effects into `[button]`
+
+**Files:**
+- Modify: `server/services/markdown.js` - `processButtonBlocks` (line ~2241)
+- Test: `tests/markdown/effect-injection.test.js`
+
+Allowed effects on `[button]`: `breathe`, `pulse`, `shake`, `animate`, `ripple`.
+
+- [ ] **Step 1: Write the failing tests.**
+
+```js
+test('[button] + pulse injection (wrapping form)', async () => {
+    const md = `[button href="/go" pulse pulse-scale="1.05"]Click[/button]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-pulse\b[^"]*"/);
+    assert.match(html, /data-fx-scale="1.05"/);
+});
+
+test('[button] + breathe injection (self-closing form)', async () => {
+    const md = `[button href="/go" label="Go" breathe /]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-breathe\b[^"]*"/);
+});
+
+test('[button] without effects is unchanged', async () => {
+    const md = `[button href="/go"]Click[/button]`;
+    const {html} = await parseMarkdown(md);
+    assert.doesNotMatch(html, /dm-fx-/);
+});
+```
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: button-injection tests fail.
+
+- [ ] **Step 2: Wire injection into the button builder.**
+
+In `processButtonBlocks`, locate the `buildButton` inner function. After `const attrs = parseShortcodeAttrs(attrStr || '');` add:
+
+```js
+const BUTTON_INJECTABLE = ['breathe', 'pulse', 'shake', 'animate', 'ripple'];
+const injected = extractInjectedEffects(attrs, BUTTON_INJECTABLE);
+```
+
+Then where the `classes` array is built, after the existing pushes, add:
+
+```js
+classes.push(...injected.effectClasses);
+```
+
+Then in the `return` statement that emits the `<a>` tag, splice `${injected.effectDataAttrs}` after `targetAttr`:
+
+```js
+return `<a href="${escapeAttr(href)}" class="${classes.join(' ')}"${idAttr}${targetAttr}${injected.effectDataAttrs}>${icon}${label}${iconAfter}</a>`;
+```
+
+- [ ] **Step 3: Run tests.**
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: all button tests pass.
+
+---
+
+### Task A7: Inject effects into `[col]`
+
+**Files:**
+- Modify: `server/services/markdown.js` - `processGridBlocks` (function at line ~969), inside Pass 1 (`[col]…[/col]` replace)
+- Test: `tests/markdown/effect-injection.test.js`
+
+Allowed effects on `[col]`: `reveal`, `breathe`, `animate`, `ripple`. (Tighter list - `[col]` is often a layout primitive inside `[row reveal]` so we don't want competing reveal animations; we do allow standalone `reveal` for cases without a parent `[row reveal]`.)
+
+- [ ] **Step 1: Write the failing tests.**
+
+```js
+test('[col] + reveal injection inside [grid]', async () => {
+    const md = `[grid cols="2"]
+[col reveal reveal-animation="fade"]
+First.
+[/col]
+[col]
+Second.
+[/col]
+[/grid]`;
+    const {html} = await parseMarkdown(md);
+    // First col gets the dm-fx-reveal class; second col does not.
+    assert.match(html, /class="[^"]*\bdm-fx-reveal\b[^"]*"/);
+    assert.match(html, /data-fx-animation="fade"/);
+});
+
+test('[col] + breathe injection', async () => {
+    const md = `[grid cols="1"]
+[col breathe]
+Calm.
+[/col]
+[/grid]`;
+    const {html} = await parseMarkdown(md);
+    assert.match(html, /class="[^"]*\bdm-fx-breathe\b[^"]*"/);
+});
+```
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: col-injection tests fail.
+
+- [ ] **Step 2: Wire injection into Pass 1 of processGridBlocks.**
+
+In `processGridBlocks`, locate Pass 1 (the `\[col([^\]]*)\]…` replace). Inside the callback, after `const attrs = parseShortcodeAttrs(attrStr);` add:
+
+```js
+const COL_INJECTABLE = ['reveal', 'breathe', 'animate', 'ripple'];
+const injected = extractInjectedEffects(attrs, COL_INJECTABLE);
+```
+
+Change the class assignment from:
+
+```js
+const cls = attrs.span ? ` class="col-span-${attrs.span}"` : ' class="col"';
+```
+
+to:
+
+```js
+const baseCls = attrs.span ? `col-span-${attrs.span}` : 'col';
+const allClasses = [baseCls, ...injected.effectClasses].join(' ');
+const cls = ` class="${allClasses}"`;
+```
+
+Then in the return, splice `${injected.effectDataAttrs}` into the opening div:
+
+```js
+return `<div${cls}${id}${injected.effectDataAttrs}>${marked.parse(processCardBlocks(restore(body.trim())))}</div>`;
+```
+
+- [ ] **Step 3: Run tests.**
+
+Run: `node --test tests/markdown/effect-injection.test.js`
+Expected: all col tests pass.
+
+---
+
+### Phase A - User Checkpoint
+
+Run the full test file once more - `node --test tests/markdown/effect-injection.test.js` - and confirm all tests pass. At this point, server-side injection is feature-complete. You can manually verify by adding to a test page:
+
+```markdown
+[card title="Test" reveal reveal-animation="slide-up"]
+This card should slide up on scroll.
+[/card]
+```
+
+…then load the page in a browser at `http://192.168.1.4:4096/<page-url>` and watch the card slide up. **This is browser-required verification** - server tests do not prove the runtime initialiser fires.
+
+User commits at this point if happy.
+
+---
+
+## Phase B - Effect catalogue
+
+### Task B1: Create `effect-defs.js`
+
+**Files:**
+- Create: `admin/js/lib/effect-defs.js`
+
+This is pure data. No tests required beyond the syntax check at the end - but the *shape* must be right because every consumer downstream pivots off it.
+
+- [ ] **Step 1: Write the catalogue.**
+
+Create `admin/js/lib/effect-defs.js`:
+
+```js
+/**
+ * Declarative catalogue of Domma effects available in the page editor.
+ *
+ * Each entry drives both the slideover form (parameter UI) and the
+ * shortcode generation (which attribute names get emitted).
+ *
+ * Field shapes used by attrs[]:
+ *   - { name, label, type: 'text',     default?, placeholder?, hint? }
+ *   - { name, label, type: 'number',   default?, min?, max?, step?, hint? }
+ *   - { name, label, type: 'select',   default?, options: [['val','Label'], …], hint? }
+ *   - { name, label, type: 'checkbox', default?, hint? }
+ *   - { name, label, type: 'colour',   default?, hint? }
+ *
+ * `hosts`: array of host shortcode names this effect can be injected into.
+ *          Empty array means standalone-only.
+ * `previewable`: whether the slideover's live render preview can host this
+ *                effect. Full-page-only effects are false (we show a static
+ *                placeholder instead).
+ */
+export const EFFECTS = [
+    // ── Entrance ────────────────────────────────────────────────────────────
+    {
+        name: 'reveal',
+        label: 'Reveal',
+        category: 'Entrance',
+        description: 'Scroll-triggered entrance animation when the element enters the viewport.',
+        attrs: [
+            {name: 'animation', label: 'Animation', type: 'select', default: 'fade',
+                options: [['fade','Fade'],['slide-up','Slide up'],['slide-down','Slide down'],['zoom','Zoom'],['flip','Flip']]},
+            {name: 'duration',  label: 'Duration (ms)',  type: 'number', default: 600},
+            {name: 'delay',     label: 'Delay (ms)',     type: 'number', default: 0},
+            {name: 'threshold', label: 'Threshold',      type: 'number', default: 0.1, step: 0.05, min: 0, max: 1},
+            {name: 'once',      label: 'Animate once',   type: 'checkbox', default: true},
+        ],
+        hosts: ['card', 'hero', 'banner', 'col'],
+        previewable: true,
+    },
+
+    // ── Animation ───────────────────────────────────────────────────────────
+    {
+        name: 'breathe',
+        label: 'Breathe',
+        category: 'Animation',
+        description: 'Continuous gentle scaling - makes elements feel alive.',
+        attrs: [
+            {name: 'amplitude', label: 'Amplitude (px)', type: 'number', default: 8},
+            {name: 'duration',  label: 'Duration (ms)',  type: 'number', default: 3000},
+        ],
+        hosts: ['card', 'hero', 'col', 'button'],
+        previewable: true,
+    },
+    {
+        name: 'pulse',
+        label: 'Pulse',
+        category: 'Animation',
+        description: 'A repeating scale pulse - stronger than breathe.',
+        attrs: [
+            {name: 'scale',    label: 'Scale',         type: 'number', default: 1.05, step: 0.01},
+            {name: 'duration', label: 'Duration (ms)', type: 'number', default: 1000},
+        ],
+        hosts: ['card', 'hero', 'banner', 'button'],
+        previewable: true,
+    },
+    {
+        name: 'shake',
+        label: 'Shake',
+        category: 'Animation',
+        description: 'One-shot horizontal or vertical shake.',
+        attrs: [
+            {name: 'intensity', label: 'Intensity (px)', type: 'number', default: 5},
+            {name: 'duration',  label: 'Duration (ms)',  type: 'number', default: 500},
+            {name: 'direction', label: 'Direction',      type: 'select', default: 'horizontal',
+                options: [['horizontal','Horizontal'],['vertical','Vertical']]},
+        ],
+        hosts: ['card', 'banner', 'button'],
+        previewable: true,
+    },
+    {
+        name: 'animate',
+        label: 'CSS Animate',
+        category: 'Animation',
+        description: 'Applies a Domma CSS animation utility class - no JavaScript.',
+        attrs: [
+            {name: 'type', label: 'Type', type: 'select', default: 'fade-in-up',
+                options: [
+                    ['fade-in','fade-in'],['fade-in-up','fade-in-up'],['fade-in-down','fade-in-down'],
+                    ['fade-in-left','fade-in-left'],['fade-in-right','fade-in-right'],
+                    ['slide-in-up','slide-in-up'],['slide-in-down','slide-in-down'],
+                    ['zoom-in','zoom-in'],['zoom-out','zoom-out'],
+                    ['bounce','bounce'],['pulse','pulse'],['shake','shake'],['spin','spin'],['flip','flip'],
+                ]},
+            {name: 'duration', label: 'Duration', type: 'select', default: 'normal',
+                options: [['fast','fast'],['normal','normal'],['slow','slow'],['slower','slower']]},
+            {name: 'delay',    label: 'Delay (ms)', type: 'number', default: 0},
+            {name: 'repeat',   label: 'Repeat', type: 'select', default: 'once',
+                options: [['once','Once'],['infinite','Infinite']]},
+        ],
+        hosts: ['card', 'hero', 'banner', 'col', 'button'],
+        previewable: true,
+    },
+
+    // ── Text ────────────────────────────────────────────────────────────────
+    {
+        name: 'scribe',
+        label: 'Scribe (typewriter)',
+        category: 'Text',
+        description: 'Types text character by character. Simple mode only - for the action-script composer use Insert → Scribe.',
+        attrs: [
+            {name: 'speed',  label: 'Speed (ms/char)', type: 'number', default: 50},
+            {name: 'cursor', label: 'Show cursor',     type: 'checkbox', default: true},
+            {name: 'loop',   label: 'Loop',            type: 'checkbox', default: false},
+        ],
+        hosts: [],
+        previewable: true,
+    },
+    {
+        name: 'scramble',
+        label: 'Scramble',
+        category: 'Text',
+        description: 'Reveals text through a character-scramble animation.',
+        attrs: [
+            {name: 'speed', label: 'Speed (ms/char)', type: 'number', default: 50},
+            {name: 'loop',  label: 'Loop',            type: 'checkbox', default: false},
+        ],
+        hosts: [],
+        previewable: true,
+    },
+    {
+        name: 'counter',
+        label: 'Counter',
+        category: 'Text',
+        description: 'Animates a number from a starting value to a target. Self-closing shortcode.',
+        attrs: [
+            {name: 'to',        label: 'To',             type: 'number', default: 100},
+            {name: 'from',      label: 'From',           type: 'number', default: 0},
+            {name: 'duration',  label: 'Duration (ms)',  type: 'number', default: 2000},
+            {name: 'prefix',    label: 'Prefix',         type: 'text',   default: ''},
+            {name: 'suffix',    label: 'Suffix',         type: 'text',   default: ''},
+            {name: 'decimals',  label: 'Decimal places', type: 'number', default: 0},
+            {name: 'separator', label: 'Thousand separator', type: 'text', default: ''},
+        ],
+        hosts: [],
+        previewable: true,
+        selfClosing: true, // counter has no body
+    },
+
+    // ── Visual ──────────────────────────────────────────────────────────────
+    {
+        name: 'ripple',
+        label: 'Ripple',
+        category: 'Visual',
+        description: 'Click-triggered ripple effect on the element.',
+        attrs: [
+            {name: 'colour',   label: 'Colour',        type: 'colour', default: '#7c6af7'},
+            {name: 'duration', label: 'Duration (ms)', type: 'number', default: 600},
+            {name: 'opacity',  label: 'Opacity',       type: 'number', default: 0.3, step: 0.05, min: 0, max: 1},
+        ],
+        hosts: ['card', 'col', 'button'],
+        previewable: true,
+    },
+    {
+        name: 'twinkle',
+        label: 'Twinkle',
+        category: 'Visual',
+        description: 'Generates animated particle effects inside the element.',
+        attrs: [
+            {name: 'count',    label: 'Particle count', type: 'number', default: 80},
+            {name: 'shape',    label: 'Shape',          type: 'select', default: 'star',
+                options: [['star','Star'],['circle','Circle'],['square','Square']]},
+            {name: 'colour',   label: 'Colour',         type: 'colour', default: '#ffffff'},
+            {name: 'min-size', label: 'Min size (px)',  type: 'number', default: 2},
+            {name: 'max-size', label: 'Max size (px)',  type: 'number', default: 6},
+        ],
+        hosts: ['card', 'hero'],
+        previewable: true,
+    },
+    {
+        name: 'ambient',
+        label: 'Ambient background',
+        category: 'Visual',
+        description: 'Applies an animated CSS background class to the element.',
+        attrs: [
+            {name: 'type', label: 'Type', type: 'select', default: 'float-blobs',
+                options: [
+                    ['float-blobs','Float blobs'],['float-orbs','Float orbs'],['float-particles','Float particles'],
+                    ['rotate-glow','Rotate glow'],['rotate-dual','Rotate dual'],['rotate-spotlight','Rotate spotlight'],
+                    ['wave','Wave'],['ripple','Ripple'],['aurora','Aurora'],
+                ]},
+            {name: 'speed',     label: 'Speed', type: 'select', default: 'normal',
+                options: [['slow','Slow'],['normal','Normal'],['fast','Fast']]},
+            {name: 'intensity', label: 'Intensity', type: 'select', default: 'subtle',
+                options: [['subtle','Subtle'],['intense','Intense']]},
+        ],
+        hosts: ['card', 'hero', 'banner'],
+        previewable: true,
+    },
+
+    // ── Celebrations ────────────────────────────────────────────────────────
+    {
+        name: 'firework',
+        label: 'Firework',
+        category: 'Celebrations',
+        description: 'CSS-only firework particle. Self-closing or wrapping form.',
+        attrs: [
+            {name: 'type',       label: 'Type',  type: 'select', default: 'burst',
+                options: [['burst','Burst'],['sparkle','Sparkle'],['trail','Trail']]},
+            {name: 'colour',     label: 'Colour theme', type: 'select', default: 'rainbow',
+                options: [['rainbow','Rainbow'],['primary','Primary'],['info','Info'],['success','Success'],['warning','Warning'],['danger','Danger']]},
+            {name: 'size',       label: 'Size', type: 'select', default: 'md',
+                options: [['sm','Small'],['md','Medium'],['lg','Large']]},
+            {name: 'continuous', label: 'Continuous',  type: 'checkbox', default: false},
+            {name: 'hover',      label: 'On hover only', type: 'checkbox', default: false},
+        ],
+        hosts: [],
+        previewable: true,
+    },
+    {
+        name: 'fireworks',
+        label: 'Fireworks show',
+        category: 'Celebrations',
+        description: 'A container with multiple firework particles inside.',
+        attrs: [],
+        hosts: [],
+        previewable: false, // container of children - preview via individual fireworks
+    },
+    {
+        name: 'celebrate',
+        label: 'Celebrate',
+        category: 'Celebrations',
+        description: 'Canvas-based seasonal particle system. Runs full-page on the published site.',
+        attrs: [
+            {name: 'theme', label: 'Theme', type: 'select', default: 'auto',
+                options: [
+                    ['auto','Auto (date-detected)'],['christmas','Christmas'],['halloween','Halloween'],
+                    ['valentines','Valentines'],['guy-fawkes','Guy Fawkes'],['st-patricks',"St Patrick's"],
+                    ['st-davids',"St David's"],['st-georges',"St George's"],['st-andrews',"St Andrew's"],
+                ]},
+            {name: 'intensity', label: 'Intensity', type: 'select', default: 'medium',
+                options: [['light','Light'],['medium','Medium'],['heavy','Heavy']]},
+        ],
+        hosts: [],
+        previewable: false, // full-page only
+        selfClosing: true,
+    },
+    {
+        name: 'ticker-tape',
+        label: 'Ticker tape',
+        category: 'Celebrations',
+        description: 'Coloured rectangular strips fall from the top, sway, rotate, and fade. Self-closing for full-page; wrapping form for container-scoped.',
+        attrs: [
+            {name: 'palette', label: 'Palette', type: 'select', default: 'theme',
+                options: [['theme','Theme'],['rainbow','Rainbow'],['gold','Gold'],['silver','Silver'],['festive','Festive'],['pastel','Pastel'],['mono','Mono']]},
+            {name: 'density', label: 'Density', type: 'number', default: 50},
+            {name: 'speed',   label: 'Speed multiplier', type: 'number', default: 1, step: 0.1},
+            {name: 'sway',    label: 'Sway (px)', type: 'number', default: 60},
+            {name: 'burst',   label: 'Burst mode (one-shot)', type: 'checkbox', default: false},
+            {name: 'burst-count', label: 'Burst count', type: 'number', default: 150},
+        ],
+        hosts: ['hero'],
+        previewable: true, // container mode previews; page mode shows static placeholder via opt-out check
+    },
+];
+
+/**
+ * Look up an effect definition by name.
+ *
+ * @param {string} name
+ * @returns {object|null}
+ */
+export function getEffect(name) {
+    return EFFECTS.find(e => e.name === name) || null;
+}
+
+/**
+ * Effects grouped by category, in display order.
+ *
+ * @returns {{category: string, effects: object[]}[]}
+ */
+export function effectsByCategory() {
+    const order = ['Entrance', 'Animation', 'Text', 'Visual', 'Celebrations'];
+    return order.map(cat => ({
+        category: cat,
+        effects: EFFECTS.filter(e => e.category === cat),
+    }));
+}
+
+/**
+ * The list of effects that may be injected into the given host shortcode.
+ *
+ * @param {string} hostName - 'card' | 'hero' | 'banner' | 'col' | 'button'
+ * @returns {object[]}
+ */
+export function effectsInjectableInto(hostName) {
+    return EFFECTS.filter(e => e.hosts.includes(hostName));
+}
+```
+
+- [ ] **Step 2: Syntax check.**
+
+Run: `node --check admin/js/lib/effect-defs.js`
+Expected: no output (clean parse).
+
+- [ ] **Step 3: Smoke test the API.**
+
+Run:
+
+```bash
+node -e "import('./admin/js/lib/effect-defs.js').then(m => {
+  console.log('total:', m.EFFECTS.length);
+  console.log('reveal hosts:', m.getEffect('reveal').hosts);
+  console.log('categories:', m.effectsByCategory().map(c => c.category + '=' + c.effects.length).join(', '));
+  console.log('card-injectable:', m.effectsInjectableInto('card').map(e => e.name).join(', '));
+})"
+```
+
+Expected output:
+```
+total: 14
+reveal hosts: [ 'card', 'hero', 'banner', 'col' ]
+categories: Entrance=1, Animation=4, Text=3, Visual=3, Celebrations=4
+card-injectable: reveal, breathe, pulse, shake, animate, ripple, twinkle, ambient
+```
+
+(Ordering of `card-injectable` reflects the EFFECTS array order, not the matrix table order - both are correct.)
+
+---
+
+### Phase B - User Checkpoint
+
+The catalogue is data-only - no UI behaviour to verify yet. Move on to Phase C when ready.
+
+---
+
+## Phase C - Slideover skeleton
+
+### Task C1: Create `effects-builder.js` with open/close
+
+**Files:**
+- Create: `admin/js/lib/effects-builder.js`
+
+This task gives us a working slideover that opens, displays a placeholder, and closes. Everything else builds on top.
+
+- [ ] **Step 1: Write the skeleton.**
+
+Create `admin/js/lib/effects-builder.js`:
+
+```js
+/**
+ * Effects Builder - unified slideover for inserting, editing, and injecting
+ * Domma effects in the page editor. Replaces the old flat dropdown.
+ *
+ * Public API:
+ *   EffectsBuilder.open(textarea)
+ *
+ * The slideover detects the cursor context inside `textarea` to decide
+ * whether to open in standalone-insert, edit, or inject mode (see the
+ * effects-slideover-overhaul-design spec for details).
+ */
+import {EFFECTS, getEffect, effectsByCategory, effectsInjectableInto} from './effect-defs.js?v=1';
+
+let _current = null;
+
+export const EffectsBuilder = {
+    open(textarea) {
+        if (_current) return;
+        const state = {
+            textarea,
+            activeEffect: S.get('effects-builder-last') || 'reveal',
+            scope: 'standalone',          // 'standalone' | 'inject'
+            host: null,                   // {name, openTagStart, openTagEnd, closeTagStart, closeTagEnd, attrs} when scope = inject
+            editing: null,                // {name, blockStart, blockEnd, openTagEnd, attrs} when editing existing effect
+            fieldValues: {},              // current form values keyed by attr name
+        };
+        const slideover = E.slideover({
+            title: 'Effects',
+            size: 'lg',
+            position: 'right',
+        });
+        const body = _buildLayout(state, slideover);
+        slideover.element.appendChild(body);
+        slideover.open();
+        I.scan(body);
+        _current = {state, slideover};
+    },
+
+    close() {
+        if (_current) {
+            _current.slideover.close();
+            _current = null;
+        }
+    },
+};
+
+function _buildLayout(state, slideover) {
+    const root = document.createElement('div');
+    root.style.cssText = 'display:grid;grid-template-columns:170px 1fr;height:100%;min-height:520px;';
+
+    const rail = document.createElement('div');
+    rail.className = 'effects-rail';
+    rail.style.cssText = 'background:var(--dm-surface-subtle,#15152a);border-right:1px solid var(--dm-border,#2a2a40);padding:.5rem .35rem;font-size:.8rem;overflow-y:auto;';
+    rail.textContent = 'Effects rail (filled in C2)';
+
+    const pane = document.createElement('div');
+    pane.className = 'effects-pane';
+    pane.style.cssText = 'padding:1rem;display:flex;flex-direction:column;gap:.75rem;overflow-y:auto;';
+    pane.textContent = 'Effects pane (filled in C3+)';
+
+    root.appendChild(rail);
+    root.appendChild(pane);
+    return root;
+}
+```
+
+- [ ] **Step 2: Syntax check.**
+
+Run: `node --check admin/js/lib/effects-builder.js`
+Expected: no output.
+
+- [ ] **Step 3: Wire a temporary test trigger.**
+
+For C1 we just need a quick way to open the slideover. Don't permanently wire the toolbar yet - that's Task H2. Instead, open the browser dev console once C1 is in place and run:
+
+```js
+import('/admin/js/lib/effects-builder.js?v=1').then(m => m.EffectsBuilder.open(document.getElementById('markdown-editor')));
+```
+
+…to verify the skeleton renders.
+
+- [ ] **Step 4: Browser verification.**
+
+Open `http://192.168.1.4:4096/admin/#/pages` in a browser, edit any page, then run the dev-console snippet above.
+
+Expected: a slideover opens on the right side; left rail shows "Effects rail (filled in C2)"; pane shows "Effects pane (filled in C3+)". Closing with the X or Esc dismisses it.
+
+If the slideover doesn't open: check the dev console for import errors. If it opens but layout is wrong: re-check the inline grid styles. **Do not proceed to C2 until this works in the browser.**
+
+---
+
+### Task C2: Render category rail + effect list
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Add a `_renderRail` function.**
+
+Above `_buildLayout`, add:
+
+```js
+function _renderRail(rail, state, onChange) {
+    rail.replaceChildren();
+    for (const group of effectsByCategory()) {
+        const heading = document.createElement('div');
+        heading.style.cssText = 'color:var(--dm-text-muted,#888);text-transform:uppercase;font-size:.65rem;letter-spacing:.05em;margin:.4rem .35rem .25rem;';
+        heading.textContent = group.category;
+        rail.appendChild(heading);
+
+        for (const effect of group.effects) {
+            const item = document.createElement('button');
+            item.type = 'button';
+            item.dataset.effect = effect.name;
+            item.style.cssText = 'display:block;width:100%;text-align:left;padding:.3rem .5rem;border:none;background:transparent;color:var(--dm-text,#ddd);border-radius:3px;font-size:.8rem;cursor:pointer;margin-bottom:.1rem;';
+            item.textContent = effect.label;
+            if (effect.name === state.activeEffect) {
+                item.style.background = 'var(--dm-primary,#4338ca)';
+                item.style.color = '#fff';
+            }
+            item.addEventListener('click', () => {
+                state.activeEffect = effect.name;
+                S.set('effects-builder-last', effect.name);
+                state.fieldValues = {}; // reset form values when switching
+                _renderRail(rail, state, onChange);
+                onChange();
+            });
+            rail.appendChild(item);
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Add a stub `_renderPane`.**
+
+Above `_renderRail`, add:
+
+```js
+function _renderPane(pane, state, slideover) {
+    const effect = getEffect(state.activeEffect);
+    pane.replaceChildren();
+
+    const heading = document.createElement('h3');
+    heading.style.cssText = 'margin:0;font-size:1rem;color:var(--dm-text,#eee);';
+    heading.textContent = effect.label;
+    pane.appendChild(heading);
+
+    const desc = document.createElement('p');
+    desc.style.cssText = 'margin:0;color:var(--dm-text-muted,#999);font-size:.8rem;line-height:1.4;';
+    desc.textContent = effect.description;
+    pane.appendChild(desc);
+
+    const placeholder = document.createElement('div');
+    placeholder.style.cssText = 'padding:1rem;color:var(--dm-text-muted,#888);font-style:italic;font-size:.8rem;';
+    placeholder.textContent = 'Form fields render in D1.';
+    pane.appendChild(placeholder);
+}
+```
+
+- [ ] **Step 3: Update `_buildLayout` to wire the rail and pane.**
+
+Replace:
+
+```js
+rail.textContent = 'Effects rail (filled in C2)';
+…
+pane.textContent = 'Effects pane (filled in C3+)';
+```
+
+With:
+
+```js
+_renderRail(rail, state, () => _renderPane(pane, state, slideover));
+_renderPane(pane, state, slideover);
+```
+
+- [ ] **Step 4: Syntax check.**
+
+Run: `node --check admin/js/lib/effects-builder.js`
+Expected: clean.
+
+- [ ] **Step 5: Browser verification.**
+
+Reload the admin page (hard reload - Cmd/Ctrl+Shift+R). Open the slideover via the dev console snippet from C1.
+
+Expected:
+- Left rail shows five categories with their effects underneath.
+- The active effect (Reveal by default, or whatever's in `S.get('effects-builder-last')`) is highlighted indigo.
+- Clicking another effect highlights it and updates the right pane's heading and description.
+- Closing and reopening preserves the last-clicked effect.
+
+---
+
+### Phase C - User Checkpoint
+
+The slideover opens, lists every effect in its category, and the user can navigate between them. Form fields, preview, and insert behaviour come next. User commits if happy.
+
+---
+
+## Phase D - Form fields, shortcode preview, insert
+
+### Task D1: Render form fields per active effect
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Add helpers for form controls.**
+
+Inside `effects-builder.js`, above `_renderPane`, add:
+
+```js
+function _makeInput(attr, currentValue) {
+    if (attr.type === 'select') {
+        const sel = document.createElement('select');
+        sel.style.cssText = 'width:100%;padding:.35rem .5rem;background:var(--dm-input-bg,#1a1a1a);border:1px solid var(--dm-border,#333);border-radius:3px;color:var(--dm-text,#eee);font-size:.85rem;';
+        for (const [val, label] of attr.options) {
+            const opt = document.createElement('option');
+            opt.value = val;
+            opt.textContent = label;
+            sel.appendChild(opt);
+        }
+        sel.value = currentValue ?? attr.default ?? '';
+        return sel;
+    }
+    if (attr.type === 'checkbox') {
+        const cb = document.createElement('input');
+        cb.type = 'checkbox';
+        cb.checked = currentValue ?? attr.default ?? false;
+        return cb;
+    }
+    const inp = document.createElement('input');
+    inp.type = attr.type === 'number' ? 'number' : (attr.type === 'colour' ? 'color' : 'text');
+    inp.value = currentValue ?? attr.default ?? '';
+    if (attr.placeholder) inp.placeholder = attr.placeholder;
+    if (attr.type === 'number') {
+        if (attr.min != null) inp.min = attr.min;
+        if (attr.max != null) inp.max = attr.max;
+        if (attr.step != null) inp.step = attr.step;
+    }
+    inp.style.cssText = 'width:100%;padding:.35rem .5rem;background:var(--dm-input-bg,#1a1a1a);border:1px solid var(--dm-border,#333);border-radius:3px;color:var(--dm-text,#eee);font-size:.85rem;';
+    return inp;
+}
+
+function _readInput(input, attr) {
+    if (attr.type === 'checkbox') return input.checked;
+    if (attr.type === 'number')   return input.value === '' ? '' : Number(input.value);
+    return input.value;
+}
+
+function _renderForm(container, state, onFieldChange) {
+    const effect = getEffect(state.activeEffect);
+    container.replaceChildren();
+    if (effect.attrs.length === 0) {
+        const empty = document.createElement('div');
+        empty.style.cssText = 'color:var(--dm-text-muted,#888);font-size:.8rem;font-style:italic;';
+        empty.textContent = 'This effect takes no parameters.';
+        container.appendChild(empty);
+        return;
+    }
+    const grid = document.createElement('div');
+    grid.style.cssText = 'display:grid;grid-template-columns:1fr 1fr;gap:.6rem .7rem;';
+    for (const attr of effect.attrs) {
+        const wrap = document.createElement('div');
+        const lbl = document.createElement('label');
+        lbl.style.cssText = 'display:block;color:var(--dm-text-muted,#888);font-size:.7rem;text-transform:uppercase;letter-spacing:.05em;margin-bottom:.2rem;';
+        lbl.textContent = attr.label;
+        wrap.appendChild(lbl);
+        const input = _makeInput(attr, state.fieldValues[attr.name]);
+        input.addEventListener('input', () => {
+            state.fieldValues[attr.name] = _readInput(input, attr);
+            onFieldChange();
+        });
+        input.addEventListener('change', () => {
+            state.fieldValues[attr.name] = _readInput(input, attr);
+            onFieldChange();
+        });
+        wrap.appendChild(input);
+        if (attr.hint) {
+            const hint = document.createElement('div');
+            hint.style.cssText = 'color:var(--dm-text-muted,#666);font-size:.7rem;margin-top:.15rem;';
+            hint.textContent = attr.hint;
+            wrap.appendChild(hint);
+        }
+        grid.appendChild(wrap);
+    }
+    container.appendChild(grid);
+}
+```
+
+- [ ] **Step 2: Wire form into `_renderPane`.**
+
+Replace the placeholder div in `_renderPane` with:
+
+```js
+const formContainer = document.createElement('div');
+pane.appendChild(formContainer);
+
+_renderForm(formContainer, state, () => {
+    // Rebuild only the preview when fields change (not the form itself -
+    // we'd lose focus on the input the user is typing into).
+});
+```
+
+- [ ] **Step 3: Syntax check.**
+
+Run: `node --check admin/js/lib/effects-builder.js`
+Expected: clean.
+
+- [ ] **Step 4: Browser verification.**
+
+Reload, reopen the slideover. Cycle through every effect in the rail; each should render its parameter form, and the form should reset to defaults when switching effects. Type into a field and verify focus is preserved.
+
+Expected: every effect's form renders without errors. Console clean.
+
+---
+
+### Task D2: Live shortcode preview
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Add `_buildShortcode` and `_renderShortcodePreview`.**
+
+Above `_renderPane`, add:
+
+```js
+function _serialiseAttrs(state, effect) {
+    const parts = [];
+    for (const attr of effect.attrs) {
+        const v = state.fieldValues[attr.name];
+        // Skip values equal to default (keeps shortcode tidy).
+        if (v === undefined || v === '' || v === null) continue;
+        if (v === attr.default) continue;
+        if (attr.type === 'checkbox') {
+            // Booleans: emit 'true' or 'false' explicitly so the parser sees them.
+            parts.push(`${attr.name}="${v ? 'true' : 'false'}"`);
+        } else {
+            parts.push(`${attr.name}="${String(v).replace(/"/g, '&quot;')}"`);
+        }
+    }
+    return parts.join(' ');
+}
+
+function _buildShortcode(state) {
+    const effect = getEffect(state.activeEffect);
+    const attrStr = _serialiseAttrs(state, effect);
+    const space = attrStr ? ' ' : '';
+    if (state.scope === 'inject' && state.host) {
+        // Inject form: rewrite host's opening tag with effect-flag attrs prefixed.
+        // Implemented in F2; preview here just shows the standalone form.
+    }
+    if (effect.selfClosing) {
+        return `[${effect.name}${space}${attrStr} /]`;
+    }
+    return `[${effect.name}${space}${attrStr}]\nContent\n[/${effect.name}]`;
+}
+
+function _renderShortcodePreview(container, state) {
+    container.replaceChildren();
+    const lbl = document.createElement('div');
+    lbl.style.cssText = 'color:var(--dm-text-muted,#888);font-size:.7rem;text-transform:uppercase;letter-spacing:.05em;margin-bottom:.25rem;';
+    lbl.textContent = 'Shortcode (live)';
+    container.appendChild(lbl);
+
+    const pre = document.createElement('pre');
+    pre.style.cssText = 'background:var(--dm-surface-deep,#000);border:1px solid var(--dm-border,#333);padding:.5rem .65rem;border-radius:3px;font-family:var(--dm-font-mono,monospace);font-size:.75rem;color:#7c6af7;line-height:1.5;white-space:pre-wrap;word-break:break-all;margin:0;';
+    pre.textContent = _buildShortcode(state);
+    container.appendChild(pre);
+}
+```
+
+- [ ] **Step 2: Wire shortcode preview into `_renderPane`.**
+
+After the `formContainer` block, add:
+
+```js
+const shortcodeBox = document.createElement('div');
+pane.appendChild(shortcodeBox);
+_renderShortcodePreview(shortcodeBox, state);
+```
+
+And update the form's onChange callback:
+
+```js
+_renderForm(formContainer, state, () => {
+    _renderShortcodePreview(shortcodeBox, state);
+});
+```
+
+- [ ] **Step 3: Syntax check.**
+
+Run: `node --check admin/js/lib/effects-builder.js`
+Expected: clean.
+
+- [ ] **Step 4: Browser verification.**
+
+Reload, reopen the slideover. Pick Reveal. Change Animation to "slide-up". Verify the shortcode preview updates live to `[reveal animation="slide-up"]\nContent\n[/reveal]`. Tick "Loop" on Scribe and verify the preview reflects the boolean.
+
+Expected: every keystroke / change updates the shortcode pane. Defaults are omitted from output.
+
+---
+
+### Task D3: Insert button
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Add Insert button + footer to `_renderPane`.**
+
+Append to the bottom of `_renderPane`:
+
+```js
+const footer = document.createElement('div');
+footer.style.cssText = 'display:flex;gap:.5rem;margin-top:auto;padding-top:.75rem;border-top:1px solid var(--dm-border,#2a2a40);';
+
+const cancel = document.createElement('button');
+cancel.type = 'button';
+cancel.className = 'btn btn-ghost';
+cancel.textContent = 'Cancel';
+cancel.addEventListener('click', () => slideover.close());
+footer.appendChild(cancel);
+
+const insert = document.createElement('button');
+insert.type = 'button';
+insert.className = 'btn btn-primary';
+insert.style.flex = '2';
+insert.textContent = state.editing ? 'Update' : 'Insert effect';
+insert.addEventListener('click', () => {
+    _doInsert(state, slideover);
+});
+footer.appendChild(insert);
+
+pane.appendChild(footer);
+```
+
+Make sure `pane.style.cssText` includes `flex-direction:column` and a `min-height:520px` (already present from C1).
+
+- [ ] **Step 2: Add `_doInsert` and import `insertAtCursor`.**
+
+At the top of `effects-builder.js`, add:
+
+```js
+import {insertAtCursor} from './markdown-toolbar.js?v=13';
+```
+
+(`?v=13` - we're bumping in this commit; see Task H2 below where the importer's `?v=12` becomes `?v=13` for `page-editor.js`.)
+
+Below `_buildShortcode`, add:
+
+```js
+function _doInsert(state, slideover) {
+    const ta = state.textarea;
+    const shortcode = _buildShortcode(state);
+
+    if (state.editing) {
+        // Replace the existing block (F3) - placeholder for now.
+        // For D3, only the standalone-insert path is needed; the editing
+        // path is implemented in Task F3.
+        slideover.close();
+        return;
+    }
+    if (state.scope === 'inject' && state.host) {
+        // Inject mode (F2) - placeholder. F2 implements the rewrite.
+        slideover.close();
+        return;
+    }
+    insertAtCursor(ta, shortcode);
+    ta.dispatchEvent(new Event('input', {bubbles: true}));
+    slideover.close();
+}
+```
+
+- [ ] **Step 3: Syntax check.**
+
+Run: `node --check admin/js/lib/effects-builder.js`
+Expected: clean.
+
+- [ ] **Step 4: Browser verification.**
+
+Reload, reopen the slideover. Pick Reveal, change Animation to "zoom", click Insert. Verify the markdown editor now contains `[reveal animation="zoom"]\nContent\n[/reveal]` at the cursor. Save the page; preview the rendered page; reveal animation should fire on scroll.
+
+This is the first end-to-end smoke: slideover → write shortcode → server renders → effects.js initialises → animation runs.
+
+---
+
+### Phase D - User Checkpoint
+
+The slideover can now insert effects standalone. User commits if happy. The next phase adds cursor awareness (host detection, edit-existing).
+
+---
+
+## Phase E - Cursor-context awareness
+
+### Task E1: Client-side `parseShortcodeAttrs` helper
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+We need a minimal client-side attribute parser to inspect the shortcode the cursor sits inside. Don't import from server modules - admin code is browser-only.
+
+- [ ] **Step 1: Add `_parseAttrs`.**
+
+Above `_serialiseAttrs`, add:
+
+```js
+/**
+ * Minimal shortcode attribute parser. Mirrors the server's
+ * parseShortcodeAttrs for the subset we need.
+ *
+ *   _parseAttrs('title="Hi" reveal reveal-animation="slide-up"')
+ *   → { title: 'Hi', reveal: '', 'reveal-animation': 'slide-up' }
+ *
+ * @param {string} attrStr
+ * @returns {Object<string,string>}
+ */
+function _parseAttrs(attrStr) {
+    const out = {};
+    const re = /(\w[\w-]*)(?:\s*=\s*"([^"]*)"|\s*=\s*'([^']*)'|\s*=\s*(\S+))?/g;
+    for (const m of attrStr.matchAll(re)) {
+        const key = m[1];
+        const val = m[2] ?? m[3] ?? m[4] ?? '';
+        out[key] = val;
+    }
+    return out;
+}
+```
+
+- [ ] **Step 2: Smoke-test the helper.**
+
+This task has no visible browser change yet - just sets up the helper for E2. Verify the syntax is clean:
+
+Run: `node --check admin/js/lib/effects-builder.js`
+Expected: no output.
+
+---
+
+### Task E2: Detect host shortcode at cursor
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Add `_findEnclosingHost`.**
+
+Above `_doInsert`, add:
+
+```js
+const HOST_NAMES = ['card', 'hero', 'banner', 'col', 'button'];
+
+/**
+ * Inspect textarea content around `cursor` and find the innermost host
+ * shortcode that wraps the cursor position, if any.
+ *
+ * @param {HTMLTextAreaElement} ta
+ * @returns {{name: string, openTagStart: number, openTagEnd: number, closeTagStart: number, closeTagEnd: number, attrs: Object}|null}
+ */
+function _findEnclosingHost(ta) {
+    const value = ta.value;
+    const cursor = ta.selectionStart;
+
+    // Walk forward through all open/close tags up to the cursor; track depth.
+    for (const name of HOST_NAMES) {
+        const openRe = new RegExp(`\\[${name}([^\\]]*)\\]`, 'g');
+        const closeRe = new RegExp(`\\[/${name}\\]`, 'g');
+        const events = [];
+        for (const mo of value.matchAll(openRe)) {
+            if (mo.index >= cursor) break;
+            events.push({type: 'open', start: mo.index, end: mo.index + mo[0].length, attrStr: mo[1]});
+        }
+        for (const mc of value.matchAll(closeRe)) {
+            if (mc.index >= cursor) break;
+            events.push({type: 'close', start: mc.index, end: mc.index + mc[0].length});
+        }
+        events.sort((a, b) => a.start - b.start);
+        let depth = 0;
+        let lastOpen = null;
+        for (const ev of events) {
+            if (ev.type === 'open') {
+                depth++;
+                lastOpen = ev;
+            } else {
+                depth--;
+                if (depth < 0) { depth = 0; lastOpen = null; }
+            }
+        }
+        if (depth > 0 && lastOpen) {
+            // Find matching close tag *after* cursor.
+            const after = new RegExp(`\\[/${name}\\]`, 'g');
+            const tail = value.slice(cursor);
+            const cm = tail.match(after);
+            if (cm) {
+                const closeStart = cursor + tail.indexOf(cm[0]);
+                return {
+                    name,
+                    openTagStart: lastOpen.start,
+                    openTagEnd: lastOpen.end,
+                    closeTagStart: closeStart,
+                    closeTagEnd: closeStart + cm[0].length,
+                    attrs: _parseAttrs(lastOpen.attrStr),
+                };
+            }
+        }
+    }
+    return null;
+}
+```
+
+This is intentionally simple. It does not handle pathological cases (unclosed tags, code fences containing shortcode-like text). For pages where it fails, the user just sees scope = Standalone and proceeds. No errors thrown.
+
+- [ ] **Step 2: Wire detection into `open()`.**
+
+In `EffectsBuilder.open`, after building `state` and **before** `E.slideover(...)`, add:
+
+```js
+state.host = _findEnclosingHost(textarea);
+if (state.host) {
+    // Default to inject if cursor is inside a compatible host that
+    // doesn't yet have this effect injected. Otherwise standalone.
+    const compat = effectsInjectableInto(state.host.name).map(e => e.name);
+    if (compat.includes(state.activeEffect) && !(state.activeEffect in state.host.attrs)) {
+        state.scope = 'inject';
+    }
+}
+```
+
+- [ ] **Step 3: Smoke test in dev console.**
+
+Reload. Edit a page that contains:
+
+```markdown
+[card title="Hello"]
+Body content.
+[/card]
+```
+
+Position the cursor inside the body. Run:
+
+```js
+import('/admin/js/lib/effects-builder.js?v=1').then(m => m.EffectsBuilder.open(document.getElementById('markdown-editor')));
+```
+
+The slideover opens. State is internal; in F1 the Scope toggle UI will visualise this.
+
+For now, manual verification: temporarily add `console.log('host:', state.host)` to `EffectsBuilder.open` after `_findEnclosingHost`, reload, place cursor inside the card body, reopen, and confirm the console logs `host: { name: 'card', … }`. Place cursor outside the card and confirm `host: null`. Remove the `console.log` once verified.
+
+---
+
+### Task E3: Detect existing effect at cursor
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+Same idea as E2 but for effect blocks instead of host shortcodes. When the cursor is inside `[reveal …]…[/reveal]`, we want to populate fields and switch to Update mode.
+
+- [ ] **Step 1: Add `_findEnclosingEffect`.**
+
+Above `_findEnclosingHost`, add:
+
+```js
+const EFFECT_BLOCK_NAMES = EFFECTS.filter(e => !e.selfClosing).map(e => e.name);
+
+/**
+ * Find the effect-block shortcode wrapping the cursor, if any.
+ *
+ * @param {HTMLTextAreaElement} ta
+ * @returns {{name: string, blockStart: number, blockEnd: number, openTagEnd: number, attrs: Object}|null}
+ */
+function _findEnclosingEffect(ta) {
+    const value = ta.value;
+    const cursor = ta.selectionStart;
+    for (const name of EFFECT_BLOCK_NAMES) {
+        const openRe = new RegExp(`\\[${name}([^\\]]*)\\]`, 'g');
+        const closeRe = new RegExp(`\\[/${name}\\]`, 'g');
+        const events = [];
+        for (const mo of value.matchAll(openRe)) {
+            if (mo.index >= cursor) break;
+            events.push({type: 'open', start: mo.index, end: mo.index + mo[0].length, attrStr: mo[1]});
+        }
+        for (const mc of value.matchAll(closeRe)) {
+            if (mc.index >= cursor) break;
+            events.push({type: 'close', start: mc.index, end: mc.index + mc[0].length});
+        }
+        events.sort((a, b) => a.start - b.start);
+        let depth = 0;
+        let lastOpen = null;
+        for (const ev of events) {
+            if (ev.type === 'open') { depth++; lastOpen = ev; }
+            else { depth--; if (depth < 0) { depth = 0; lastOpen = null; } }
+        }
+        if (depth > 0 && lastOpen) {
+            const after = new RegExp(`\\[/${name}\\]`, 'g');
+            const tail = value.slice(cursor);
+            const cm = tail.match(after);
+            if (cm) {
+                const closeStart = cursor + tail.indexOf(cm[0]);
+                return {
+                    name,
+                    blockStart: lastOpen.start,
+                    blockEnd: closeStart + cm[0].length,
+                    openTagEnd: lastOpen.end,
+                    attrs: _parseAttrs(lastOpen.attrStr),
+                };
+            }
+        }
+    }
+    return null;
+}
+```
+
+- [ ] **Step 2: Wire detection into `open()`.**
+
+After the `state.host = …` block in `EffectsBuilder.open`, add:
+
+```js
+state.editing = _findEnclosingEffect(textarea);
+if (state.editing) {
+    state.activeEffect = state.editing.name;
+    state.scope = 'standalone';
+    // Populate fieldValues from existing attrs; coerce to expected types.
+    const effect = getEffect(state.editing.name);
+    for (const attr of effect.attrs) {
+        if (attr.name in state.editing.attrs) {
+            const raw = state.editing.attrs[attr.name];
+            if (attr.type === 'number')   state.fieldValues[attr.name] = Number(raw);
+            else if (attr.type === 'checkbox') state.fieldValues[attr.name] = raw === 'true';
+            else                            state.fieldValues[attr.name] = raw;
+        }
+    }
+}
+```
+
+(Edit-mode detection wins over host-injection: if the cursor is inside both `[card]` and a nested `[reveal]`, edit the inner reveal, not inject onto the card.)
+
+- [ ] **Step 3: Smoke verify.**
+
+Reload, edit a page containing:
+
+```markdown
+[reveal animation="zoom" duration="800"]
+Existing content.
+[/reveal]
+```
+
+Position cursor inside the reveal body. Open the slideover via the dev console snippet. Expected:
+- The active effect in the rail is Reveal.
+- Animation field is "zoom"; Duration is 800.
+- The Insert button label shows "Update" (we set this in D3 via `state.editing ? 'Update' : 'Insert effect'`).
+
+Note: actually performing the update is implemented in F3.
+
+---
+
+### Phase E - User Checkpoint
+
+Cursor awareness works internally but isn't yet visible in the UI (no scope toggle, no functional inject/update). User commits if the smoke checks pass.
+
+---
+
+## Phase F - Inject and edit modes
+
+### Task F1: Scope toggle UI
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Add `_renderScopeToggle`.**
+
+Above `_renderPane`, add:
+
+```js
+function _renderScopeToggle(container, state, onChange) {
+    container.replaceChildren();
+    if (state.editing) return; // No scope toggle in edit mode.
+
+    const effect = getEffect(state.activeEffect);
+    const compatible = state.host && effect.hosts.includes(state.host.name);
+
+    const wrap = document.createElement('div');
+    wrap.style.cssText = 'background:var(--dm-surface-subtle,#15152a);border:1px solid var(--dm-border,#2a2a40);border-radius:4px;padding:.5rem .6rem;';
+
+    const lbl = document.createElement('div');
+    lbl.style.cssText = 'color:var(--dm-text-muted,#888);text-transform:uppercase;font-size:.65rem;letter-spacing:.05em;margin-bottom:.3rem;';
+    lbl.textContent = 'Apply as';
+    wrap.appendChild(lbl);
+
+    if (!compatible) {
+        const note = document.createElement('div');
+        note.style.cssText = 'color:var(--dm-text-muted,#888);font-size:.75rem;font-style:italic;';
+        if (state.host) {
+            note.textContent = `Inserted as a standalone block (${effect.label} cannot be injected into [${state.host.name}]).`;
+        } else {
+            note.textContent = 'Inserted as a standalone block.';
+        }
+        wrap.appendChild(note);
+        container.appendChild(wrap);
+        state.scope = 'standalone';
+        return;
+    }
+
+    const row = document.createElement('div');
+    row.style.cssText = 'display:flex;gap:.3rem;';
+    function makeBtn(scope, label) {
+        const b = document.createElement('button');
+        b.type = 'button';
+        b.style.cssText = `flex:1;padding:.35rem;border:1px solid var(--dm-border,#333);border-radius:3px;font-size:.75rem;font-weight:600;cursor:pointer;`;
+        if (state.scope === scope) {
+            b.style.background = 'var(--dm-primary,#4338ca)';
+            b.style.color = '#fff';
+            b.style.borderColor = 'var(--dm-primary,#4338ca)';
+        } else {
+            b.style.background = 'transparent';
+            b.style.color = 'var(--dm-text-muted,#bbb)';
+        }
+        b.textContent = label;
+        b.addEventListener('click', () => {
+            state.scope = scope;
+            onChange();
+        });
+        return b;
+    }
+    row.appendChild(makeBtn('standalone', 'Standalone block'));
+    row.appendChild(makeBtn('inject', `Inject into [${state.host.name}]`));
+    wrap.appendChild(row);
+    container.appendChild(wrap);
+}
+```
+
+- [ ] **Step 2: Update `_renderPane` to include the scope toggle and a single rerender helper.**
+
+Replace the body of `_renderPane` with:
+
+```js
+function _renderPane(pane, state, slideover) {
+    const effect = getEffect(state.activeEffect);
+    pane.replaceChildren();
+
+    const heading = document.createElement('h3');
+    heading.style.cssText = 'margin:0;font-size:1rem;color:var(--dm-text,#eee);';
+    heading.textContent = effect.label;
+    pane.appendChild(heading);
+
+    const desc = document.createElement('p');
+    desc.style.cssText = 'margin:0;color:var(--dm-text-muted,#999);font-size:.8rem;line-height:1.4;';
+    desc.textContent = effect.description;
+    pane.appendChild(desc);
+
+    const scopeBox = document.createElement('div');
+    pane.appendChild(scopeBox);
+
+    const formContainer = document.createElement('div');
+    pane.appendChild(formContainer);
+
+    const shortcodeBox = document.createElement('div');
+    pane.appendChild(shortcodeBox);
+
+    function rerenderAll() {
+        _renderScopeToggle(scopeBox, state, rerenderAll);
+        _renderForm(formContainer, state, () => {
+            _renderShortcodePreview(shortcodeBox, state);
+        });
+        _renderShortcodePreview(shortcodeBox, state);
+    }
+    rerenderAll();
+
+    const footer = document.createElement('div');
+    footer.style.cssText = 'display:flex;gap:.5rem;margin-top:auto;padding-top:.75rem;border-top:1px solid var(--dm-border,#2a2a40);';
+    const cancel = document.createElement('button');
+    cancel.type = 'button';
+    cancel.className = 'btn btn-ghost';
+    cancel.textContent = 'Cancel';
+    cancel.addEventListener('click', () => slideover.close());
+    footer.appendChild(cancel);
+    const insert = document.createElement('button');
+    insert.type = 'button';
+    insert.className = 'btn btn-primary';
+    insert.style.flex = '2';
+    insert.textContent = state.editing ? 'Update' : 'Insert effect';
+    insert.addEventListener('click', () => _doInsert(state, slideover));
+    footer.appendChild(insert);
+    pane.appendChild(footer);
+}
+```
+
+- [ ] **Step 3: Update `_buildShortcode` to render an inject preview.**
+
+Replace `_buildShortcode` with:
+
+```js
+function _buildShortcode(state) {
+    const effect = getEffect(state.activeEffect);
+    const attrStr = _serialiseAttrs(state, effect);
+    const space = attrStr ? ' ' : '';
+
+    if (state.scope === 'inject' && state.host) {
+        // Inject form: rewrite host opening tag.
+        const hostAttrs = state.host.attrs;
+        const flag = effect.name;
+        const hostParts = [];
+        for (const k of Object.keys(hostAttrs)) {
+            // Skip any pre-existing flags/prefixed attrs for this effect (we replace).
+            if (k === flag) continue;
+            if (k.startsWith(flag + '-')) continue;
+            const v = hostAttrs[k];
+            hostParts.push(v === '' ? k : `${k}="${String(v).replace(/"/g, '&quot;')}"`);
+        }
+        hostParts.push(flag);
+        for (const attr of effect.attrs) {
+            const v = state.fieldValues[attr.name];
+            if (v === undefined || v === '' || v === null || v === attr.default) continue;
+            const stringified = attr.type === 'checkbox' ? (v ? 'true' : 'false') : String(v).replace(/"/g, '&quot;');
+            hostParts.push(`${flag}-${attr.name}="${stringified}"`);
+        }
+        return `[${state.host.name} ${hostParts.join(' ')}]…[/${state.host.name}]`;
+    }
+
+    if (effect.selfClosing) {
+        return `[${effect.name}${space}${attrStr} /]`;
+    }
+    return `[${effect.name}${space}${attrStr}]\nContent\n[/${effect.name}]`;
+}
+```
+
+(The `…` is intentional placeholder text in the inject preview - the user is shown that the host's body is preserved verbatim. The actual insertion in F2 splices the new opening tag in without touching the body.)
+
+- [ ] **Step 4: Update the rail click handler to trigger the new rerender.**
+
+In `_buildLayout`, change:
+
+```js
+_renderRail(rail, state, () => _renderPane(pane, state, slideover));
+_renderPane(pane, state, slideover);
+```
+
+to:
+
+```js
+function rerenderPane() { _renderPane(pane, state, slideover); }
+_renderRail(rail, state, rerenderPane);
+rerenderPane();
+```
+
+- [ ] **Step 5: Browser verification.**
+
+Reload, edit a page with `[card title="Hi"]Body[/card]`, position cursor inside the body, open the slideover. Expected:
+
+- An "Apply as" box appears between the description and the form.
+- Two buttons: *Standalone block* and *Inject into [card]*. *Inject* highlighted (default, since reveal is compatible).
+- Click *Standalone* → preview switches to `[reveal …]…[/reveal]`.
+- Click *Inject into [card]* → preview becomes `[card title="Hi" reveal reveal-animation="..."]…[/card]`.
+
+For an effect that doesn't accept the current host (e.g. switch to Twinkle while inside `[banner]`): the toggle disappears and an italic note explains.
+
+---
+
+### Task F2: Inject mode insert
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Implement the inject branch in `_doInsert`.**
+
+Replace the `if (state.scope === 'inject' && state.host)` placeholder block with:
+
+```js
+if (state.scope === 'inject' && state.host) {
+    const effect = getEffect(state.activeEffect);
+    const value = ta.value;
+    const before = value.substring(0, state.host.openTagStart);
+    const after  = value.substring(state.host.openTagEnd);
+
+    // Reuse the inject preview's host-tag construction. Build the new host
+    // open tag (no body placeholder).
+    const hostAttrs = state.host.attrs;
+    const flag = effect.name;
+    const hostParts = [];
+    for (const k of Object.keys(hostAttrs)) {
+        if (k === flag) continue;
+        if (k.startsWith(flag + '-')) continue;
+        const v = hostAttrs[k];
+        hostParts.push(v === '' ? k : `${k}="${String(v).replace(/"/g, '&quot;')}"`);
+    }
+    hostParts.push(flag);
+    for (const attr of effect.attrs) {
+        const v = state.fieldValues[attr.name];
+        if (v === undefined || v === '' || v === null || v === attr.default) continue;
+        const stringified = attr.type === 'checkbox' ? (v ? 'true' : 'false') : String(v).replace(/"/g, '&quot;');
+        hostParts.push(`${flag}-${attr.name}="${stringified}"`);
+    }
+    const newOpenTag = `[${state.host.name} ${hostParts.join(' ')}]`;
+
+    ta.value = before + newOpenTag + after;
+    // Keep the cursor inside the host body after rewrite.
+    const newCursor = before.length + newOpenTag.length;
+    ta.selectionStart = ta.selectionEnd = newCursor;
+    ta.dispatchEvent(new Event('input', {bubbles: true}));
+    slideover.close();
+    return;
+}
+```
+
+- [ ] **Step 2: Browser verification.**
+
+Reload. Page contents:
+
+```markdown
+[card title="Hi"]
+Body
+[/card]
+```
+
+Cursor inside Body. Open slideover. Pick Reveal, scope = Inject, animation = slide-up. Click Insert.
+
+Expected: editor now reads:
+
+```markdown
+[card title="Hi" reveal reveal-animation="slide-up"]
+Body
+[/card]
+```
+
+Save the page. Visit it on the public site. The card should slide up on scroll.
+
+---
+
+### Task F3: Edit-existing replace
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Implement the editing branch in `_doInsert`.**
+
+Replace the editing placeholder with:
+
+```js
+if (state.editing) {
+    const effect = getEffect(state.editing.name);
+    const value = ta.value;
+    const before = value.substring(0, state.editing.blockStart);
+    const after  = value.substring(state.editing.blockEnd);
+
+    // Preserve the existing body verbatim (everything between openTagEnd
+    // and the close tag start = blockEnd - close tag length).
+    const closeTagLen = `[/${effect.name}]`.length;
+    const bodyStart = state.editing.openTagEnd;
+    const bodyEnd = state.editing.blockEnd - closeTagLen;
+    const body = value.substring(bodyStart, bodyEnd);
+
+    const attrStr = _serialiseAttrs(state, effect);
+    const space = attrStr ? ' ' : '';
+    const newBlock = effect.selfClosing
+        ? `[${effect.name}${space}${attrStr} /]`
+        : `[${effect.name}${space}${attrStr}]${body}[/${effect.name}]`;
+
+    ta.value = before + newBlock + after;
+    // Place cursor just after the new opening tag.
+    const openTagEnd = effect.selfClosing
+        ? before.length + newBlock.length
+        : before.length + newBlock.indexOf(']') + 1;
+    ta.selectionStart = ta.selectionEnd = openTagEnd;
+    ta.dispatchEvent(new Event('input', {bubbles: true}));
+    slideover.close();
+    return;
+}
+```
+
+- [ ] **Step 2: Browser verification.**
+
+Reload. Page contents:
+
+```markdown
+[reveal animation="fade" duration="600"]
+This will change.
+[/reveal]
+```
+
+Cursor inside the body. Open slideover. Verify:
+- Active effect is Reveal.
+- Animation = "fade" (populated).
+- Duration = 600 (populated).
+- Insert button reads "Update".
+
+Change Animation to "zoom", Duration to 1200. Click Update.
+
+Expected:
+
+```markdown
+[reveal animation="zoom" duration="1200"]
+This will change.
+[/reveal]
+```
+
+The body is preserved verbatim. Save and verify the published page now zooms instead of fading.
+
+---
+
+### Phase F - User Checkpoint
+
+All three modes (insert / inject / update) work. User commits. The remaining work is the live render preview and final wiring.
+
+---
+
+## Phase G - Live render preview
+
+### Task G1: Live preview pane (effects flagged previewable)
+
+**Files:**
+- Modify: `admin/js/lib/effects-builder.js`
+
+- [ ] **Step 1: Add `_renderLivePreview` and a camelCase helper.**
+
+Above `_renderPane`, add:
+
+```js
+let _previewSeq = 0;
+
+function _camelKey(s) {
+    return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+function _renderLivePreview(container, state) {
+    container.replaceChildren();
+    const effect = getEffect(state.activeEffect);
+
+    const head = document.createElement('div');
+    head.style.cssText = 'display:flex;justify-content:space-between;align-items:center;margin-bottom:.25rem;';
+    const lbl = document.createElement('div');
+    lbl.style.cssText = 'color:var(--dm-text-muted,#888);text-transform:uppercase;font-size:.65rem;letter-spacing:.05em;';
+    lbl.textContent = 'Live preview';
+    head.appendChild(lbl);
+
+    if (!effect.previewable) {
+        const note = document.createElement('div');
+        note.style.cssText = 'background:var(--dm-surface-subtle,#15152a);border:1px solid var(--dm-border,#2a2a40);border-radius:4px;padding:.6rem;color:var(--dm-text-muted,#888);font-size:.8rem;font-style:italic;text-align:center;';
+        note.textContent = 'Runs full-page on the published site - no inline preview.';
+        container.appendChild(note);
+        return;
+    }
+
+    const replay = document.createElement('button');
+    replay.type = 'button';
+    replay.style.cssText = 'background:transparent;border:1px solid var(--dm-border,#333);color:var(--dm-text-muted,#888);font-size:.65rem;padding:.15rem .4rem;border-radius:2px;cursor:pointer;';
+    replay.textContent = '↻ Replay';
+    head.appendChild(replay);
+    container.appendChild(head);
+
+    const stage = document.createElement('div');
+    stage.style.cssText = 'background:var(--dm-surface-subtle,#1a1a2e);border:1px solid var(--dm-border,#2a2a40);border-radius:4px;padding:1rem;text-align:center;min-height:80px;position:relative;overflow:hidden;';
+    container.appendChild(stage);
+
+    function mount() {
+        _previewSeq++;
+        const seq = _previewSeq;
+        stage.replaceChildren();
+        const sample = document.createElement('div');
+        sample.style.cssText = 'background:linear-gradient(135deg,#6366f1,#a855f7);color:#fff;padding:.6rem;border-radius:4px;font-size:.8rem;font-weight:600;';
+        sample.textContent = 'Sample content';
+        stage.appendChild(sample);
+        const FX = window.Domma && window.Domma.effects;
+        if (!FX) return;
+        const opts = {};
+        for (const attr of effect.attrs) {
+            const v = state.fieldValues[attr.name];
+            if (v === undefined || v === '' || v === null) continue;
+            opts[_camelKey(attr.name)] = v;
+        }
+        try {
+            const fn = FX[_camelKey(effect.name)];
+            if (typeof fn === 'function') {
+                if (seq !== _previewSeq) return; // stale
+                fn(sample, opts);
+            }
+        } catch (err) {
+            console.warn('Effects preview failed:', err);
+        }
+    }
+
+    replay.addEventListener('click', mount);
+    mount();
+}
+```
+
+- [ ] **Step 2: Wire preview into the rerender helper.**
+
+Update `_renderPane`'s `rerenderAll` so it also re-renders the live preview. Add `previewBox` after `shortcodeBox`:
+
+```js
+const shortcodeBox = document.createElement('div');
+pane.appendChild(shortcodeBox);
+
+const previewBox = document.createElement('div');
+pane.appendChild(previewBox);
+
+function rerenderAll() {
+    _renderScopeToggle(scopeBox, state, rerenderAll);
+    _renderForm(formContainer, state, () => {
+        _renderShortcodePreview(shortcodeBox, state);
+        _renderLivePreview(previewBox, state);
+    });
+    _renderShortcodePreview(shortcodeBox, state);
+    _renderLivePreview(previewBox, state);
+}
+rerenderAll();
+```
+
+- [ ] **Step 3: Browser verification.**
+
+Reload. Open the slideover, pick Reveal. The Sample content card should fade/slide as configured. Change Animation; click Replay. The new animation runs.
+
+Try Twinkle: particles animate over the sample. Try Counter: a number animates from 0 to the configured target. Try Celebrate: the static placeholder shows ("Runs full-page on the published site").
+
+Verify there are no console errors when switching between previewable and non-previewable effects.
+
+---
+
+### Phase G - User Checkpoint
+
+The slideover is feature-complete. User commits. Final wiring in Phase H replaces the dropdown handler with the new builder.
+
+---
+
+## Phase H - Final wiring
+
+### Task H1: Remove the old dropdown
+
+**Files:**
+- Modify: `admin/js/lib/markdown-toolbar.js`
+
+- [ ] **Step 1: Delete `effectsMenuItems`.**
+
+Locate the `effectsMenuItems` array (around line 338). Delete it entirely.
+
+- [ ] **Step 2: Delete `openEffectsDropdown`.**
+
+The function starting `function openEffectsDropdown(ta, triggerEl) { …` (around line 364). Delete it including its event-listener attachment for outside-click.
+
+- [ ] **Step 3: Confirm the toolbar click branch only calls the registered handler.**
+
+Find:
+
+```js
+} else if (action === 'effects') {
+    if (handlers.effects) {
+        handlers.effects(ta);
+    }
+}
+```
+
+Confirm it does **not** call `openEffectsDropdown` as a fallback. If it does, remove that fallback. The branch should ONLY call `handlers.effects(ta)`.
+
+- [ ] **Step 4: Syntax check.**
+
+Run: `node --check admin/js/lib/markdown-toolbar.js`
+Expected: clean.
+
+---
+
+### Task H2: Wire `EffectsBuilder.open` into page-editor
+
+**Files:**
+- Modify: `admin/js/views/page-editor.js`
+
+- [ ] **Step 1: Add the import.**
+
+After the existing `import { …createToolbar… } from "../lib/markdown-toolbar.js?v=12";` line (line 8), add:
+
+```js
+import {EffectsBuilder} from "../lib/effects-builder.js?v=1";
+```
+
+- [ ] **Step 2: Bump the markdown-toolbar import.**
+
+Change:
+
+```js
+} from "../lib/markdown-toolbar.js?v=12";
+```
+
+to:
+
+```js
+} from "../lib/markdown-toolbar.js?v=13";
+```
+
+- [ ] **Step 3: Register the handler.**
+
+Locate the existing `V.onHelp(()=>{Ke()})` line. Immediately before it, add:
+
+```js
+V.onEffects(ta => EffectsBuilder.open(ta));
+```
+
+- [ ] **Step 4: Remove any temporary test wiring from C1-G1.**
+
+If you added an inline `import('...').then(m => V.onEffects(...))` block during C1, remove it now. Search the file for `effects-builder` and delete any temporary registration.
+
+- [ ] **Step 5: Syntax check.**
+
+Run: `node --check admin/js/views/page-editor.js`
+Expected: clean.
+
+---
+
+### Task H3: Bump the effects-builder cache-buster on edits
+
+**Files:**
+- (No new edits - this is a discipline note for future revisions to `effects-builder.js`.)
+
+- [ ] **Step 1: Confirm current state.**
+
+Run: `grep -n "effects-builder" admin/js/views/page-editor.js`
+Expected: one line - `import {EffectsBuilder} from "../lib/effects-builder.js?v=1";`
+
+When making future changes to `effects-builder.js`, bump this `?v=1` to `?v=2`, etc., in the same commit. Same convention applies to `effect-defs.js?v=1` if its API or contents change in a way that affects consumers.
+
+---
+
+### Phase H - User Checkpoint
+
+The Effects toolbar button now opens the new slideover. The old dropdown is gone. User commits.
+
+---
+
+## Phase I - Final browser verification
+
+### Task I1: End-to-end smoke checklist
+
+This phase is purely user-driven. Each item is to be performed in a real browser at `http://192.168.1.4:4096/admin`. **Do not mark this plan complete based on server tests alone.**
+
+- [ ] **Standalone insertion** - Edit a page. Click the Effects toolbar button (sparkles icon). Slideover opens. Pick *Reveal*. Animation = "slide-up". Click Insert. Editor now contains a `[reveal animation="slide-up"]…[/reveal]` block. Save. Visit the public page. Reveal animation fires on scroll.
+
+- [ ] **Injection** - Edit a page with an existing `[card title="Hello"]Body[/card]`. Cursor inside the body. Click Effects. Scope toggle appears with *Inject into [card]* highlighted. Pick *Pulse*, scale 1.05. Click Insert. Editor now reads `[card title="Hello" pulse pulse-scale="1.05"]Body[/card]`. Save. Visit the page. The card pulses.
+
+- [ ] **Edit existing** - Edit a page with `[twinkle count="80" colour="#fff"]Body[/twinkle]`. Cursor inside body. Click Effects. Slideover opens on Twinkle, count=80, colour=#fff, button reads "Update". Change count to 150. Click Update. Editor reads `[twinkle count="150" colour="#fff"]Body[/twinkle]`. Save. Visit. Heavier twinkle density.
+
+- [ ] **Reduced-motion** - In Chrome DevTools → More tools → Rendering → Emulate CSS media feature → `prefers-reduced-motion: reduce`. Reload the public page from the previous step. Twinkle should be skipped (effects.js gates it). The slideover preview also skips animation when reduced-motion is on (Domma's effect functions self-gate).
+
+- [ ] **Old dropdown is gone** - Confirm clicking the Effects button never opens a flat dropdown. Confirm the file `admin/js/lib/markdown-toolbar.js` no longer contains the string `effectsMenuItems`.
+
+- [ ] **Cheatsheet preserved** - Visit `/admin/#/effects`. The reference cheatsheet still loads with the Ticker tape section from Phase 1 intact.
+
+- [ ] **No console errors** - Throughout all of the above, the dev console should remain clean. Domma `[effects.tickerTape] Initialised …` info logs are fine.
+
+---
+
+### Phase I - User Checkpoint
+
+Plan complete. User commits the final state if all checks pass.
+
+---
+
+## Self-review notes
+
+(For the implementing engineer - flagged here so the next session has the same context.)
+
+1. **Strict check for cache-buster bumps.** Any time you modify `markdown-toolbar.js`, bump its `?v=N` in `page-editor.js`. Same for `effects-builder.js` and `effect-defs.js`.
+
+2. **Don't restart the server.** The CMS is always running on port 4096. To verify endpoints, just `curl` or visit a URL. Killing the server interrupts the user's other work.
+
+3. **Browser verification is mandatory.** Server-side `node --test` passing does not prove the slideover works. Each browser-verification step in this plan must actually be performed.
+
+4. **The user commits.** This plan deliberately omits `git commit` steps. After each phase, the user reviews the diff and commits when ready.
+
+5. **The `[row]` shortcode is intentionally left untouched.** It already supports its own multi-child reveal logic with `data-reveal-*` attributes (different keyspace from `data-fx-*`). Don't migrate it.
+
+6. **`scribe`, `scramble`, `counter`, `firework`, `fireworks`, `celebrate`** are standalone-only by design. Their `hosts: []` in `effect-defs.js` is correct, not a TODO.
+
+7. **`[hero]`'s `blobs` flag** is preserved in its existing form (it pushes a `bg-ambient-*` CSS class, distinct from the `dm-fx-*` injection mechanism). Do not fold it into the generic helper.