@caretcms/core 0.1.0 → 0.1.1

package/static/cms/dev-toolbar/app.js

@@ -0,0 +1,263 @@
+import { defineToolbarApp } from "astro/toolbar";
+
+// CaretCMS Dev Toolbar app — a login-free, dev-only view of the data-caret
+// bindings on the current page. It complements the in-editor "Show All" button
+// (static/cms/editor/toolbar.js), which only works once an editor session is
+// authenticated. This runs in `astro dev` for anyone, with no login.
+//
+// The binding resolver below mirrors static/cms/editor/helpers.js. It is
+// inlined (rather than imported from /__caret/editor/helpers.js) so the toolbar
+// keeps working in `output: 'static'` projects where /__caret/ is not served.
+// If helpers.js changes, keep these two in sync.
+
+function parseCaretAttr(attr) {
+  const parts = attr.split("::");
+  if (parts.length === 3) return { collection: parts[0], id: parts[1], field: parts[2] };
+  if (parts.length === 1 && !attr.includes("::")) return { collection: null, id: null, field: attr };
+  return null;
+}
+
+function resolveBinding(el, parsed) {
+  if (!parsed) return null;
+  if (parsed.collection && parsed.id) return parsed;
+  let node = el.parentElement;
+  while (node) {
+    const scope = node.getAttribute("data-caret-scope");
+    if (scope) {
+      const parts = scope.split("::");
+      if (parts.length === 2) return { collection: parts[0], id: parts[1], field: parsed.field };
+    }
+    node = node.parentElement;
+  }
+  return null;
+}
+
+function devConfig() {
+  const c = (typeof window !== "undefined" && window.__CARET_DEV__) || {};
+  return {
+    mountPath: typeof c.mountPath === "string" ? c.mountPath : "/admin",
+    apiBasePath: typeof c.apiBasePath === "string" ? c.apiBasePath : "/api/cms",
+  };
+}
+
+function classify(el) {
+  if (el.tagName.toLowerCase() === "img") return "image";
+  if (el.hasAttribute("data-caret-rich")) return "rich";
+  return "text";
+}
+
+// Walk the page and resolve every data-caret element to a full key, splitting
+// out orphans (field-only attrs with no resolvable scope) and duplicate keys.
+function scanBindings() {
+  const els = Array.from(document.querySelectorAll("[data-caret]"));
+  const bindings = [];
+  const orphans = [];
+
+  els.forEach((el, i) => {
+    const attr = el.getAttribute("data-caret") || "";
+    const parsed = parseCaretAttr(attr);
+    const resolved = resolveBinding(el, parsed);
+    const kind = classify(el);
+    if (!resolved) {
+      orphans.push({ el, attr, kind, index: i });
+      return;
+    }
+    bindings.push({
+      el,
+      index: i,
+      collection: resolved.collection,
+      id: resolved.id,
+      field: resolved.field,
+      key: `${resolved.collection}::${resolved.id}::${resolved.field}`,
+      kind,
+    });
+  });
+
+  const counts = new Map();
+  bindings.forEach((b) => counts.set(b.key, (counts.get(b.key) || 0) + 1));
+  const duplicates = bindings.filter((b) => counts.get(b.key) > 1);
+
+  // Stega-encoded bindings (live-loader content) only become real data-caret
+  // attributes after the editor's stega-hydrate.js runs, which needs auth — so
+  // a logged-out scan can undercount. Detect the U+E0000 markers to warn.
+  const stega = /\u{E0000}/u.test((document.body && document.body.textContent) || "");
+
+  return { bindings, orphans, duplicates, stega, total: els.length };
+}
+
+// --- login-free highlight: our own outline CSS keyed on [data-caret] directly,
+// so it does NOT depend on the editor's .cms-editable class or editor.css.
+// Colors are deliberately distinct from the editor's blue scheme so the two can
+// be told apart when both are active at once.
+const HIGHLIGHT_STYLE_ID = "__caret-devtoolbar-highlight__";
+
+function applyHighlight(active) {
+  const existing = document.getElementById(HIGHLIGHT_STYLE_ID);
+  if (existing) existing.remove();
+  if (!active) return;
+  const style = document.createElement("style");
+  style.id = HIGHLIGHT_STYLE_ID;
+  style.textContent = `
+    [data-caret]{outline:2px solid #6366f1 !important;outline-offset:2px;}
+    [data-caret][data-caret-rich]{outline-color:#10b981 !important;}
+    img[data-caret]{outline:2px dashed #f59e0b !important;outline-offset:4px;}
+  `;
+  document.head.appendChild(style);
+}
+
+function scrollTo(el) {
+  el.scrollIntoView({ behavior: "smooth", block: "center" });
+  const prev = el.style.outline;
+  const prevOffset = el.style.outlineOffset;
+  el.style.outline = "3px solid #6366f1";
+  el.style.outlineOffset = "3px";
+  setTimeout(() => {
+    el.style.outline = prev;
+    el.style.outlineOffset = prevOffset;
+  }, 1500);
+}
+
+const KIND_LABEL = { text: "text", image: "image", rich: "rich" };
+
+function esc(s) {
+  return String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+}
+
+const PANEL_CSS = `
+  :host{all:initial;}
+  astro-dev-toolbar-window{width:min(440px,100%) !important;height:auto !important;}
+  .wrap{font-family:system-ui,-apple-system,sans-serif;color:#e2e8f0;width:100%;max-height:min(70vh,520px);display:flex;flex-direction:column;}
+  .head{display:flex;align-items:center;justify-content:space-between;gap:8px;padding:2px 2px 10px;border-bottom:1px solid rgba(255,255,255,.1);}
+  .title{font-size:13px;font-weight:600;}
+  .count{font-size:11px;color:#94a3b8;}
+  .actions{display:flex;gap:6px;padding:10px 2px;}
+  button.btn{font:inherit;font-size:12px;cursor:pointer;border:1px solid rgba(255,255,255,.15);background:rgba(255,255,255,.05);color:#e2e8f0;border-radius:6px;padding:5px 10px;}
+  button.btn:hover{background:rgba(255,255,255,.12);}
+  button.btn.on{background:#6366f1;border-color:#6366f1;color:#fff;}
+  .scroll{overflow-y:auto;flex:1;padding-right:2px;}
+  .note{font-size:11px;color:#fbbf24;background:rgba(251,191,36,.08);border:1px solid rgba(251,191,36,.2);border-radius:6px;padding:6px 8px;margin:8px 0;}
+  .problem{font-size:11px;color:#f87171;background:rgba(248,113,113,.08);border:1px solid rgba(248,113,113,.2);border-radius:6px;padding:6px 8px;margin:8px 0;}
+  .problem b{color:#fca5a5;}
+  .group{margin:10px 0 0;}
+  .ghead{display:flex;align-items:center;justify-content:space-between;gap:6px;font-size:11px;font-weight:600;color:#cbd5e1;padding:4px 0;border-bottom:1px solid rgba(255,255,255,.06);}
+  .ghead a{color:#818cf8;text-decoration:none;font-weight:500;white-space:nowrap;}
+  .ghead a:hover{text-decoration:underline;}
+  .row{display:flex;align-items:center;gap:8px;padding:5px 2px;border-bottom:1px solid rgba(255,255,255,.04);}
+  .field{flex:1;font-size:12px;color:#e2e8f0;font-family:ui-monospace,monospace;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+  .kind{font-size:9px;text-transform:uppercase;letter-spacing:.04em;padding:1px 5px;border-radius:4px;font-weight:600;}
+  .kind.text{background:rgba(99,102,241,.2);color:#a5b4fc;}
+  .kind.image{background:rgba(245,158,11,.2);color:#fcd34d;}
+  .kind.rich{background:rgba(16,185,129,.2);color:#6ee7b7;}
+  .jump{font:inherit;font-size:11px;cursor:pointer;border:none;background:transparent;color:#94a3b8;padding:2px 4px;border-radius:4px;}
+  .jump:hover{color:#e2e8f0;background:rgba(255,255,255,.08);}
+  .empty{font-size:12px;color:#94a3b8;padding:16px 2px;text-align:center;}
+  .dup{color:#fca5a5;}
+`;
+
+export default defineToolbarApp({
+  init(canvas, app) {
+    const style = document.createElement("style");
+    style.textContent = PANEL_CSS;
+    canvas.appendChild(style);
+
+    const win = document.createElement("astro-dev-toolbar-window");
+    const wrap = document.createElement("div");
+    wrap.className = "wrap";
+    win.appendChild(wrap);
+    canvas.appendChild(win);
+
+    let highlightOn = false;
+    let scan = { bindings: [], orphans: [], duplicates: [], stega: false, total: 0 };
+
+    function render() {
+      scan = scanBindings();
+      const { mountPath } = devConfig();
+      const { bindings, orphans, duplicates, stega, total } = scan;
+
+      // Group bindings by collection::id, preserving first-seen order.
+      const groups = new Map();
+      for (const b of bindings) {
+        const gk = `${b.collection}::${b.id}`;
+        if (!groups.has(gk)) groups.set(gk, []);
+        groups.get(gk).push(b);
+      }
+
+      const dupKeys = new Set(duplicates.map((d) => d.key));
+
+      let html = `
+        <div class="head">
+          <span class="title">CaretCMS bindings</span>
+          <span class="count">${bindings.length} on page${orphans.length ? ` · ${orphans.length} orphan${orphans.length > 1 ? "s" : ""}` : ""}</span>
+        </div>
+        <div class="actions">
+          <button class="btn ${highlightOn ? "on" : ""}" data-action="highlight">${highlightOn ? "Hide" : "Highlight"} all</button>
+          <button class="btn" data-action="rescan">Rescan</button>
+        </div>
+        <div class="scroll">`;
+
+      if (stega) {
+        html += `<div class="note">This page has stega-encoded bindings (live-loader content). They become visible only when the editor is loaded — sign in to see them here.</div>`;
+      }
+      if (orphans.length) {
+        html += `<div class="problem"><b>${orphans.length} orphan binding${orphans.length > 1 ? "s" : ""}</b> — field-only <code>data-caret</code> with no resolvable <code>data-caret-scope</code> ancestor: ${orphans.map((o) => `<code>${esc(o.attr)}</code>`).join(", ")}</div>`;
+      }
+      if (duplicates.length) {
+        const uniq = Array.from(new Set(duplicates.map((d) => d.key)));
+        html += `<div class="problem"><b>${uniq.length} duplicate key${uniq.length > 1 ? "s" : ""}</b> — same binding used more than once: ${uniq.map((k) => `<code>${esc(k)}</code>`).join(", ")}</div>`;
+      }
+
+      if (!bindings.length && !orphans.length) {
+        html += `<div class="empty">No <code>data-caret</code> bindings found on this page.${total ? "" : ""}</div>`;
+      }
+
+      for (const [gk, rows] of groups) {
+        const [collection, id] = gk.split("::");
+        const studioHref = `${mountPath}/cms/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`;
+        html += `<div class="group">
+          <div class="ghead"><span>${esc(gk)}</span><a href="${esc(studioHref)}" target="_blank" rel="noopener">Open in Studio ↗</a></div>`;
+        for (const b of rows) {
+          html += `<div class="row">
+            <span class="field ${dupKeys.has(b.key) ? "dup" : ""}">${esc(b.field)}</span>
+            <span class="kind ${b.kind}">${KIND_LABEL[b.kind]}</span>
+            <button class="jump" data-action="scroll" data-index="${b.index}">scroll to</button>
+          </div>`;
+        }
+        html += `</div>`;
+      }
+
+      html += `</div>`;
+      wrap.innerHTML = html;
+    }
+
+    function elementByIndex(index) {
+      const b = scan.bindings.find((x) => x.index === Number(index));
+      return b ? b.el : null;
+    }
+
+    wrap.addEventListener("click", (event) => {
+      const target = event.target.closest("[data-action]");
+      if (!target) return;
+      const action = target.getAttribute("data-action");
+      if (action === "highlight") {
+        highlightOn = !highlightOn;
+        applyHighlight(highlightOn);
+        app.toggleState({ state: highlightOn });
+        target.textContent = `${highlightOn ? "Hide" : "Highlight"} all`;
+        target.classList.toggle("on", highlightOn);
+      } else if (action === "rescan") {
+        render();
+      } else if (action === "scroll") {
+        const el = elementByIndex(target.getAttribute("data-index"));
+        if (el) scrollTo(el);
+      }
+    });
+
+    // Re-render each time the panel opens; flag problems with a notification dot.
+    app.onToggled(({ state }) => {
+      if (!state) return;
+      render();
+      const probs = scan.orphans.length + scan.duplicates.length;
+      app.toggleNotification({ state: probs > 0, level: "warning" });
+    });
+  },
+});

