domma-cms 1.6.59 → 1.7.0

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

@@ -0,0 +1,2038 @@
+# Components Area 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:** Add a new "Components" area under the admin **Data** section that lets authors create, edit, and embed Domma Custom Elements on public pages via `.dmc` SFC-style files with live preview.
+
+**Architecture:** Admin-authored `.dmc` files in `content/components/` are compiled on the server to ES modules that register Custom Elements via `Domma.component(tagName, {…})`. Public pages reference them via `[component name="x" …]` shortcodes or raw `<dm-x>` tags; the renderer scans for used components and injects only the scripts that page needs. Admin has a four-tab code editor + iframe-sandboxed live preview, and a slideover "Insert Component" flow in the page editor.
+
+**Tech Stack:** Fastify 5 (ESM, backend), Domma SPA + Domma component factory (admin + public), Node's built-in `node --test` for compiler unit tests, DOMPurify for HTML sanitisation.
+
+**Spec:** `docs/superpowers/specs/2026-04-17-components-area-design.md`
+
+---
+
+## Conventions for the implementer
+
+- **No `git commit` steps.** The user commits separately. Commit boundaries are noted where they make sense but not emitted as shell commands.
+- **Follow existing patterns closely.** The Blocks feature (`server/services/blocks.js`, `server/routes/api/blocks.js`, `admin/js/views/blocks.js`, `admin/js/views/block-editor.js`) is the nearest analogue. When in doubt, mirror Blocks.
+- **Domma framework, not jQuery/vanilla.** Use `$`, `T`, `E`, `F`, `S`, `H`, `I`, `_` as per the existing admin views.
+- **British English in user-facing text.**
+- **Run the server** as it's already running on port 4096; do not start/stop. Use `curl` to hit endpoints.
+- **JSDoc all new exported functions** (the project's convention).
+
+---
+
+## File structure (maps every task to a file)
+
+### Server (new files)
+
+| File | Responsibility |
+|---|---|
+| `server/services/components.js` | Name validation, `.dmc` parser, compiler, cache, CRUD, seed. |
+| `server/routes/api/components.js` | HTTP surface: list, get, compile, put, delete, export, import, public `/:name.js`. |
+| `content/components/` | Seeded `.dmc` files + `.meta.json` companions. Five starter components. |
+
+### Server (modified)
+
+| File | Change |
+|---|---|
+| `server/server.js` | Register components route; `await seedDefaultComponents()` on startup. |
+| `server/services/markdown.js` | New `collectComponents()` pass; DOMPurify tag + attribute allowlist. |
+| `server/services/renderer.js` | Inject per-page `<script type="module">` tags into `bodyEndInject`. |
+| `server/services/permissionRegistry.js` | Add `components` resource. |
+| `server/services/hooks.js` | Add `registerComponent` hook. |
+| `public/css/site.css` | Add `:not(:defined) { visibility: hidden; }`. |
+
+### Admin (new files)
+
+| File | Responsibility |
+|---|---|
+| `admin/preview/component-preview.html` | Static iframe bootstrap. Loads Domma, listens for `postMessage`, mounts the component. |
+| `admin/js/views/components.js` | List-view logic. |
+| `admin/js/templates/components.html` | List-view template. |
+| `admin/js/views/component-editor.js` | Editor logic - four tabs + iframe preview. |
+| `admin/js/templates/component-editor.html` | Editor template. |
+
+### Admin (modified)
+
+| File | Change |
+|---|---|
+| `admin/js/api.js` | Add `api.components.{list, get, compile, put, delete, exportBundle, importBundle}`. |
+| `admin/js/views/index.js` | Register `components` + `componentEditor` views. |
+| `admin/js/config/sidebar-config.js` | Sidebar entry under Data. |
+| `admin/js/app.js` | Extend `fetchSidebarCounts()` with `api.components.list()`. |
+| `admin/js/views/page-editor.js` | Add "Insert Component" toolbar button + slideover wiring. |
+
+### Tests (new)
+
+| File | Responsibility |
+|---|---|
+| `tests/components/compile.test.js` | Unit tests for parser + compiler (`node --test`). |
+
+---
+
+# PHASE 1 - Server services and compiler
+
+## Task 1: Components service skeleton
+
+**Files:**
+- Create: `server/services/components.js`
+
+- [ ] **Step 1: Create the service file with constants and name validation**
+
+```js
+/**
+ * Components Service
+ * CRUD, compile pipeline, and seeding for .dmc component files
+ * stored in content/components/.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const COMPONENTS_DIR = path.resolve(__dirname, '../../content/components');
+
+/** Component names: lowercase alphanumeric + hyphens. Drives the Custom Element tag `dm-<name>`. */
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+function assertValidName(name) {
+    if (!NAME_RE.test(name)) {
+        const err = new Error('Invalid component name. Use a letter followed by lowercase letters, digits, and hyphens.');
+        err.code = 'INVALID_NAME';
+        throw err;
+    }
+}
+
+function componentFilePath(name) { return path.join(COMPONENTS_DIR, `${name}.dmc`); }
+function componentMetaPath(name) { return path.join(COMPONENTS_DIR, `${name}.meta.json`); }
+
+export { COMPONENTS_DIR, assertValidName, componentFilePath, componentMetaPath };
+```
+
+- [ ] **Step 2: Add a self-test harness for `assertValidName`**
+
+Append to the end of `server/services/components.js`:
+
+```js
+// eslint-disable-next-line
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const cases = [
+        ['counter', true],
+        ['copy-button', true],
+        ['Counter', false],
+        ['1counter', false],
+        ['', false],
+        ['../etc/passwd', false]
+    ];
+    for (const [name, ok] of cases) {
+        try { assertValidName(name); console.log(ok ? '✓' : '✗', name, '→ valid'); }
+        catch { console.log(ok ? '✗' : '✓', name, '→ invalid'); }
+    }
+}
+```
+
+- [ ] **Step 3: Verify by running it directly**
+
+Run: `node server/services/components.js`
+Expected: six lines all prefixed `✓`.
+
+---
+
+## Task 2: Block parser - split `.dmc` into four parts
+
+**Files:**
+- Modify: `server/services/components.js`
+- Create: `tests/components/compile.test.js`
+
+- [ ] **Step 1: Write a failing parser test**
+
+Create `tests/components/compile.test.js`:
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {parseDmcSource} from '../../server/services/components.js';
+
+test('parseDmcSource splits the four blocks', () => {
+    const src = `<template>
+<div>{{count}}</div>
+</template>
+<props>
+{ "x": {"type":"number","default":0} }
+</props>
+<script>
+export default { data() { return { count: 1 }; } };
+</script>
+<style>
+div { color: red; }
+</style>`;
+    const {template, props, script, style} = parseDmcSource(src);
+    assert.match(template, /<div>\{\{count\}\}<\/div>/);
+    assert.match(props,    /"type":"number"/);
+    assert.match(script,   /export default/);
+    assert.match(style,    /color: red/);
+});
+
+test('parseDmcSource tolerates missing <style>', () => {
+    const src = `<template>x</template><props>{}</props><script>export default {};</script>`;
+    const {style} = parseDmcSource(src);
+    assert.equal(style, '');
+});
+
+test('parseDmcSource throws on missing <template>', () => {
+    const src = `<props>{}</props><script>export default {};</script>`;
+    assert.throws(() => parseDmcSource(src), /MISSING_BLOCK/);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/components/compile.test.js`
+Expected: all three tests FAIL with `parseDmcSource is not a function`.
+
+- [ ] **Step 3: Implement the parser in `server/services/components.js`**
+
+Add below the existing helpers:
+
+```js
+/**
+ * Split a .dmc source string into its four SFC blocks.
+ * Missing <template>, <props>, or <script> is a compile error;
+ * <style> is optional (returns '').
+ *
+ * @param {string} source
+ * @returns {{template: string, props: string, script: string, style: string}}
+ * @throws {Error} With code MISSING_BLOCK when a required block is absent.
+ */
+export function parseDmcSource(source) {
+    const extract = (tag) => {
+        const re = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`);
+        const m = source.match(re);
+        return m ? m[1].trim() : null;
+    };
+    const template = extract('template');
+    const props    = extract('props');
+    const script   = extract('script');
+    const style    = extract('style') ?? '';
+
+    for (const [name, value] of [['template', template], ['props', props], ['script', script]]) {
+        if (value === null) {
+            const err = new Error(`Missing required <${name}> block.`);
+            err.code = 'MISSING_BLOCK';
+            err.block = name;
+            throw err;
+        }
+    }
+    return {template, props, script, style};
+}
+```
+
+- [ ] **Step 4: Re-run tests**
+
+Run: `node --test tests/components/compile.test.js`
+Expected: all three PASS.
+
+---
+
+## Task 3: Props schema validator
+
+**Files:**
+- Modify: `server/services/components.js`
+- Modify: `tests/components/compile.test.js`
+
+- [ ] **Step 1: Add failing tests for props validation**
+
+Append to `tests/components/compile.test.js`:
+
+```js
+import {validatePropsJson} from '../../server/services/components.js';
+
+test('validatePropsJson parses valid schema', () => {
+    const p = validatePropsJson('{"x": {"type":"number","default":0}}');
+    assert.equal(p.x.type, 'number');
+});
+
+test('validatePropsJson rejects invalid JSON', () => {
+    assert.throws(() => validatePropsJson('{not json'), /INVALID_PROPS_JSON/);
+});
+
+test('validatePropsJson rejects missing type', () => {
+    assert.throws(() => validatePropsJson('{"x": {"default": 0}}'), /INVALID_PROPS_JSON/);
+});
+
+test('validatePropsJson rejects unknown type', () => {
+    assert.throws(() => validatePropsJson('{"x": {"type":"bigint"}}'), /INVALID_PROPS_JSON/);
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `node --test tests/components/compile.test.js`
+Expected: four new tests FAIL.
+
+- [ ] **Step 3: Implement `validatePropsJson`**
+
+Add to `server/services/components.js`:
+
+```js
+const VALID_PROP_TYPES = new Set(['string', 'number', 'boolean', 'array', 'object']);
+
+/**
+ * Parse and validate a <props> block JSON body.
+ *
+ * @param {string} json
+ * @returns {object} Parsed props schema.
+ * @throws {Error} With code INVALID_PROPS_JSON on any problem.
+ */
+export function validatePropsJson(json) {
+    let parsed;
+    try { parsed = JSON.parse(json); }
+    catch (e) {
+        const err = new Error(`<props> is not valid JSON: ${e.message}`);
+        err.code = 'INVALID_PROPS_JSON';
+        throw err;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        const err = new Error('<props> must be a JSON object');
+        err.code = 'INVALID_PROPS_JSON';
+        throw err;
+    }
+    for (const [propName, def] of Object.entries(parsed)) {
+        if (!def || typeof def !== 'object' || !VALID_PROP_TYPES.has(def.type)) {
+            const err = new Error(`<props>.${propName} must declare a valid type (one of: ${[...VALID_PROP_TYPES].join(', ')})`);
+            err.code = 'INVALID_PROPS_JSON';
+            throw err;
+        }
+    }
+    return parsed;
+}
+```
+
+- [ ] **Step 4: Re-run tests**
+
+Run: `node --test tests/components/compile.test.js`
+Expected: all tests PASS.
+
+---
+
+## Task 4: `<script>` body transform (⚠️ USER CONTRIBUTION OPPORTUNITY)
+
+**Files:**
+- Modify: `server/services/components.js`
+- Modify: `tests/components/compile.test.js`
+
+> **★ Learning-mode note for the human in the loop ★**
+>
+> This function is a small but genuinely interesting decision point and a great place for the user to contribute ~10 lines of meaningful code.
+>
+> **What it has to do:** take a `<script>` body like
+>
+> ```js
+> export default { data() { return { count: 1 }; }, methods: { inc() {…} } };
+> ```
+>
+> and return just the object expression (no `export default`, no trailing semicolon) so the compiler can embed it as:
+>
+> ```js
+> const definition = { data() { return { count: 1 }; }, methods: { inc() {…} } };
+> ```
+>
+> **Trade-offs worth weighing:**
+> - **Regex approach** (5-8 lines): strip the literal `export default` keyword, trim surrounding whitespace, drop a trailing semicolon. Tolerates 95 % of real-world inputs; can be fooled by weird cases (an `export default` inside a string literal or comment at the top of the script - extremely unlikely in practice).
+> - **Indexed scan** (10-15 lines): find the first `export default` keyword that's *not* inside a string or comment by scanning char by char. More robust, more code.
+> - **Full AST parse with acorn** (introduces a dependency): the most correct, but pulls in a parser just for this one transform.
+>
+> **Recommendation:** start with the regex - it's honest, debuggable, and the author population is trusted admins writing ordinary JS. If it ever fails in practice, revisit.
+
+- [ ] **Step 1: Add failing tests**
+
+Append to `tests/components/compile.test.js`:
+
+```js
+import {stripExportDefault} from '../../server/services/components.js';
+
+test('stripExportDefault removes the keyword', () => {
+    const body = `export default { data() { return { count: 1 }; } };`;
+    assert.equal(
+        stripExportDefault(body).trim(),
+        `{ data() { return { count: 1 }; } }`
+    );
+});
+
+test('stripExportDefault handles leading whitespace and trailing semicolon', () => {
+    const body = `\n\n  export default  {x:1}  ;\n`;
+    assert.equal(stripExportDefault(body).trim(), `{x:1}`);
+});
+
+test('stripExportDefault throws when no export default is found', () => {
+    assert.throws(() => stripExportDefault(`const x = 1;`), /SCRIPT_MISSING_EXPORT/);
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `node --test tests/components/compile.test.js`
+Expected: three new tests FAIL.
+
+- [ ] **Step 3: Implement `stripExportDefault` in `server/services/components.js`**
+
+Recommended minimal implementation (user may wish to substitute their own):
+
+```js
+/**
+ * Transform a <script> body for embedding.
+ * Removes the `export default` prefix and any trailing semicolon,
+ * leaving only the object expression.
+ *
+ * @param {string} body - Raw <script> body.
+ * @returns {string} The bare object expression.
+ * @throws {Error} With code SCRIPT_MISSING_EXPORT when no export default is found.
+ */
+export function stripExportDefault(body) {
+    const m = body.match(/^\s*export\s+default\s+([\s\S]+?)\s*;?\s*$/);
+    if (!m) {
+        const err = new Error('<script> must have an `export default` statement');
+        err.code = 'SCRIPT_MISSING_EXPORT';
+        throw err;
+    }
+    return m[1];
+}
+```
+
+- [ ] **Step 4: Re-run tests**
+
+Run: `node --test tests/components/compile.test.js`
+Expected: all tests PASS.
+
+---
+
+## Task 5: Compile function - assemble the JS module
+
+**Files:**
+- Modify: `server/services/components.js`
+- Modify: `tests/components/compile.test.js`
+
+- [ ] **Step 1: Add a failing integration test**
+
+Append to `tests/components/compile.test.js`:
+
+```js
+import {compileComponent} from '../../server/services/components.js';
+
+test('compileComponent produces a self-contained module', () => {
+    const src = `<template><div>{{count}}</div></template>
+<props>{"initial":{"type":"number","default":0}}</props>
+<script>export default { data() { return { count: this.props.initial }; } };</script>
+<style>div { color: red; }</style>`;
+    const {js, errors} = compileComponent(src, 'counter');
+    assert.deepEqual(errors, []);
+    assert.match(js, /const template = /);
+    assert.match(js, /const style = /);
+    assert.match(js, /const props = /);
+    assert.match(js, /const definition = /);
+    assert.match(js, /Domma\.component\('dm-counter'/);
+});
+
+test('compileComponent returns structured errors for bad props', () => {
+    const src = `<template>x</template><props>{not json}</props><script>export default {};</script>`;
+    const {js, errors} = compileComponent(src, 'bad');
+    assert.equal(js, null);
+    assert.equal(errors.length, 1);
+    assert.equal(errors[0].type, 'INVALID_PROPS_JSON');
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `node --test tests/components/compile.test.js`
+Expected: two new tests FAIL.
+
+- [ ] **Step 3: Implement `compileComponent`**
+
+```js
+/**
+ * Escape a string for use inside a JS template literal.
+ * Handles backticks, backslashes, and `${` sequences.
+ */
+function toBacktickLiteral(str) {
+    return '`' + String(str).replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${') + '`';
+}
+
+/**
+ * Compile a .dmc source into a self-contained JS module that registers
+ * the component on load via Domma.component().
+ *
+ * @param {string} source - Full .dmc file contents.
+ * @param {string} name   - Component name (controls the Custom Element tag).
+ * @returns {{js: string|null, errors: Array<{type: string, message: string, block?: string}>}}
+ */
+export function compileComponent(source, name) {
+    try {
+        assertValidName(name);
+    } catch (e) {
+        return {js: null, errors: [{type: e.code, message: e.message}]};
+    }
+
+    let parts;
+    try { parts = parseDmcSource(source); }
+    catch (e) { return {js: null, errors: [{type: e.code, message: e.message, block: e.block}]}; }
+
+    let propsObj;
+    try { propsObj = validatePropsJson(parts.props); }
+    catch (e) { return {js: null, errors: [{type: e.code, message: e.message}]}; }
+
+    let definitionExpr;
+    try { definitionExpr = stripExportDefault(parts.script); }
+    catch (e) { return {js: null, errors: [{type: e.code, message: e.message}]}; }
+
+    const js = [
+        `// Compiled from ${name}.dmc - do not edit by hand.`,
+        `const template = ${toBacktickLiteral(parts.template)};`,
+        `const style    = ${toBacktickLiteral(parts.style)};`,
+        `const props    = ${JSON.stringify(propsObj)};`,
+        `const definition = ${definitionExpr};`,
+        `Domma.component('dm-${name}', { template, style, props, ...definition });`
+    ].join('\n');
+
+    return {js, errors: []};
+}
+```
+
+- [ ] **Step 4: Re-run tests**
+
+Run: `node --test tests/components/compile.test.js`
+Expected: all tests PASS.
+
+---
+
+## Task 6: In-memory compile cache
+
+**Files:**
+- Modify: `server/services/components.js`
+
+- [ ] **Step 1: Add the cache primitives**
+
+```js
+const _compileCache = new Map();  // name → {js, mtime}
+
+/** Drop a cached compiled output - called on save/delete. */
+export function invalidateCache(name) { _compileCache.delete(name); }
+
+/**
+ * Return compiled JS for `name`, reading + compiling lazily if not cached.
+ * Returns { js, mtime } on success, or { errors, mtime } on compile failure.
+ */
+export async function getCompiledJs(name) {
+    assertValidName(name);
+    const fp = componentFilePath(name);
+    const stat = await fs.stat(fp);
+    const cached = _compileCache.get(name);
+    if (cached && cached.mtime === stat.mtimeMs) return cached;
+    const source = await fs.readFile(fp, 'utf8');
+    const {js, errors} = compileComponent(source, name);
+    const entry = {js, errors, mtime: stat.mtimeMs};
+    _compileCache.set(name, entry);
+    return entry;
+}
+```
+
+- [ ] **Step 2: Smoke test by writing a throwaway file and calling the function**
+
+```bash
+mkdir -p /home/darryl/src/js/domma-cms/content/components
+cat > /home/darryl/src/js/domma-cms/content/components/__smoke.dmc <<'EOF'
+<template><div>hi</div></template>
+<props>{}</props>
+<script>export default { data() { return {}; } };</script>
+EOF
+node -e "import('/home/darryl/src/js/domma-cms/server/services/components.js').then(m=>m.getCompiledJs('__smoke').then(r=>console.log(r.js.slice(0,80))))"
+rm /home/darryl/src/js/domma-cms/content/components/__smoke.dmc
+```
+
+Expected: output begins with `// Compiled from __smoke.dmc`.
+
+---
+
+## Task 7: CRUD operations (list, get, save, delete)
+
+**Files:**
+- Modify: `server/services/components.js`
+
+- [ ] **Step 1: Implement `listComponents`**
+
+```js
+/**
+ * List all components. Returns lightweight metadata - does NOT compile.
+ * The `props` field is parsed from the <props> block so callers can display
+ * props in the list view without a second fetch.
+ */
+export async function listComponents() {
+    await fs.mkdir(COMPONENTS_DIR, {recursive: true});
+    const files = await fs.readdir(COMPONENTS_DIR);
+    const entries = [];
+    for (const file of files.filter(f => f.endsWith('.dmc'))) {
+        const name = file.slice(0, -4);
+        const stat = await fs.stat(path.join(COMPONENTS_DIR, file)).catch(() => null);
+        let bundled = false;
+        try {
+            const meta = JSON.parse(await fs.readFile(componentMetaPath(name), 'utf8'));
+            bundled = !!meta.bundled;
+        } catch { /* no meta */ }
+        let props = {};
+        try {
+            const src = await fs.readFile(path.join(COMPONENTS_DIR, file), 'utf8');
+            const {props: propsBlock} = parseDmcSource(src);
+            props = validatePropsJson(propsBlock);
+        } catch { /* malformed - list still usable */ }
+        entries.push({
+            name,
+            size: stat?.size ?? 0,
+            updatedAt: stat?.mtime?.toISOString() ?? null,
+            bundled,
+            props
+        });
+    }
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+```
+
+- [ ] **Step 2: Implement `getComponent` (raw source + parsed props)**
+
+```js
+/**
+ * Read a component's raw .dmc source plus parsed props.
+ *
+ * @returns {Promise<{name: string, source: string, props: object, bundled: boolean}>}
+ */
+export async function getComponent(name) {
+    assertValidName(name);
+    try {
+        const source = await fs.readFile(componentFilePath(name), 'utf8');
+        let bundled = false;
+        try {
+            const meta = JSON.parse(await fs.readFile(componentMetaPath(name), 'utf8'));
+            bundled = !!meta.bundled;
+        } catch { /* no meta */ }
+        let props = {};
+        try {
+            const parts = parseDmcSource(source);
+            props = validatePropsJson(parts.props);
+        } catch { /* return malformed source for editing; UI will flag */ }
+        return {name, source, props, bundled};
+    } catch (err) {
+        if (err.code === 'ENOENT') {
+            const nf = new Error('Component not found'); nf.code = 'ENOENT'; throw nf;
+        }
+        throw err;
+    }
+}
+```
+
+- [ ] **Step 3: Implement `saveComponent` - compiles before writing**
+
+```js
+/**
+ * Create or update a component. Compiles BEFORE writing - a malformed
+ * source never reaches disk. Returns the compile errors if any.
+ *
+ * @returns {Promise<{success: boolean, name: string, errors: Array}>}
+ */
+export async function saveComponent(name, source, {bundled = false} = {}) {
+    assertValidName(name);
+    const {errors} = compileComponent(source, name);
+    if (errors.length) return {success: false, name, errors};
+
+    await fs.mkdir(COMPONENTS_DIR, {recursive: true});
+    await fs.writeFile(componentFilePath(name), source, 'utf8');
+    const metaPath = componentMetaPath(name);
+    if (bundled) await fs.writeFile(metaPath, JSON.stringify({bundled: true}, null, 2) + '\n', 'utf8');
+    else         await fs.unlink(metaPath).catch(() => {});
+    invalidateCache(name);
+    return {success: true, name, errors: []};
+}
+```
+
+- [ ] **Step 4: Implement `deleteComponent`**
+
+```js
+/**
+ * Delete a component's .dmc + companion .meta.json.
+ * @throws {Error} With code ENOENT when the component is not found.
+ */
+export async function deleteComponent(name) {
+    assertValidName(name);
+    try { await fs.unlink(componentFilePath(name)); }
+    catch (err) {
+        if (err.code === 'ENOENT') { const nf = new Error('Component not found'); nf.code = 'ENOENT'; throw nf; }
+        throw err;
+    }
+    await fs.unlink(componentMetaPath(name)).catch(() => {});
+    invalidateCache(name);
+}
+```
+
+- [ ] **Step 5: Smoke test CRUD via a tiny throwaway script**
+
+```bash
+node -e "
+const m = await import('/home/darryl/src/js/domma-cms/server/services/components.js');
+const src = '<template><div>{{x}}</div></template><props>{\"x\":{\"type\":\"string\",\"default\":\"hi\"}}</props><script>export default { data(){ return { x: this.props.x }; } };</script>';
+await m.saveComponent('__smoke', src);
+console.log('list:', (await m.listComponents()).map(c=>c.name));
+console.log('get:',  (await m.getComponent('__smoke')).name);
+await m.deleteComponent('__smoke');
+console.log('after delete:', (await m.listComponents()).map(c=>c.name));
+"
+```
+
+Expected: `__smoke` present in the list, then absent after delete.
+
+---
+
+## Task 8: Export/import bundle helpers
+
+**Files:**
+- Modify: `server/services/components.js`
+
+- [ ] **Step 1: Add `BUNDLE_FORMAT` constant and helper**
+
+```js
+/** Current .dmcomponent.json bundle schema version. Bump when shape changes. */
+export const BUNDLE_FORMAT = 1;
+
+/** Export a component as a downloadable bundle object. */
+export async function exportBundle(name) {
+    const {source, bundled} = await getComponent(name);
+    return {format: BUNDLE_FORMAT, name, source, bundled};
+}
+
+/**
+ * Import a bundle. On name collision, throws with code CONFLICT
+ * unless overwrite === true.
+ */
+export async function importBundle(bundle, {overwrite = false} = {}) {
+    if (!bundle || typeof bundle !== 'object') { const e = new Error('Invalid bundle'); e.code = 'INVALID_BUNDLE'; throw e; }
+    if (typeof bundle.format !== 'number' || bundle.format > BUNDLE_FORMAT) {
+        const e = new Error(`Unsupported bundle format (${bundle.format})`); e.code = 'INVALID_BUNDLE'; throw e;
+    }
+    if (typeof bundle.name !== 'string' || typeof bundle.source !== 'string') {
+        const e = new Error('Bundle missing name or source'); e.code = 'INVALID_BUNDLE'; throw e;
+    }
+    if (!overwrite) {
+        try { await getComponent(bundle.name); const e = new Error('Component already exists'); e.code = 'CONFLICT'; e.name = bundle.name; throw e; }
+        catch (err) { if (err.code !== 'ENOENT') throw err; }
+    }
+    return saveComponent(bundle.name, bundle.source, {bundled: !!bundle.bundled});
+}
+```
+
+- [ ] **Step 2: Smoke test round-trip**
+
+```bash
+node -e "
+const m = await import('/home/darryl/src/js/domma-cms/server/services/components.js');
+const src = '<template><div>x</div></template><props>{}</props><script>export default {};</script>';
+await m.saveComponent('__rt', src);
+const bundle = await m.exportBundle('__rt');
+await m.deleteComponent('__rt');
+await m.importBundle(bundle);
+console.log('ok:', (await m.getComponent('__rt')).source === src);
+await m.deleteComponent('__rt');
+"
+```
+
+Expected: `ok: true`.
+
+---
+
+## Task 8b: Plugin hook - `registerComponent`
+
+Spec Section 3.4 promises plugins can contribute read-only components. Minimal wiring:
+
+**Files:**
+- Modify: `server/services/hooks.js`
+- Modify: `server/services/components.js`
+
+- [ ] **Step 1: Add the hook registry entry in `hooks.js`**
+
+```js
+// Plugins call registerComponent({ name, source }) during plugin boot.
+const _pluginComponents = new Map();
+
+export function registerComponent({name, source}) {
+    if (typeof name !== 'string' || typeof source !== 'string') return;
+    _pluginComponents.set(name, {name, source, origin: 'plugin'});
+}
+export function getPluginComponents() {
+    return [..._pluginComponents.values()];
+}
+```
+
+Export `registerComponent` from whatever `hooks.js` already exposes to plugins (it should follow the pattern of existing hook exports in that file).
+
+- [ ] **Step 2: Merge plugin components into `listComponents()` in `components.js`**
+
+After building the disk-backed entries, append plugin-contributed ones:
+
+```js
+import {getPluginComponents} from './hooks.js';
+// …at the end of listComponents, before the sort:
+for (const pc of getPluginComponents()) {
+    let props = {};
+    try { props = validatePropsJson(parseDmcSource(pc.source).props); } catch {}
+    entries.push({name: pc.name, size: pc.source.length, updatedAt: null, bundled: true, props, origin: 'plugin'});
+}
+```
+
+- [ ] **Step 3: Route `getCompiledJs` to plugin sources when no file exists**
+
+Inside `getCompiledJs`, before the `fs.stat` call, check the plugin map:
+
+```js
+const plugin = getPluginComponents().find(pc => pc.name === name);
+if (plugin) {
+    const cached = _compileCache.get(name);
+    if (cached && cached.origin === 'plugin' && cached.sourceHash === plugin.source.length) return cached;
+    const {js, errors} = compileComponent(plugin.source, name);
+    const entry = {js, errors, origin: 'plugin', sourceHash: plugin.source.length, mtime: 0};
+    _compileCache.set(name, entry);
+    return entry;
+}
+```
+
+- [ ] **Step 4: Block disk writes to plugin-provided names**
+
+In `saveComponent` and `deleteComponent`, throw `CONFLICT` if a plugin owns the name:
+
+```js
+if (getPluginComponents().some(pc => pc.name === name)) {
+    const e = new Error('That name is registered by a plugin and cannot be edited from the admin.');
+    e.code = 'PLUGIN_OWNED';
+    throw e;
+}
+```
+
+Handle `PLUGIN_OWNED` in the API as a 409.
+
+- [ ] **Step 5: No explicit test - covered by smoke test in Task 25**
+
+---
+
+# PHASE 2 - Permissions and API
+
+## Task 9: Add `components` resource to the permission registry
+
+> **Correction vs spec:** the spec presented permissions as a `resource: {action: [roles]}` map. The actual `permissionRegistry.js` exports `REGISTRY` as an **array of descriptor objects** (see existing `blocks` entry at `permissionRegistry.js:38-50`). Role-to-action mapping lives elsewhere (in the role entries of `content/collections/user-types/`). This task only adds the descriptor so the resource is discoverable by the Roles UI and accepted by `requirePermission()`.
+
+**Files:**
+- Modify: `server/services/permissionRegistry.js`
+
+- [ ] **Step 1: Locate the existing `blocks` entry**
+
+Run: `grep -n "key: 'blocks'" server/services/permissionRegistry.js`
+
+Expected: a single line around `permissionRegistry.js:39`.
+
+- [ ] **Step 2: Add the `components` descriptor directly after `blocks`**
+
+Insert a new entry inside the `REGISTRY` array, matching the existing descriptor shape exactly:
+
+```js
+{
+    key: 'components',
+    label: 'Components',
+    description: 'Manage reusable Domma components.',
+    icon: 'puzzle',
+    group: 'Content',
+    actions: [
+        {key: 'read', label: 'View', description: 'View components'},
+        {key: 'create', label: 'Create', description: 'Create new components'},
+        {key: 'update', label: 'Edit', description: 'Edit existing components'},
+        {key: 'delete', label: 'Delete', description: 'Delete components'}
+    ]
+},
+```
+
+- [ ] **Step 3: Set the default role grants**
+
+Per the spec: super-admin gets all four actions; admin gets `read` only. These live in the seeded role entries - find where the `admin` and `super-admin` role entries are seeded (likely `server/services/userTypes.js` or `config/presets.json`) and add entries. If the seeding is already run, site owners can add the permissions manually via the Roles admin UI.
+
+Run: `grep -rn "'blocks.read'\|blocks.read" server/ config/ | head -10`
+
+Whatever pattern is used for `blocks.*` is what we mirror for `components.*`.
+
+- [ ] **Step 4: Restart + smoke**
+
+After Task 10 is done, verify with:
+
+```bash
+# Replace $TOKEN with an admin JWT.
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:4096/api/auth/permissions | grep -o 'components\.read'
+```
+
+Expected: one match.
+
+---
+
+## Task 10: API routes
+
+**Files:**
+- Create: `server/routes/api/components.js`
+- Modify: `server/server.js` - register route
+
+- [ ] **Step 1: Write the routes file**
+
+Create `server/routes/api/components.js`:
+
+```js
+/**
+ * Components API
+ * CRUD + compilation + export/import for .dmc components.
+ *
+ * GET    /api/components              - list
+ * GET    /api/components/:name        - raw source + parsed props
+ * GET    /api/components/:name.js     - compiled JS module (public)
+ * POST   /api/components/compile      - transient compile for preview
+ * GET    /api/components/:name/export - download .dmcomponent.json
+ * POST   /api/components/import       - import .dmcomponent.json
+ * PUT    /api/components/:name        - create/update (compiles first)
+ * DELETE /api/components/:name        - delete
+ */
+import {authenticate, requirePermission} from '../../middleware/auth.js';
+import {
+    BUNDLE_FORMAT,
+    compileComponent,
+    deleteComponent,
+    exportBundle,
+    getComponent,
+    getCompiledJs,
+    importBundle,
+    listComponents,
+    saveComponent
+} from '../../services/components.js';
+
+export async function componentsRoutes(fastify) {
+    const canRead   = {preHandler: [authenticate, requirePermission('components', 'read')]};
+    const canUpdate = {preHandler: [authenticate, requirePermission('components', 'update')]};
+    const canDelete = {preHandler: [authenticate, requirePermission('components', 'delete')]};
+
+    // Public: compiled JS module (served to every page visitor).
+    fastify.get('/components/:name.js', async (request, reply) => {
+        const {name} = request.params;
+        try {
+            const {js, errors, mtime} = await getCompiledJs(name);
+            if (errors.length) return reply.status(500).send({error: 'Compile failed', errors});
+            reply.header('Content-Type', 'application/javascript; charset=utf-8');
+            reply.header('Cache-Control', 'public, max-age=60, must-revalidate');
+            reply.header('ETag', `"${name}-${mtime}"`);
+            return js;
+        } catch (err) {
+            if (err.code === 'INVALID_NAME') return reply.status(400).send({error: err.message});
+            if (err.code === 'ENOENT')       return reply.status(404).send({error: 'Component not found'});
+            throw err;
+        }
+    });
+
+    fastify.get('/components', canRead, () => listComponents());
+
+    fastify.get('/components/:name', canRead, async (request, reply) => {
+        try { return await getComponent(request.params.name); }
+        catch (err) {
+            if (err.code === 'INVALID_NAME') return reply.status(400).send({error: err.message});
+            if (err.code === 'ENOENT')       return reply.status(404).send({error: 'Component not found'});
+            throw err;
+        }
+    });
+
+    // Transient compile - used by the editor's live preview.
+    fastify.post('/components/compile', canUpdate, async (request, reply) => {
+        const {source, name} = request.body || {};
+        if (typeof source !== 'string' || typeof name !== 'string') {
+            return reply.status(400).send({error: 'source and name are required'});
+        }
+        return compileComponent(source, name);
+    });
+
+    fastify.get('/components/:name/export', canRead, async (request, reply) => {
+        const {name} = request.params;
+        try {
+            const bundle = await exportBundle(name);
+            reply.header('Content-Type', 'application/json; charset=utf-8');
+            reply.header('Content-Disposition', `attachment; filename="${name}.dmcomponent.json"`);
+            return JSON.stringify(bundle, null, 2);
+        } catch (err) {
+            if (err.code === 'INVALID_NAME') return reply.status(400).send({error: err.message});
+            if (err.code === 'ENOENT')       return reply.status(404).send({error: 'Component not found'});
+            throw err;
+        }
+    });
+
+    fastify.post('/components/import', canUpdate, async (request, reply) => {
+        try { return await importBundle(request.body, {overwrite: !!request.body?.overwrite}); }
+        catch (err) {
+            if (err.code === 'CONFLICT')       return reply.status(409).send({error: err.message, name: err.name});
+            if (err.code === 'INVALID_BUNDLE') return reply.status(400).send({error: err.message});
+            if (err.code === 'INVALID_NAME')   return reply.status(400).send({error: err.message});
+            throw err;
+        }
+    });
+
+    fastify.put('/components/:name', canUpdate, async (request, reply) => {
+        const {name} = request.params;
+        const {source, bundled} = request.body || {};
+        if (typeof source !== 'string') return reply.status(400).send({error: 'source (string) is required'});
+        try {
+            const result = await saveComponent(name, source, {bundled: !!bundled});
+            if (!result.success) return reply.status(400).send({error: 'Compile failed', errors: result.errors});
+            return result;
+        } catch (err) {
+            if (err.code === 'INVALID_NAME') return reply.status(400).send({error: err.message});
+            throw err;
+        }
+    });
+
+    fastify.delete('/components/:name', canDelete, async (request, reply) => {
+        try { await deleteComponent(request.params.name); return reply.status(204).send(); }
+        catch (err) {
+            if (err.code === 'INVALID_NAME') return reply.status(400).send({error: err.message});
+            if (err.code === 'ENOENT')       return reply.status(404).send({error: 'Component not found'});
+            throw err;
+        }
+    });
+}
+```
+
+- [ ] **Step 2: Register the route in `server/server.js`**
+
+Two insertions are needed, mirroring the existing `blocksRoutes` pattern:
+
+- After line **243** (`const {blocksRoutes} = await import('./routes/api/blocks.js');`) add:
+  ```js
+  const {componentsRoutes} = await import('./routes/api/components.js');
+  ```
+- After line **260** (`await app.register(blocksRoutes, {prefix: '/api'});`) add:
+  ```js
+  await app.register(componentsRoutes, {prefix: '/api'});
+  ```
+
+- [ ] **Step 3: Restart manually (user action) and smoke-test**
+
+Tell the user to restart their dev server (`npm run dev`), then run:
+
+```bash
+# Replace $TOKEN with an admin JWT from the admin SPA (S.get('auth_token') in the browser console).
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:4096/api/components | head
+```
+
+Expected: `[]` (empty list - no components yet).
+
+---
+
+# PHASE 3 - Seeded starter library
+
+## Task 11: Write the five seed `.dmc` sources
+
+**Files:**
+- Modify: `server/services/components.js`
+
+- [ ] **Step 1: Add the `SEED_COMPONENTS` map at the bottom of `components.js`**
+
+```js
+// ─── Seeded starter components ────────────────────────────────────────────
+
+const SEED_COMPONENTS = {
+
+    counter: `
+<template>
+<div class="dm-counter">
+  <div class="value">{{count}}</div>
+  <div class="controls">
+    <button data-action="dec">−</button>
+    <button data-action="inc">+</button>
+    {{#if showReset}}<button data-action="reset">Reset</button>{{/if}}
+  </div>
+</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.shadowRoot.addEventListener('click', (e) => {
+      const action = e.target.dataset.action;
+      if (action && this[action]) this[action]();
+    });
+  }
+};
+</script>
+<style>
+.dm-counter { text-align: center; padding: 1rem; }
+.dm-counter .value { font-size: 2.5rem; font-weight: 700; margin-bottom: .5rem; }
+.dm-counter .controls button { margin: 0 .25rem; padding: .4rem .8rem; }
+</style>
+`,
+
+    'copy-button': `
+<template>
+<button class="dm-copy-btn" data-action="copy">{{label}}</button>
+</template>
+<props>
+{
+  "text":        { "type": "string", "default": "",       "label": "Text to copy" },
+  "label":       { "type": "string", "default": "Copy",   "label": "Button label" },
+  "copiedLabel": { "type": "string", "default": "Copied!","label": "Confirmation label" }
+}
+</props>
+<script>
+export default {
+  data() { return { label: this.props.label }; },
+  methods: {
+    async copy() {
+      try {
+        await navigator.clipboard.writeText(this.props.text);
+        this.set({ label: this.props.copiedLabel });
+        setTimeout(() => this.set({ label: this.props.label }), 1500);
+      } catch {}
+    }
+  },
+  onMount() {
+    this.el.shadowRoot.addEventListener('click', (e) => {
+      if (e.target.dataset.action === 'copy') this.copy();
+    });
+  }
+};
+</script>
+<style>
+.dm-copy-btn { padding: .5rem 1rem; cursor: pointer; }
+</style>
+`,
+
+    'reveal-panel': `
+<template>
+<div class="dm-reveal">
+  <button class="toggle" data-action="toggle">{{heading}}</button>
+  {{#if open}}<div class="body"><slot></slot></div>{{/if}}
+</div>
+</template>
+<props>
+{
+  "heading":     { "type": "string",  "default": "Show more", "label": "Toggle heading" },
+  "openDefault": { "type": "boolean", "default": false,       "label": "Open on load" }
+}
+</props>
+<script>
+export default {
+  data() { return { open: this.props.openDefault }; },
+  methods: { toggle() { this.set({ open: !this.data.open }); } },
+  onMount() {
+    this.el.shadowRoot.addEventListener('click', (e) => {
+      if (e.target.dataset.action === 'toggle') this.toggle();
+    });
+  }
+};
+</script>
+<style>
+.dm-reveal .toggle { background: none; border: none; font-weight: 600; cursor: pointer; }
+.dm-reveal .body { margin-top: .5rem; padding-top: .5rem; border-top: 1px solid currentColor; }
+</style>
+`,
+
+    'testimonial-card': `
+<template>
+<figure class="dm-testimonial">
+  <blockquote class="quote">"{{quote}}"</blockquote>
+  <figcaption class="author">
+    {{#if avatar}}<img class="avatar" src="{{avatar}}" alt="">{{/if}}
+    <div><div class="name">{{author}}</div><div class="role">{{role}}</div></div>
+  </figcaption>
+</figure>
+</template>
+<props>
+{
+  "quote":  { "type": "string", "default": "", "label": "Quote" },
+  "author": { "type": "string", "default": "", "label": "Author name" },
+  "role":   { "type": "string", "default": "", "label": "Author role or company" },
+  "avatar": { "type": "string", "default": "", "label": "Avatar image URL" }
+}
+</props>
+<script>
+export default {};
+</script>
+<style>
+.dm-testimonial { margin: 0; padding: 1.25rem; border-radius: 8px; background: rgba(0,0,0,.04); }
+.dm-testimonial .quote { font-size: 1.05rem; font-style: italic; margin: 0 0 .75rem; }
+.dm-testimonial .author { display: flex; align-items: center; gap: .75rem; font-size: .85rem; }
+.dm-testimonial .avatar { width: 40px; height: 40px; border-radius: 50%; object-fit: cover; }
+.dm-testimonial .name { font-weight: 600; }
+.dm-testimonial .role { opacity: .7; }
+</style>
+`,
+
+    'countdown-timer': `
+<template>
+<div class="dm-countdown-c">
+  <div class="part"><span class="n">{{days}}</span><span class="l">days</span></div>
+  <div class="part"><span class="n">{{hours}}</span><span class="l">hrs</span></div>
+  <div class="part"><span class="n">{{minutes}}</span><span class="l">min</span></div>
+  <div class="part"><span class="n">{{seconds}}</span><span class="l">sec</span></div>
+</div>
+</template>
+<props>
+{
+  "target": { "type": "string", "default": "", "label": "Target date (ISO 8601)" }
+}
+</props>
+<script>
+export default {
+  data() { return { days: 0, hours: 0, minutes: 0, seconds: 0 }; },
+  _timer: null,
+  methods: {
+    tick() {
+      const t = new Date(this.props.target).getTime() - Date.now();
+      if (isNaN(t) || t <= 0) { this.set({ days: 0, hours: 0, minutes: 0, seconds: 0 }); return; }
+      this.set({
+        days:    Math.floor(t / 86400000),
+        hours:   Math.floor((t % 86400000) / 3600000),
+        minutes: Math.floor((t % 3600000) / 60000),
+        seconds: Math.floor((t % 60000) / 1000)
+      });
+    }
+  },
+  onMount()   { this.tick(); this._timer = setInterval(() => this.tick(), 1000); },
+  onUnmount() { if (this._timer) clearInterval(this._timer); }
+};
+</script>
+<style>
+.dm-countdown-c { display: flex; gap: 1rem; justify-content: center; }
+.dm-countdown-c .part { display: flex; flex-direction: column; align-items: center; }
+.dm-countdown-c .n { font-size: 1.8rem; font-weight: 700; }
+.dm-countdown-c .l { font-size: .7rem; text-transform: uppercase; opacity: .7; }
+</style>
+`
+};
+```
+
+---
+
+## Task 12: `seedDefaultComponents()` and wire into startup
+
+**Files:**
+- Modify: `server/services/components.js`
+- Modify: `server/server.js`
+
+- [ ] **Step 1: Add the seeder**
+
+```js
+/**
+ * Seed starter components into content/components/.
+ * Never overwrites existing files - user customisations are preserved.
+ * All seeded components are marked `bundled: true` via .meta.json.
+ */
+export async function seedDefaultComponents() {
+    await fs.mkdir(COMPONENTS_DIR, {recursive: true});
+    const seeded = [];
+    for (const [name, source] of Object.entries(SEED_COMPONENTS)) {
+        const fp = componentFilePath(name);
+        try { await fs.access(fp); }
+        catch {
+            await fs.writeFile(fp, source.trim() + '\n', 'utf8');
+            await fs.writeFile(componentMetaPath(name), JSON.stringify({bundled: true}, null, 2) + '\n', 'utf8');
+            seeded.push(name);
+        }
+    }
+    if (seeded.length) console.log(`[components] Seeded default components: ${seeded.join(', ')}`);
+}
+```
+
+- [ ] **Step 2: Call it during startup in `server/server.js`**
+
+Two insertions, mirroring the existing `seedDefaultBlocks()` pattern:
+
+- After line **24** (`import {seedDefaultBlocks} from './services/blocks.js';`) add:
+  ```js
+  import {seedDefaultComponents} from './services/components.js';
+  ```
+- After line **169** (`await seedDefaultBlocks();`) add:
+  ```js
+  await seedDefaultComponents();
+  ```
+
+- [ ] **Step 3: Restart + verify**
+
+After restart:
+
+```bash
+ls /home/darryl/src/js/domma-cms/content/components/
+```
+
+Expected: five `.dmc` + five `.meta.json` files.
+
+```bash
+curl -s http://localhost:4096/api/components/counter.js | head -n 3
+```
+
+Expected: first line begins `// Compiled from counter.dmc`.
+
+---
+
+# PHASE 4 - Renderer integration (public site)
+
+## Task 13: `collectComponents()` + shortcode rewrite in `markdown.js`
+
+**Files:**
+- Modify: `server/services/markdown.js`
+
+- [ ] **Step 1: Locate the shortcode pipeline**
+
+Run: `grep -n "function process\|export function parseMarkdown\|export function renderMarkdown" server/services/markdown.js | head -20`
+
+- [ ] **Step 2: Add the `collectAndRewriteComponents` processor**
+
+Add near the other `process*` functions:
+
+```js
+/**
+ * Process component references in two injection forms:
+ *   1. [component name="x" attr="y" /]          - shortcode
+ *   2. <dm-x attr="y">…</dm-x>                  - raw custom-element tag
+ *
+ * Rewrites form 1 to form 2 in-place, and collects every <dm-*> tag
+ * name encountered into a de-duplicated Set.
+ *
+ * @param {string} source
+ * @returns {{output: string, used: Set<string>}}
+ */
+export function collectAndRewriteComponents(source) {
+    const used = new Set();
+
+    // Rewrite shortcode to raw tag. [component name="x" a="1" b="2" /] → <dm-x a="1" b="2"></dm-x>
+    const rewritten = source.replace(
+        /\[component\s+([^\]]+?)\s*\/?\]/g,
+        (_, attrs) => {
+            const nameMatch = attrs.match(/name\s*=\s*["']([a-z][a-z0-9-]*)["']/);
+            if (!nameMatch) return '';  // silently drop malformed shortcodes
+            const name = nameMatch[1];
+            const otherAttrs = attrs.replace(/name\s*=\s*["'][^"']+["']/, '').trim();
+            return `<dm-${name} ${otherAttrs}></dm-${name}>`;
+        }
+    );
+
+    // Collect every <dm-name … tag from the rewritten source.
+    for (const m of rewritten.matchAll(/<dm-([a-z][a-z0-9-]*)/g)) {
+        used.add(m[1]);
+    }
+
+    return {output: rewritten, used};
+}
+```
+
+- [ ] **Step 3: Wire it into the existing pipeline**
+
+`parseMarkdown()` in `markdown.js` currently returns `{data, content, html}`. The renderer calls it and then assembles the page shell. To get `used` to the renderer:
+
+1. Inside `parseMarkdown()`, call `collectAndRewriteComponents(raw)` on the Markdown body **before** the other `process*()` passes (so shortcodes are rewritten to `<dm-*>` tags that downstream passes see). Capture the output and `used` set.
+2. Feed `output` into the rest of the pipeline instead of the raw source.
+3. **Return `usedComponents: [...used]` as a fourth field** from `parseMarkdown()`:
+   ```js
+   return {data, content, html, usedComponents: [...used]};
+   ```
+4. In `renderer.js`'s `renderPage()`, the parsed page object will now carry `usedComponents`. Read it directly there - no mutation of a shared page object is required.
+
+- [ ] **Step 4: Test it on an isolated Markdown string**
+
+```bash
+node -e "
+const m = await import('/home/darryl/src/js/domma-cms/server/services/markdown.js');
+const res = m.collectAndRewriteComponents('Hello [component name=\"counter\" initial=\"5\" /] and <dm-pricing-table /> end.');
+console.log(res.output);
+console.log([...res.used]);
+"
+```
+
+Expected output:
+```
+Hello <dm-counter  initial="5"></dm-counter> and <dm-pricing-table /> end.
+[ 'counter', 'pricing-table' ]
+```
+
+---
+
+## Task 14: `sanitize-html` config - `dm-*` allowlist + attribute pass-through
+
+> **Correction vs spec:** the spec referred to DOMPurify but this project uses `sanitize-html` (see `server/services/markdown.js:7` and the sanitiser block at `markdown.js:2715-2748`). All DOMPurify-specific config keys (`ADD_TAGS`, `CUSTOM_ELEMENT_HANDLING`, `uponSanitizeAttribute`) have been translated to their `sanitize-html` equivalents below.
+
+**Files:**
+- Modify: `server/services/markdown.js` (sanitiser block near line 2715)
+
+- [ ] **Step 1: Add a helper that resolves the live set of allowed `dm-*` tag names**
+
+At the top of `server/services/markdown.js`, add an import:
+
+```js
+import {listComponents} from './components.js';
+```
+
+And near the other top-level helpers add a small cache:
+
+```js
+// Cache of registered dm-* tag names. Rebuilt by `refreshComponentTagAllowlist()`
+// on component create/delete so the sanitiser stays in sync without server restarts.
+let _dmTagAllowlist = [];
+let _dmTagAllowlistReady = false;
+
+/**
+ * Refresh the in-memory list of allowed dm-* custom-element tag names.
+ * Called once on startup, and by the components service after mutation.
+ */
+export async function refreshComponentTagAllowlist() {
+    try {
+        const entries = await listComponents();
+        _dmTagAllowlist = entries.map(c => `dm-${c.name}`);
+        _dmTagAllowlistReady = true;
+    } catch {
+        _dmTagAllowlist = [];
+    }
+}
+```
+
+- [ ] **Step 2: Extend the sanitiser config at `markdown.js:2720-2747`**
+
+Edit the existing `sanitizeHtml(rendered, { … })` call:
+
+```js
+const sanitized = sanitizeHtml(rendered, {
+    allowVulnerableTags: true,
+    allowedTags: sanitizeHtml.defaults.allowedTags.concat([
+        'img', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+        'form', 'input', 'textarea', 'select', 'option', 'optgroup',
+        'button', 'label', 'fieldset', 'legend',
+        'style',
+        ...extensions.tags,
+        ..._dmTagAllowlist                               // ← new: dm-<name> for every registered component
+    ]),
+    allowedAttributes: {
+        ...sanitizeHtml.defaults.allowedAttributes,
+        '*': ['class', 'id', 'style', 'data-*'],
+        img:      [/* existing … */],
+        form:     [/* existing … */],
+        input:    [/* existing … */],
+        textarea: [/* existing … */],
+        select:   [/* existing … */],
+        option:   [/* existing … */],
+        optgroup: [/* existing … */],
+        button:   [/* existing … */],
+        label:    [/* existing … */],
+        fieldset: [/* existing … */],
+        // Allow any kebab-case attribute on every registered dm-* tag.
+        // Props are author-defined; enumerating them at sanitise time has no
+        // security benefit. On* handlers and javascript: URLs are still stripped
+        // by sanitize-html's defaults (globally, via the '*' default).
+        ..._dmTagAllowlist.reduce((acc, tag) => {
+            acc[tag] = ['*'];
+            return acc;
+        }, {}),
+        ...extensions.attributes
+    }
+});
+```
+
+The key addition is two lines: `..._dmTagAllowlist` under `allowedTags`, and the `reduce(...)` under `allowedAttributes` that maps every registered `dm-<name>` tag to `['*']` (all attributes allowed). The two existing author-level trust boundaries (admins write components, admins write pages) mean this does not introduce a new XSS surface.
+
+- [ ] **Step 3: Call `refreshComponentTagAllowlist()` during startup**
+
+In `server/server.js`, directly **after** the `await seedDefaultComponents()` line from Task 12 Step 2, add:
+
+```js
+import {refreshComponentTagAllowlist} from './services/markdown.js';
+// …
+await refreshComponentTagAllowlist();
+```
+
+- [ ] **Step 4: Invalidate the allowlist on component mutations**
+
+In `server/services/components.js`, import the refresh function lazily (at the top of the file) and call it in `saveComponent()` and `deleteComponent()`:
+
+```js
+// Near the top of components.js:
+import {refreshComponentTagAllowlist} from './markdown.js';
+
+// In saveComponent, after invalidateCache(name):
+await refreshComponentTagAllowlist();
+
+// In deleteComponent, after invalidateCache(name):
+await refreshComponentTagAllowlist();
+```
+
+Watch for circular import: `markdown.js` already imports from `components.js` (Step 1) and now `components.js` imports from `markdown.js`. Node's ESM handles circular imports when the reference is only used lazily at call time - verify by restarting the server. If the circular causes a `TDZ` error, move the helper to a new `server/services/sanitiser.js` module that both sides import from.
+
+- [ ] **Step 5: Verify via round-trip**
+
+After restarting:
+
+```bash
+node -e "
+const m = await import('/home/darryl/src/js/domma-cms/server/services/markdown.js');
+await m.refreshComponentTagAllowlist();
+const {html} = await m.renderMarkdown('<dm-counter initial=\"5\"></dm-counter>');
+console.log(html.includes('<dm-counter') ? 'OK' : 'STRIPPED');
+"
+```
+
+Expected: `OK`.
+
+---
+
+## Task 15: Per-page script injection in `renderer.js`
+
+**Files:**
+- Modify: `server/services/renderer.js`
+
+- [ ] **Step 1: Locate the `bodyEndInject` assembly**
+
+Run: `grep -n "bodyEndInject" server/services/renderer.js`
+
+- [ ] **Step 2: Build the per-page component scripts list**
+
+At the point where `bodyEndInject` is constructed, add:
+
+```js
+const componentScripts = (page.usedComponents || [])
+    .map(n => `<script type="module" src="/api/components/${n}.js"></script>`)
+    .join('\n');
+```
+
+(Per Task 13 Step 3, `parseMarkdown()` now returns `usedComponents` as part of the page object.)
+
+- [ ] **Step 3: Insert into `bodyEndInject` at the correct position**
+
+The existing array at `renderer.js:157-161` is:
+
+```js
+bodyEndInject: [
+    injection.bodyEnd,
+    site.backToTop?.enabled    ? '<script src="/public/js/btt.js"></script>'             : '',
+    site.cookieConsent?.enabled ? '<script src="/public/js/cookie-consent.js"></script>' : ''
+].filter(Boolean).join('\n'),
+```
+
+Add `componentScripts` as a new entry at the **end** of the array (so component scripts load after `btt.js` / `cookie-consent.js` - both small and synchronous, no blocking concern):
+
+```js
+bodyEndInject: [
+    injection.bodyEnd,
+    site.backToTop?.enabled    ? '<script src="/public/js/btt.js"></script>'             : '',
+    site.cookieConsent?.enabled ? '<script src="/public/js/cookie-consent.js"></script>' : '',
+    componentScripts                              // ← new
+].filter(Boolean).join('\n'),
+```
+
+Apply the same edit to the `renderPreview()` function further down the file (it has an identical `bodyEndInject` assembly at a separate line range - find via `grep -n "bodyEndInject" server/services/renderer.js`).
+
+- [ ] **Step 4: Verify on a real page**
+
+Pick an existing page file and add a component reference:
+
+```bash
+echo '[component name="counter" /]' >> /home/darryl/src/js/domma-cms/content/pages/index.md
+curl -s http://localhost:4096/ | grep -o '<script type="module" src="/api/components/counter.js"></script>'
+```
+
+Expected: one match. Then revert the `index.md` change.
+
+---
+
+## Task 16: Flash-prevention CSS
+
+**Files:**
+- Modify: `public/css/site.css`
+
+- [ ] **Step 1: Append the rule**
+
+At the bottom of `public/css/site.css`:
+
+```css
+/* Hide custom elements until their defining module has upgraded them. */
+:not(:defined) { visibility: hidden; }
+```
+
+- [ ] **Step 2: Scope it if a blanket `:not(:defined)` causes issues on built-in browsers that haven't yet defined some Domma element**
+
+If the blanket rule proves too broad, narrow to `dm-*` via an attribute selector chain:
+
+```css
+[class*=""]:is(:not(:defined)) { visibility: hidden; }
+```
+
+(Only apply Step 2 if testing surfaces a problem - otherwise skip.)
+
+- [ ] **Step 3: Verify on the public page**
+
+Reload a page containing a `<dm-counter>`. Expected: no flash of unstyled tag text before the component upgrades.
+
+---
+
+# PHASE 5 - Admin preview iframe bootstrap
+
+## Task 17: `component-preview.html`
+
+**Files:**
+- Create: `admin/preview/component-preview.html`
+- Modify: `server/server.js` - register static serve path (if not already covered)
+
+- [ ] **Step 1: Write the bootstrap**
+
+```html
+<!DOCTYPE html>
+<html lang="en-GB">
+<head>
+<meta charset="UTF-8">
+<title>Component Preview</title>
+<link rel="stylesheet" href="/dist/domma/domma.css">
+<link rel="stylesheet" href="/dist/domma/elements.css">
+<link rel="stylesheet" href="/dist/domma/themes/domma-themes.css">
+<style>
+  body { margin: 0; padding: 1rem; }
+  #mount { display: block; }
+  #err { color: crimson; font-family: monospace; white-space: pre-wrap; }
+</style>
+<script src="/dist/domma/domma.min.js"></script>
+</head>
+<body class="dm-theme-charcoal-dark">
+<div id="mount"></div>
+<pre id="err" hidden></pre>
+<script>
+  let currentEl = null;
+
+  function showError(msg) {
+    const err = document.getElementById('err');
+    err.hidden = false;
+    err.textContent = msg;
+    parent.postMessage({type: 'error', message: msg}, '*');
+  }
+
+  function clearMount() {
+    const mount = document.getElementById('mount');
+    while (mount.firstChild) mount.removeChild(mount.firstChild);
+    document.getElementById('err').hidden = true;
+    currentEl = null;
+  }
+
+  async function mount({compiledJs, tagName, props}) {
+    clearMount();
+    try {
+      // Execute the compiled module - it calls Domma.component(...) at top level.
+      const blob = new Blob([compiledJs], {type: 'application/javascript'});
+      const url  = URL.createObjectURL(blob);
+      await import(url);
+      URL.revokeObjectURL(url);
+
+      currentEl = document.createElement(tagName);
+      for (const [k, v] of Object.entries(props || {})) {
+        const attr = k.replace(/([A-Z])/g, '-$1').toLowerCase();
+        currentEl.setAttribute(attr, String(v));
+      }
+      document.getElementById('mount').appendChild(currentEl);
+      parent.postMessage({type: 'ready', height: document.body.scrollHeight}, '*');
+    } catch (e) {
+      showError(e.stack || e.message);
+    }
+  }
+
+  function updateProps(props) {
+    if (!currentEl) return;
+    for (const [k, v] of Object.entries(props || {})) {
+      const attr = k.replace(/([A-Z])/g, '-$1').toLowerCase();
+      currentEl.setAttribute(attr, String(v));
+    }
+  }
+
+  window.addEventListener('message', (e) => {
+    const msg = e.data || {};
+    if (msg.type === 'mount')        mount(msg.payload);
+    else if (msg.type === 'update')  updateProps(msg.payload?.props);
+    else if (msg.type === 'remount') mount(msg.payload);
+  });
+
+  new ResizeObserver(() => {
+    parent.postMessage({type: 'resize', height: document.body.scrollHeight}, '*');
+  }).observe(document.body);
+</script>
+</body>
+</html>
+```
+
+- [ ] **Step 2: Ensure `/admin/preview/` is served statically**
+
+Check `server/server.js` - the admin static serve may already cover `/admin/*`. If not, add a static registration mirroring the pattern used for `/admin`.
+
+- [ ] **Step 3: Smoke test it loads**
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4096/admin/preview/component-preview.html
+```
+
+Expected: `200`.
+
+---
+
+# PHASE 6 - Admin list view
+
+## Task 18: `api.components` helpers in `admin/js/api.js`
+
+**Files:**
+- Modify: `admin/js/api.js`
+
+- [ ] **Step 1: Locate existing `api.blocks` definition**
+
+Run: `grep -n "blocks" admin/js/api.js | head -10`
+
+- [ ] **Step 2: Add `api.components` mirroring the blocks pattern**
+
+The existing `api.blocks` sub-object lives at `admin/js/api.js:305-360` and uses the module-level `apiRequest()` helper plus raw `fetch()` for the file-download / file-upload paths (so Bearer auth is carried). Mirror it exactly - add inside the same exported `api` object, directly after the `blocks` key:
+
+```js
+components: {
+    list: () => apiRequest('/components', {method: 'GET'}),
+    get: (name) => apiRequest(`/components/${encodeURIComponent(name)}`, {method: 'GET'}),
+    compile: (name, source) => apiRequest('/components/compile', {
+        method: 'POST',
+        body: JSON.stringify({name, source})
+    }),
+    put: (name, data) => apiRequest(`/components/${encodeURIComponent(name)}`, {
+        method: 'PUT',
+        body: JSON.stringify(data)
+    }),
+    delete: (name) => apiRequest(`/components/${encodeURIComponent(name)}`, {method: 'DELETE'}),
+
+    /** See api.blocks.exportBundle for the rationale. */
+    async exportBundle(name) {
+        const token = getToken();
+        const res = await fetch(`${BASE}/components/${encodeURIComponent(name)}/export`, {
+            headers: token ? {Authorization: `Bearer ${token}`} : {}
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(err.error || `Export failed (${res.status})`);
+        }
+        const blob = await res.blob();
+        const url  = URL.createObjectURL(blob);
+        const a    = document.createElement('a');
+        a.href = url;
+        a.download = `${name}.dmcomponent.json`;
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+        URL.revokeObjectURL(url);
+    },
+
+    async importBundle(bundle, {overwrite = false} = {}) {
+        const res = await fetch(`${BASE}/components/import`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(getToken() ? {Authorization: `Bearer ${getToken()}`} : {})
+            },
+            body: JSON.stringify({...bundle, overwrite})
+        });
+        if (res.status === 409) {
+            const payload = await res.json().catch(() => ({}));
+            const err = new Error(payload.error || 'Component already exists');
+            err.code = 'CONFLICT';
+            err.name = payload.name;
+            throw err;
+        }
+        if (!res.ok) {
+            const payload = await res.json().catch(() => ({}));
+            throw new Error(payload.error || `Import failed (${res.status})`);
+        }
+        return res.json();
+    }
+},
+```
+
+- [ ] **Step 3: Smoke-test in the browser console after reload**
+
+`await api.components.list()` - expect an array of five seeded entries.
+
+---
+
+## Task 19: List view template + logic
+
+**Files:**
+- Create: `admin/js/templates/components.html`
+- Create: `admin/js/views/components.js`
+
+- [ ] **Step 1: Write the template**
+
+Use `admin/js/templates/blocks.html` as a reference and copy its structure. Change every "Block" to "Component", add a **Props** column to the table, and change the URL fragments from `/blocks/` to `/components/`.
+
+- [ ] **Step 2: Write the view**
+
+Use `admin/js/views/blocks.js` as a reference and copy its structure. Key changes:
+
+- Import `api.components` instead of `api.blocks`.
+- The table columns include **Props** - render the parsed props as a pill list:
+  ```js
+  {
+      key: 'props',
+      title: 'Props',
+      render: (val) => Object.keys(val || {}).map(p => `<span class="badge badge-secondary" style="margin-right:.25rem;">${esc(p)}</span>`).join('')
+  }
+  ```
+- File extension in links: `.dmc` not `.html`.
+- Register a `puzzle` icon (paths: `M10 3h4v4h4v4h-4v4h-4v-4H6V7h4V3z` or a similar puzzle-piece SVG) alongside the existing download/upload/plus icon registrations.
+
+- [ ] **Step 3: Smoke test once wired in Task 20**
+
+---
+
+## Task 20: Register view, sidebar entry, and sidebar counts
+
+**Files:**
+- Modify: `admin/js/views/index.js`
+- Modify: `admin/js/config/sidebar-config.js`
+- Modify: `admin/js/app.js`
+
+- [ ] **Step 1: Register the view**
+
+In `admin/js/views/index.js`:
+
+```js
+import {componentsView} from './components.js';
+// …and inside the views object:
+components: componentsView,
+```
+
+- [ ] **Step 2: Add the sidebar entry**
+
+In `admin/js/config/sidebar-config.js`, inside the Data section, after the Blocks entry:
+
+```js
+if (canAny('components')) {
+    items.push({id: 'components', text: 'Components', icon: 'puzzle', url: '#/components', section: '#/components', badge: badge(counts.components)});
+}
+```
+
+Also update the `hasData` check to include `canAny('components')`.
+
+- [ ] **Step 3: Wire sidebar count**
+
+In `admin/js/app.js` → `fetchSidebarCounts()`, add `api.components.list().catch(() => [])` to the `Promise.all` and expose `components: components.length` in the returned object.
+
+- [ ] **Step 4: Register the route**
+
+Find where `/blocks` route is defined in `admin/js/app.js` (or wherever Domma router routes are declared) and add:
+
+```js
+R.route('/components', {view: 'components'});
+R.route('/components/new', {view: 'componentEditor'});
+R.route('/components/edit/:name', {view: 'componentEditor'});
+```
+
+- [ ] **Step 5: Reload and check**
+
+Open the admin in a browser. Expected: **Components** appears in the sidebar under Data, clicking it shows five seeded entries.
+
+---
+
+# PHASE 7 - Admin component editor
+
+## Task 21: Editor template
+
+**Files:**
+- Create: `admin/js/templates/component-editor.html`
+
+- [ ] **Step 1: Write the template**
+
+Reference `admin/js/templates/block-editor.html` for overall structure. Add a tab bar with four tabs (template / props / script / style), each revealing a textarea-based code editor (reuse the `#block-line-numbers`, `#block-cursor-pos`, `#block-editor-toolbar` primitives - give them new IDs scoped to `component-`).
+
+On the right, add the iframe preview and a "Preview props" panel below it.
+
+Key new IDs:
+- `#component-name`, `#component-bundled`, `#save-component-btn`, `#component-quick-switch`
+- `#component-tab-template`, `#component-tab-props`, `#component-tab-script`, `#component-tab-style`
+- `#component-pane-template`, `#component-pane-props`, `#component-pane-script`, `#component-pane-style`
+- `#component-preview-iframe`, `#component-preview-props`, `#component-compile-status`
+
+---
+
+## Task 22: Editor view logic
+
+**Files:**
+- Create: `admin/js/views/component-editor.js`
+
+- [ ] **Step 1: Write the view skeleton**
+
+Reference `admin/js/views/block-editor.js` for editor primitives (line numbers, cursor tracking, tab-indent, toolbar). Adapt:
+
+- Load via `api.components.get(name)`.
+- Parse the source into its four blocks on load; populate each tab's textarea.
+- **Tolerant parse on load:** use the same block-split regex client-side as `parseDmcSource` on the server. If any block is missing, populate the corresponding tab empty and surface a warning in the status bar - do **not** hard-fail the editor. An author editing a component they just broke should still be able to fix it.
+- On save, reassemble the four textareas into a single `.dmc` source string:
+  ```js
+  const source = `<template>\n${templateText}\n</template>\n<props>\n${propsText}\n</props>\n<script>\n${scriptText}\n</script>\n<style>\n${styleText}\n</style>\n`;
+  ```
+- POST to `api.components.put(name, {source, bundled})`. On `400` with `errors`, display them in `#component-compile-status`.
+
+- [ ] **Step 2: Debounced compile + preview wiring**
+
+On input in any tab's textarea:
+
+1. Debounce 300 ms.
+2. Assemble the current source.
+3. Call `api.components.compile(name, source)`.
+4. On success, postMessage `{type: 'remount', payload: {compiledJs: js, tagName: 'dm-'+name, props: previewProps}}` to the iframe.
+5. On error, show the error in `#component-compile-status` and do NOT remount.
+
+- [ ] **Step 3: Preview props panel**
+
+After load, parse the `<props>` block. For each prop, render an input keyed by type:
+- `number` → `<input type="number">`
+- `boolean` → `<input type="checkbox">`
+- `string` → `<input type="text">`
+- `array` / `object` → `<textarea>` containing JSON
+
+On input, call the iframe `{type: 'update', payload: {props: currentProps}}` (cheaper than remount for prop-only changes).
+
+---
+
+## Task 23: Editor manual smoke test
+
+- [ ] **Step 1: Navigate to `#/components/edit/counter`**
+
+Expected: four tabs populated with the seeded counter source; iframe preview on the right shows the working counter.
+
+- [ ] **Step 2: Edit the `<template>` value tag content and confirm live preview remounts**
+
+- [ ] **Step 3: Click the `+` button inside the preview iframe**
+
+Expected: counter increments (proves reactivity reaches into the sandbox).
+
+- [ ] **Step 4: Introduce a `<props>` JSON syntax error**
+
+Expected: save button disables, status bar shows the error.
+
+---
+
+# PHASE 8 - Page editor insertion slideover
+
+## Task 24: Insert Component button + slideover
+
+**Files:**
+- Modify: `admin/js/views/page-editor.js`
+
+- [ ] **Step 1: Locate existing insert buttons**
+
+Run: `grep -n "Insert Block\|insert-block\|[Ii]nsertBlock" admin/js/views/page-editor.js | head -20`
+
+- [ ] **Step 2: Add the button + handler**
+
+Next to the existing Insert Block / Insert Form buttons, add:
+
+```js
+const insertComponentBtn = $container.find('#insert-component-btn').get(0);
+if (insertComponentBtn) insertComponentBtn.addEventListener('click', () => openComponentSlideover($container));
+```
+
+Add a button in the template HTML with id `#insert-component-btn` and text "Insert Component".
+
+- [ ] **Step 3: Implement `openComponentSlideover`**
+
+```js
+async function openComponentSlideover($container) {
+    const components = await api.components.list().catch(() => []);
+    const slideover = E.slideover({
+        title: 'Insert Component',
+        size: 'lg',
+        position: 'right'
+    });
+
+    // Build gallery + form + preview DOM (do NOT use slideover.setContent with HTML - strips <button>).
+    // Use .element.appendChild(...) pattern for interactive content (same as modal gotcha).
+    const root = document.createElement('div');
+    // …build UI: gallery cards, props form via F.create, iframe preview.
+    slideover.element.appendChild(root);
+    slideover.open();
+}
+```
+
+Inside the slideover:
+
+1. **Gallery**: card grid of `components`. On click of a card, reveal the props form and preview.
+2. **Props form**: `F.create(propsContainer, { blueprint: buildBlueprint(selectedComponent.props) })`. Emits changes.
+3. **Preview**: iframe pointing at `/admin/preview/component-preview.html`; postMessage mount with the selected component's compiled JS + current props.
+4. **Insert button**: closes the slideover and inserts `[component name="x" a="y" /]` at the textarea cursor in the page editor.
+
+- [ ] **Step 4: Verify `E.slideover()` + iframe behaviour**
+
+Flag during this task: if `E.slideover()` strips HTML the way `E.modal()` does, the light-DOM append pattern is the workaround (as done in the plan). Confirm the iframe survives open/close cycles. If it does not, note in the save preview code that the iframe is destroyed and recreated on reopen.
+
+---
+
+# PHASE 9 - End-to-end verification
+
+## Task 25: Smoke tests
+
+- [ ] **Step 1: Fresh page with a component**
+
+Create a scratch page `content/pages/scratch.md`:
+
+```markdown
+---
+title: Scratch
+---
+[component name="counter" initial="3" step="2" /]
+```
+
+Navigate to `http://localhost:4096/scratch`. Expected: counter renders with value 3; clicking `+` advances by 2.
+
+- [ ] **Step 2: Page with a raw-tag component**
+
+Edit the same page to use `<dm-testimonial-card quote="Hello" author="Alice" role="CEO"></dm-testimonial-card>` - confirm it renders.
+
+- [ ] **Step 3: Multiple components on one page**
+
+Add both a counter and a testimonial-card to the same page. Open the browser dev tools → Network → confirm exactly two `/api/components/*.js` requests are made (not five, not zero).
+
+- [ ] **Step 4: Reference a non-existent component**
+
+Add `<dm-does-not-exist></dm-does-not-exist>` to the page. Expected: browser 404 for the script, tag stays inert, rest of the page renders fine.
+
+- [ ] **Step 5: Permission gating**
+
+With a non-super-admin user (but admin-level), confirm:
+- The Components sidebar entry is visible (they have `read`).
+- `PUT /api/components/counter` returns 403 (they lack `update`).
+
+- [ ] **Step 6: Export / import round-trip**
+
+Export the `counter`, delete it, re-import, confirm it reappears with identical source.
+
+- [ ] **Step 7: Delete the scratch page**
+
+```bash
+rm /home/darryl/src/js/domma-cms/content/pages/scratch.md
+```
+
+---
+
+## Done criteria
+
+- All twenty-five tasks checked off.
+- `node --test tests/components/compile.test.js` passes all assertions.
+- Smoke tests in Task 25 all pass.
+- No new lint warnings.
+- User has committed the changes at their own cadence.