domma-cms 1.6.59 → 1.7.0

package/docs/plans/2026-03-05-scribe-script-shortcode.md

@@ -0,0 +1,373 @@
+# Scribe Script Shortcode Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Expose Domma's Scribe `actions` array in CMS Markdown via nested `[render]`, `[wait]`, and `[undo]` shortcodes
+inside `[scribe]`, so content editors can write multi-step typewriter scripts without touching JavaScript.
+
+**Architecture:** The `[scribe]` shortcode handler in `plugin.js` gains a dedicated parser that scans the body for inner
+action shortcodes and serialises them to JSON stored in a `data-fx-actions` attribute. `inject-body.html` reads that
+attribute on the client side and passes the parsed array directly to `E.scribe()`. Backward compat is preserved: a
+plain-text body continues to produce a single `{render: text}` action as before.
+
+**Tech Stack:** Fastify plugin hooks, `parseShortcodeAttrs` / `escapeAttr` from markdown.js, `E.scribe()` from Domma JS,
+vanilla JS in inject-body.html.
+
+---
+
+### Task 1: Export `escapeAttr` from markdown.js and add to plugin context
+
+**Files:**
+
+- Modify: `server/services/markdown.js`
+
+**Step 1: Change `escapeAttr` declaration to `export function`**
+
+In `server/services/markdown.js` (around line 154), change:
+
+```
+function escapeAttr(str) {
+```
+
+to:
+
+```
+export function escapeAttr(str) {
+```
+
+**Step 2: Add `escapeAttr` to the plugin shortcode context**
+
+In `processPluginShortcodes` (around line 68), change:
+
+```
+const context = {parseShortcodeAttrs, scrubCodeRegions, marked, processCardBlocks, processGridBlocks};
+```
+
+to:
+
+```
+const context = {parseShortcodeAttrs, scrubCodeRegions, marked, processCardBlocks, processGridBlocks, escapeAttr};
+```
+
+**Step 3: Verify export**
+
+Run: `node -e "import('./server/services/markdown.js').then(m => console.log('ok:', typeof m.escapeAttr))"`
+Expected: `ok: function`
+
+**Step 4: Commit**
+
+```
+git add server/services/markdown.js
+git commit -m "feat: export escapeAttr from markdown.js and expose in plugin shortcode context"
+```
+
+---
+
+### Task 2: Dedicated `[scribe]` shortcode handler with action parsing
+
+**Files:**
+
+- Modify: `plugins/domma-effects/plugin.js`
+
+**Step 1: Remove `'scribe'` from the generic loop**
+
+Change line ~66 from:
+
+```
+for (const name of ['reveal', 'breathe', 'pulse', 'shake', 'scribe', 'scramble', 'ripple', 'twinkle']) {
+```
+
+to:
+
+```
+for (const name of ['reveal', 'breathe', 'pulse', 'shake', 'scramble', 'ripple', 'twinkle']) {
+```
+
+**Step 2: Insert dedicated scribe handler before the generic loop**
+
+```js
+registerShortcode('scribe', (attrStr, body, ctx) => {
+  if (body === null) return '';
+  const attrs = ctx.parseShortcodeAttrs(attrStr);
+  const dataAttrs = Object.entries(attrs).map(([k, v]) => ` data-fx-${k}="${v}"`).join('');
+
+  // Script mode: body contains at least one [render], [wait], or [undo] action shortcode
+  const hasActions = /\[\s*(render|wait|undo)\b/.test(body);
+
+  if (!hasActions) {
+    // Legacy path - single render from body text (backward compat)
+    const innerHtml = ctx.marked.parse(ctx.processCardBlocks(ctx.processGridBlocks(body.trim())));
+    return `<div class="dm-fx-scribe"${dataAttrs}>${innerHtml}</div>\n`;
+  }
+
+  // Script path - parse inner action shortcodes in document order
+  const actions = [];
+  const actionRe = /\[render([^\]]*)\]([\s\S]*?)\[\/render\]|\[wait\]([\s\S]*?)\[\/wait\]|\[undo([^\]]*?)\/\]/gi;
+  let match;
+  while ((match = actionRe.exec(body)) !== null) {
+    if (match[0].startsWith('[render')) {
+      const rAttrs = ctx.parseShortcodeAttrs(match[1] || '');
+      const action = {render: match[2].trim()};
+      if (rAttrs.effect) action.effect = rAttrs.effect;
+      actions.push(action);
+    } else if (match[0].startsWith('[wait')) {
+      const val = match[3].trim();
+      actions.push({wait: isNaN(val) ? val : parseInt(val, 10)});
+    } else {
+      const uAttrs = ctx.parseShortcodeAttrs(match[4] || '');
+      if (uAttrs.all === 'true') {
+        actions.push({undoRender: 'all'});
+      } else if (uAttrs.count) {
+        actions.push({undoRender: parseInt(uAttrs.count, 10)});
+      } else {
+        actions.push({undoRender: true});
+      }
+    }
+  }
+
+  if (!actions.length) return '';
+
+  const actionsJson = ctx.escapeAttr(JSON.stringify(actions));
+  return `<span class="dm-fx-scribe"${dataAttrs} data-fx-actions="${actionsJson}"></span>\n`;
+}, {priority: 5});
+```
+
+**Step 3: Smoke-test script mode**
+
+Run:
+
+```
+node -e "import('./server/services/markdown.js').then(({parseMarkdown}) => { const {html} = parseMarkdown('---\ntitle: T\n---\n[scribe loop=\"true\"]\n[render effect=\"fade\"]Hello[/render]\n[wait]1s[/wait]\n[undo /]\n[render]World[/render]\n[/scribe]'); console.log('span:', html.includes('dm-fx-scribe')); console.log('actions:', html.includes('data-fx-actions')); console.log('loop:', html.includes('data-fx-loop')); })"
+```
+
+Expected: `span: true`, `actions: true`, `loop: true`
+
+**Step 4: Smoke-test legacy mode is unchanged**
+
+Run:
+
+```
+node -e "import('./server/services/markdown.js').then(({parseMarkdown}) => { const {html} = parseMarkdown('---\ntitle: T\n---\n[scribe speed=\"50\"]Hello World[/scribe]'); console.log('div:', html.includes('<div class=\"dm-fx-scribe\"')); console.log('text:', html.includes('Hello World')); })"
+```
+
+Expected: `div: true`, `text: true`
+
+**Step 5: Commit**
+
+```
+git add plugins/domma-effects/plugin.js
+git commit -m "feat: dedicated [scribe] handler with [render]/[wait]/[undo] action script support"
+```
+
+---
+
+### Task 3: Update `inject-body.html` to read `data-fx-actions` and wire new options
+
+**Files:**
+
+- Modify: `plugins/domma-effects/public/inject-body.html`
+
+**Step 1: Replace the `.dm-fx-scribe` handler block**
+
+Find the existing block (lines ~218-229):
+
+```js
+body.querySelectorAll('.dm-fx-scribe').forEach(function (el) {
+  var opts = {};
+  if (attr(el, 'speed')) opts.speed = numAttr(el, 'speed', 50);
+  if (attr(el, 'cursor')) opts.cursor = boolAttr(el, 'cursor', true);
+  if (attr(el, 'mode')) opts.mode = attr(el, 'mode');
+  if (attr(el, 'loop')) opts.loop = boolAttr(el, 'loop', false);
+  var text = el.textContent.trim();
+  if (!text) return;
+  el.textContent = '';
+  opts.actions = [{render: text}];
+  E.scribe(el, opts);
+});
+```
+
+Replace with:
+
+```js
+body.querySelectorAll('.dm-fx-scribe').forEach(function (el) {
+  var opts = {};
+  if (attr(el, 'speed'))          opts.speed        = numAttr(el, 'speed', 50);
+  if (attr(el, 'delete-speed'))   opts.deleteSpeed  = numAttr(el, 'delete-speed', 30);
+  if (attr(el, 'cursor'))         opts.cursor       = boolAttr(el, 'cursor', true);
+  if (attr(el, 'cursor-char'))    opts.cursorChar   = attr(el, 'cursor-char');
+  if (attr(el, 'cursor-type'))    opts.cursorType   = attr(el, 'cursor-type');
+  if (attr(el, 'mode'))           opts.mode         = attr(el, 'mode');
+  if (attr(el, 'loop'))           opts.loop         = boolAttr(el, 'loop', false);
+  if (attr(el, 'loop-delay'))     opts.loopDelay    = numAttr(el, 'loop-delay', 1000);
+  if (attr(el, 'pause-on-hover')) opts.pauseOnHover = boolAttr(el, 'pause-on-hover', false);
+
+  var actionsAttr = attr(el, 'actions');
+  if (actionsAttr) {
+    try { opts.actions = JSON.parse(actionsAttr); } catch (e) { return; }
+    el.textContent = '';
+  } else {
+    var text = el.textContent.trim();
+    if (!text) return;
+    el.textContent = '';
+    opts.actions = [{render: text}];
+  }
+  E.scribe(el, opts);
+});
+```
+
+**Step 2: Commit**
+
+```
+git add plugins/domma-effects/public/inject-body.html
+git commit -m "feat: read data-fx-actions in scribe client init; expose deleteSpeed, cursorChar, cursorType, loopDelay, pauseOnHover"
+```
+
+---
+
+### Task 4: Update Domma Effects admin docs
+
+**Files:**
+
+- Modify: `plugins/domma-effects/admin/templates/domma-effects.html`
+
+**Step 1: Replace the Scribe section (lines ~178-183)**
+
+Find:
+
+```html
+<h3 class="mb-2">Typewriter (Scribe)</h3>
+<p class="text-muted mb-2">Types text character by character. Perfect for hero taglines or code
+  demonstrations.</p>
+<pre class="code-block mb-3">[scribe speed="50" cursor="true" loop="false"]
+Your text appears letter by letter.
+[/scribe]</pre>
+```
+
+Replace with:
+
+```html
+<h3 class="mb-2">Typewriter (Scribe)</h3>
+<p class="text-muted mb-2">Types text character by character. Supports a multi-step <strong>script</strong> of render, wait, and undo actions for looping typewriter sequences.</p>
+
+<p class="text-muted mb-1" style="font-size:.85rem;"><strong>Simple (single phrase):</strong></p>
+<pre class="code-block mb-3">[scribe speed="50" cursor="true" loop="false"]
+Your text appears letter by letter.
+[/scribe]</pre>
+
+<p class="text-muted mb-1" style="font-size:.85rem;"><strong>Script (multi-step sequence):</strong></p>
+<pre class="code-block mb-2">[scribe loop="true" loop-delay="1000" delete-speed="30"]
+[render effect="fade"]Hello, World![/render]
+[wait]1.5s[/wait]
+[undo /]
+[render]Something else entirely.[/render]
+[wait]2s[/wait]
+[undo all="true" /]
+[/scribe]</pre>
+
+<table class="table mb-2" style="font-size:.85rem;">
+  <thead><tr><th>Action</th><th>Description</th></tr></thead>
+  <tbody>
+  <tr><td><code>[render effect="fade"]text[/render]</code></td><td>Type text. effect: none, fade, bounce, glow</td></tr>
+  <tr><td><code>[wait]1.5s[/wait]</code></td><td>Pause. Accepts ms, s, or bare number (ms)</td></tr>
+  <tr><td><code>[undo /]</code></td><td>Delete the last render</td></tr>
+  <tr><td><code>[undo all="true" /]</code></td><td>Delete everything typed so far</td></tr>
+  <tr><td><code>[undo count="5" /]</code></td><td>Delete exactly N characters</td></tr>
+  </tbody>
+</table>
+
+<table class="table mb-3" style="font-size:.85rem;">
+  <thead><tr><th>Attribute</th><th>Default</th><th>Description</th></tr></thead>
+  <tbody>
+  <tr><td><code>speed</code></td><td>50</td><td>Typing speed (ms/char)</td></tr>
+  <tr><td><code>delete-speed</code></td><td>30</td><td>Deletion speed (ms/char)</td></tr>
+  <tr><td><code>cursor</code></td><td>true</td><td>Show cursor</td></tr>
+  <tr><td><code>cursor-type</code></td><td>caret</td><td>caret, block, underline</td></tr>
+  <tr><td><code>cursor-char</code></td><td>|</td><td>Custom cursor character</td></tr>
+  <tr><td><code>mode</code></td><td>typewriter</td><td>typewriter, word, sentence</td></tr>
+  <tr><td><code>loop</code></td><td>false</td><td>true to loop, or a repeat count</td></tr>
+  <tr><td><code>loop-delay</code></td><td>1000</td><td>Pause between loops (ms)</td></tr>
+  <tr><td><code>pause-on-hover</code></td><td>false</td><td>Pause typing while hovered</td></tr>
+  </tbody>
+</table>
+```
+
+**Step 2: Commit**
+
+```
+git add plugins/domma-effects/admin/templates/domma-effects.html
+git commit -m "docs: add Scribe script syntax and full attribute table to effects admin"
+```
+
+---
+
+### Task 5: Update page editor shortcode help
+
+**Files:**
+
+- Modify: `admin/js/views/page-editor.js`
+
+**Step 1: Update the scribe row description (around line 284)**
+
+Change:
+
+```js
+['[scribe speed="50"]...[/scribe]', 'Typewriter character-by-character'],
+```
+
+to:
+
+```js
+['[scribe speed="50"]...[/scribe]', 'Typewriter - plain text or multi-step script'],
+```
+
+**Step 2: Add Scribe script snippet after `section5.appendChild(effectsTable)` (around line 310)**
+
+```js
+section5.appendChild(makeSnippet(
+  'Scribe - multi-step script',
+  '[scribe loop="true" loop-delay="1000"]\n[render effect="fade"]Hello, World![/render]\n[wait]1.5s[/wait]\n[undo /]\n[render]Something else.[/render]\n[wait]2s[/wait]\n[undo all="true" /]\n[/scribe]',
+  'Actions: [render effect="fade|bounce|glow"]text[/render] · [wait]1.5s[/wait] · [undo /] · [undo all="true" /] · [undo count="5" /]'
+));
+```
+
+**Step 3: Commit**
+
+```
+git add admin/js/views/page-editor.js
+git commit -m "docs: add Scribe multi-step script snippet to page editor help"
+```
+
+---
+
+## Final Verification
+
+```
+node -e "
+import('./server/services/markdown.js').then(({parseMarkdown}) => {
+  const src = \`---
+title: T
+---
+[scribe loop=\"true\" delete-speed=\"25\" cursor-type=\"block\"]
+[render effect=\"bounce\"]Step one[/render]
+[wait]500ms[/wait]
+[undo /]
+[render]Step two[/render]
+[wait]1s[/wait]
+[undo count=\"4\" /]
+[render]Done.[/render]
+[/scribe]\`;
+  const {html} = parseMarkdown(src);
+  const m = html.match(/data-fx-actions=\\\"([^\\\"]*)\\\"/);
+  if (!m) { console.error('FAIL: no data-fx-actions'); process.exit(1); }
+  const decoded = m[1].replace(/&quot;/g,'\"').replace(/&amp;/g,'&');
+  const actions = JSON.parse(decoded);
+  console.log('actions.length === 6:', actions.length === 6);
+  console.log('render effect bounce:', actions[0].effect === 'bounce');
+  console.log('wait 500ms:', actions[1].wait === '500ms');
+  console.log('undoRender true:', actions[2].undoRender === true);
+  console.log('undoRender count 4:', actions[5].undoRender === 4);
+  console.log('loop attr:', html.includes('data-fx-loop=\"true\"'));
+  console.log('PASS');
+}).catch(e => console.error('ERROR:', e.message));
+"
+```