package/static/cms/editor/highlight.js

@@ -0,0 +1,46 @@
+/**
+ * Owns the `cms-highlight-all` body class — the single source of truth for
+ * "show every editable region". Two callers share it:
+ * - the toolbar "Show All" button, via the persistent `toggleHighlight` toggle
+ * - the post-login welcome reveal, via the ephemeral `revealAndFade`
+ *
+ * Keeping `highlightActive` here (rather than in the toolbar closure) lets the
+ * ephemeral reveal defer to an active manual toggle instead of clobbering it.
+ *
+ * The fade itself is pure CSS: `[data-caret].cms-editable` already transitions
+ * its outline, so adding/removing the class animates for free. Motion is
+ * suppressed for `prefers-reduced-motion` in toolbar.css, not here.
+ */
+
+let highlightActive = false;
+
+export function toggleHighlight(highlightBtn, showToast) {
+  highlightActive = !highlightActive;
+  document.body.classList.toggle('cms-highlight-all', highlightActive);
+  highlightBtn.classList.toggle('cms-highlight-btn-active', highlightActive);
+
+  const textNode = Array.from(highlightBtn.childNodes).find(
+    (n) => n.nodeType === 3 && n.textContent?.trim(),
+  );
+
+  if (highlightActive) {
+    if (textNode) textNode.textContent = ' Hide All';
+    showToast('Showing all editable regions', 'success');
+  } else {
+    if (textNode) textNode.textContent = ' Show All';
+  }
+}
+
+/**
+ * One-time reveal: flash every editable region, then fade out after `durationMs`.
+ * No-op if the user has already turned highlighting on manually, so it never
+ * desyncs the toolbar button's state.
+ */
+export function revealAndFade(durationMs = 2500) {
+  if (highlightActive) return;
+  document.body.classList.add('cms-highlight-all');
+  setTimeout(() => {
+    if (highlightActive) return;
+    document.body.classList.remove('cms-highlight-all');
+  }, durationMs);
+}

package/static/cms/editor/sanitize.js

@@ -15,24 +15,52 @@ const ALLOWED_ATTRS = {
 
 const SAFE_HREF_RE = /^(?:https?:|mailto:|tel:|\/)/i;
 
+/**
+ * Does `cls` match any pattern? (exact, `prefix-*`, or lone `*`)
+ * MUST stay identical to classAllowed() in src/runtime/sanitize-html.ts.
+ * @param {string} cls
+ * @param {readonly string[]} patterns
+ * @returns {boolean}
+ */
+function classAllowed(cls, patterns) {
+  for (const p of patterns) {
+    if (p === '*') return true;
+    if (p.endsWith('*')) {
+      if (cls.startsWith(p.slice(0, -1))) return true;
+    } else if (cls === p) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Sanitize an HTML string, keeping only allowed inline tags and attributes.
+ * Per-tag class allowlist comes from `options.allowedClasses`, falling back to
+ * `window.__CARET__.allowedClasses` so the client matches the server config.
  * @param {string} html
+ * @param {{ allowedClasses?: Record<string, readonly string[]> }} [options]
  * @returns {string}
  */
-export function sanitizeHtml(html) {
+export function sanitizeHtml(html, options) {
   if (!html) return '';
 
+  const allowedClasses =
+    options?.allowedClasses ??
+    (typeof window !== 'undefined' ? window.__CARET__?.allowedClasses : undefined) ??
+    null;
+
   const doc = new DOMParser().parseFromString(`<body>${html}</body>`, 'text/html');
-  sanitizeNode(doc.body);
+  sanitizeNode(doc.body, allowedClasses);
   return doc.body.innerHTML;
 }
 
 /**
  * Recursively sanitize a DOM node in place.
  * @param {Node} parent
+ * @param {Record<string, readonly string[]> | null} allowedClasses
  */
-function sanitizeNode(parent) {
+function sanitizeNode(parent, allowedClasses) {
   const children = Array.from(parent.childNodes);
 
   for (const node of children) {
@@ -57,14 +85,29 @@ function sanitizeNode(parent) {
       while (el.firstChild) frag.appendChild(el.firstChild);
       parent.replaceChild(frag, el);
       // Re-sanitize the newly promoted children
-      sanitizeNode(parent);
+      sanitizeNode(parent, allowedClasses);
       return;
     }
 
     // Strip disallowed attributes
     const allowed = ALLOWED_ATTRS[tag];
+    const classPatterns = allowedClasses ? allowedClasses[tag] : undefined;
     const attrs = Array.from(el.attributes);
     for (const attr of attrs) {
+      // class is gated by the per-tag allowlist, not ALLOWED_ATTRS
+      if (attr.name === 'class') {
+        if (!classPatterns) {
+          el.removeAttribute('class');
+          continue;
+        }
+        const kept = attr.value
+          .split(/\s+/)
+          .filter((c) => c !== '' && classAllowed(c, classPatterns))
+          .join(' ');
+        if (kept) el.setAttribute('class', kept);
+        else el.removeAttribute('class');
+        continue;
+      }
       if (!allowed || !allowed.has(attr.name)) {
         el.removeAttribute(attr.name);
       }
@@ -84,6 +127,6 @@ function sanitizeNode(parent) {
     }
 
     // Recurse into children
-    sanitizeNode(el);
+    sanitizeNode(el, allowedClasses);
   }
 }

package/static/cms/editor/stega-hydrate.js

@@ -0,0 +1,80 @@
+/**
+ * Stega hydration (browser side).
+ *
+ * Content fetched through the live loaders in draft mode carries its binding key
+ * (`collection::id::field`) hidden inside the string as invisible Unicode "tag"
+ * characters. This pass walks the rendered DOM, decodes that key from each text
+ * node, strips the invisible characters, and PROMOTES the containing element to
+ * a normal `data-caret` binding — so the existing text/image editors pick it up
+ * with zero changes. This is what makes prop-fed / component / loop content
+ * click-to-edit without any author-written attribute.
+ *
+ * Decode logic mirrors runtime/stega.ts (the editor bundle is hand-authored JS,
+ * separate from the TS runtime, so the few lines are intentionally duplicated).
+ */
+
+const TAG_BASE = 0xe0000;
+const TAG_MAX = 0xe007f;
+const START = String.fromCodePoint(TAG_BASE + 0x00);
+const END = String.fromCodePoint(TAG_BASE + 0x01);
+const TAG_RE = /[\u{E0000}-\u{E007F}]/gu;
+
+function fromBase64(b64) {
+  const binary = atob(b64);
+  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+
+export function stegaDecode(value) {
+  const start = value.indexOf(START);
+  if (start === -1) return undefined;
+  const end = value.indexOf(END, start + START.length);
+  if (end === -1) return undefined;
+  let b64 = '';
+  for (const ch of value.slice(start + START.length, end)) {
+    const cp = ch.codePointAt(0);
+    if (cp === undefined || cp < TAG_BASE || cp > TAG_MAX) return undefined;
+    b64 += String.fromCharCode(cp - TAG_BASE);
+  }
+  try {
+    return JSON.parse(fromBase64(b64));
+  } catch {
+    return undefined;
+  }
+}
+
+export function stegaClean(value) {
+  return value.replace(TAG_RE, '');
+}
+
+/**
+ * Find every stega-tagged text node under `root`, decode its key, strip the
+ * invisible characters, and tag the containing element with `data-caret`.
+ * Returns the number of elements newly promoted.
+ */
+export function hydrateStega(root) {
+  const scope = root || document.body;
+  if (!scope) return 0;
+
+  const walker = document.createTreeWalker(scope, NodeFilter.SHOW_TEXT);
+  const tagged = [];
+  let node = walker.nextNode();
+  while (node) {
+    if (node.nodeValue && node.nodeValue.indexOf(START) !== -1) tagged.push(node);
+    node = walker.nextNode();
+  }
+
+  let promoted = 0;
+  for (const textNode of tagged) {
+    const key = stegaDecode(textNode.nodeValue);
+    // Always strip the invisible characters so they never affect layout/copy.
+    textNode.nodeValue = stegaClean(textNode.nodeValue);
+    if (typeof key !== 'string' || key.indexOf('::') === -1) continue;
+
+    const el = textNode.parentElement;
+    if (!el || el.hasAttribute('data-caret')) continue; // explicit attr wins
+    el.setAttribute('data-caret', key);
+    promoted++;
+  }
+  return promoted;
+}

package/static/cms/editor/text-edit.js

@@ -57,6 +57,28 @@ export function mountTextEditors({
     if (isRich) el.classList.add('cms-rich');
     if (isLinkable) el.classList.add('cms-linkable');
 
+    // Plain-text fields render with HTML whitespace collapsing, but a
+    // contenteditable element exposes the raw source whitespace (newlines +
+    // indentation) verbatim. A paragraph authored across several indented
+    // source lines then shows large gaps in the editor that aren't in the
+    // final page — and, if edited, the raw whitespace leaks into the saved
+    // value. Collapse it once on mount so the editable text matches the
+    // rendered text and the snapshot/saved value stays clean. Rich fields are
+    // left alone — their whitespace is governed by their own HTML.
+    if (!isRich) {
+      if (isLinkable) {
+        const rawAttr = el.getAttribute('data-caret-raw') || '';
+        const collapsed = rawAttr.replace(/\s+/g, ' ').trim();
+        if (rawAttr !== collapsed) {
+          el.setAttribute('data-caret-raw', collapsed);
+          el.innerHTML = clientLinkify(collapsed);
+        }
+      } else {
+        const collapsed = (el.textContent || '').replace(/\s+/g, ' ').trim();
+        if (el.textContent !== collapsed) el.textContent = collapsed;
+      }
+    }
+
     el.addEventListener('focus', () => {
       if (isRich) {
         snapshots.set(el, el.innerHTML);

package/static/cms/editor/tokens-and-text.css

@@ -25,7 +25,7 @@
 
 [data-caret].cms-editable {
   cursor: text;
-  transition: outline 0.2s, box-shadow 0.2s;
+  transition: outline 0.2s, box-shadow 0.2s, background 0.4s;
   outline: 2px dashed transparent;
   outline-offset: 4px;
   border-radius: 2px;

package/static/cms/editor/toolbar.css

@@ -175,6 +175,39 @@
   color: rgba(59, 130, 246, 0.9);
 }
 
+/* The base `.cms-toolbar button` sets `display`, which overrides the default
+   [hidden] behavior — restore it so hidden draft actions actually disappear. */
+.cms-toolbar button[hidden] {
+  display: none;
+}
+
+/* Draft preview active — amber, signalling "unpublished" */
+.cms-toolbar button.cms-preview-btn-active {
+  background: rgba(234, 179, 8, 0.12);
+  border-color: rgba(234, 179, 8, 0.4);
+  color: var(--cms-yellow);
+}
+
+/* Publish — green */
+.cms-toolbar button.cms-publish-btn {
+  background: rgba(34, 197, 94, 0.12);
+  border-color: rgba(34, 197, 94, 0.3);
+  color: var(--cms-green);
+}
+
+.cms-toolbar button.cms-publish-btn:hover {
+  background: rgba(34, 197, 94, 0.25);
+  border-color: rgba(34, 197, 94, 0.5);
+  color: var(--cms-green);
+}
+
+/* Discard — red on hover */
+.cms-toolbar button.cms-discard-btn:hover {
+  background: rgba(248, 113, 113, 0.08);
+  border-color: rgba(248, 113, 113, 0.3);
+  color: var(--cms-red);
+}
+
 /* Highlight all mode — show every editable region */
 .cms-highlight-all [data-caret].cms-editable {
   outline-color: var(--cms-blue-hover);
@@ -186,6 +219,15 @@
   outline-offset: 4px;
 }
 
+/* The welcome reveal still flashes editable regions, but without animating the
+   transition — motion is suppressed, the information is not. */
+@media (prefers-reduced-motion: reduce) {
+  .cms-highlight-all [data-caret].cms-editable,
+  .cms-highlight-all img[data-caret] {
+    transition: none;
+  }
+}
+
 /* ---------------------------------------------------------------------------
    Toolbar — page navigation links
    --------------------------------------------------------------------------- */