package/docs/plans/2026-03-05-user-types-design.md

@@ -0,0 +1,139 @@
+# User Types - Design Document
+
+**Date:** 2026-03-05
+**Status:** Approved
+**Approach:** Option A - Preset Collection (full dynamic roles)
+
+---
+
+## Overview
+
+The Users admin view gains a second tab - **User Types** - backed by a preset Collection. Roles become runtime-dynamic: stored in `content/collections/user-types/data.json`, read at startup, cached in memory, and invalidated on CRUD. `config/auth.json` is stripped back to JWT/bcrypt config only.
+
+---
+
+## Data Model
+
+### Preset Collection: `user-types`
+
+**Location:** `content/collections/user-types/`
+
+```
+schema.json  - field definitions (locked - preset: true)
+data.json    - role entries (fully editable via admin)
+```
+
+**Schema fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | text | Slug-style key (`editor`). Unique. |
+| `label` | text | Display name (`Editor`) |
+| `level` | number | Access hierarchy - lower = more privileged |
+| `permissions` | multi-select | Which resources this role can access |
+| `badgeClass` | select | Badge CSS class (`badge-info` etc.) |
+
+**`config/auth.json` after migration:**
+
+```json
+{
+    "accessTokenExpiry": "15m",
+    "refreshTokenExpiry": "7d",
+    "bcryptRounds": 10
+}
+```
+
+Roles and permissions blocks are removed entirely from `auth.json`.
+
+---
+
+## Auth Middleware
+
+### Startup
+
+`server.js` calls `loadUserTypes()` before registering routes. This reads `data.json` and builds two in-memory maps:
+
+```js
+roleMap:        { admin: { label, level }, editor: { label, level }, ... }
+permissionsMap: { pages: ['admin','manager','editor'], ... }  // inverted from role-centric entries
+```
+
+### Cache Strategy
+
+- Loaded once at startup
+- Invalidated and reloaded on User Type create/update/delete (event-driven, no TTL)
+- File is small - synchronous-equivalent performance
+
+### Bootstrap Protection
+
+- `admin` role (level 0) cannot be deleted
+- Delete route returns 403 if `entry.data.level === 0`
+
+---
+
+## Seeding
+
+`seedPresetCollections()` runs at startup before routes register:
+
+1. Check if `content/collections/user-types/data.json` exists
+2. If **not** → create directory, write `schema.json` + seed `data.json`
+3. If **yes** → skip (user data preserved)
+
+**Seed roles:**
+
+```json
+[
+  { "data": { "name": "admin",      "label": "Admin",      "level": 0, "permissions": ["pages","settings","navigation","layouts","media","users","plugins","collections"], "badgeClass": "badge-danger"    } },
+  { "data": { "name": "manager",    "label": "Manager",    "level": 1, "permissions": ["pages","settings","navigation","layouts","media","users","collections"],            "badgeClass": "badge-warning"   } },
+  { "data": { "name": "editor",     "label": "Editor",     "level": 2, "permissions": ["pages","media"],                                                                   "badgeClass": "badge-info"      } },
+  { "data": { "name": "subscriber", "label": "Subscriber", "level": 3, "permissions": [],                                                                                  "badgeClass": "badge-secondary" } }
+]
+```
+
+---
+
+## Admin UI
+
+**`admin/js/views/users.js`** - wrapped in `E.tabs()`:
+
+- **Tab 1: Users** - existing `T.create()` table, unchanged
+- **Tab 2: User Types** - own `T.create()` table, reads `/api/collections/user-types/entries`
+
+User Types table features:
+- Add button → modal form (name, label, level, permissions checkboxes, badge colour)
+- Edit → same modal pre-populated
+- Delete → `E.confirm()` guard, disabled for admin (level 0)
+- Badge colour rendered live in table rows
+
+**`admin/js/templates/users.html`** structure:
+
+```html
+<div class="view-header">...</div>
+<div class="tabs">
+  <div class="tab-list">
+    <button class="tab-item active">Users</button>
+    <button class="tab-item">User Types</button>
+  </div>
+  <div class="tab-content">
+    <div class="tab-panel active" id="panel-users">...</div>
+    <div class="tab-panel" id="panel-user-types">...</div>
+  </div>
+</div>
+```
+
+---
+
+## Files Changed
+
+| File | Action |
+|---|---|
+| `server/server.js` | Call `seedPresetCollections()` + `loadUserTypes()` at startup |
+| `server/services/userTypes.js` | New - seed, load, cache, invalidate, invert permissions |
+| `server/routes/api/users.js` | Middleware reads from `userTypes` cache instead of `auth.json` |
+| `server/routes/api/collections.js` | CRUD routes call `userTypes.invalidate()` for `user-types` slug |
+| `config/auth.json` | Remove `roles` + `permissions` blocks |
+| `content/collections/user-types/schema.json` | Seeded at startup |
+| `content/collections/user-types/data.json` | Seeded at startup |
+| `admin/js/views/users.js` | Add tabs + User Types table + modal |
+| `admin/js/templates/users.html` | Add tabs structure |
+| `docs/structure/user-types.md` | New - structure documentation |