ultimate-jekyll-manager 1.6.8 → 1.7.0

package/CHANGELOG.md

@@ -14,6 +14,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+---
+## [1.7.0] - 2026-06-09
+
+### Added
+
+- **Animation Studio admin page** (`/admin/studio`). New default admin page for creating screen-recording-ready product demo animation clips. Framework provides all boilerplate: sidebar, FormManager controls, resolution picker (540p–4K), aspect ratio toggle (16:9/9:16), playback loop with speed/pause controls, and 60fps tab recording via `getDisplayMedia` + `CropTarget`.
+- **Clip builder helpers** — `flowClip`, `cardClip`, `chatClip` passed alongside `animate`/`el` to clip `build()` functions. Consumers declare data, not structure.
+- **Studio CSS partial** (`_studio.scss`) — importable via `@use 'studio'` in consumer page CSS. Includes boilerplate layout + generic animation primitives (`.s-hidden`, `.s-step-bg`, `.s-bar-fill`).
+- **`docs/animation-studio.md`** — full reference for the clip contract, helpers, recording, resolution, aspect ratios.
+- **Admin sidebar entry** for Animation Studio under new "Content" section.
+
+---
+## [1.6.9] - 2026-06-08
+
+### Added
+
+- **Bootstrap-first theming convention.** Added comprehensive guidance to `docs/themes.md` and the default consumer `CLAUDE.md` — themes must restyle Bootstrap classes, not create parallel design systems.
+- **Dev workflow documentation.** Added explicit instructions to `CLAUDE.md` and consumer defaults to check `logs/dev.log` instead of running `npm start`/`npm test` in consumer projects.
+
+### Fixed
+
+- **Signup metadata failure notification timeout.** Changed dev-only notification from permanent (`timeout: 0`) to 1 second (`timeout: 1000`) so it doesn't block the screen during development.
+
 ---
 ## [1.6.8] - 2026-06-07
 

package/CLAUDE.md

@@ -158,6 +158,10 @@ Same `{ layer, description, run(ctx) }` contract as EM/BXM. JSON-line reporter p
 
 Note: `-t` short alias belongs to `translation`. The `test` command uses `--test` flag + `test` positional only. See [docs/cli.md](docs/cli.md) (planned).
 
+## Development Workflow
+
+- **🚫 NEVER run `npm start` / `npm run build` / `npm test` in a consumer project** unless the user explicitly asks. The user runs the dev server — running it again kills theirs. Instead, **check `logs/dev.log`** after editing files to confirm the watcher recompiled successfully (`Reloading Browsers...` = success; `errored` = fix the error). If editing multiple files, check the log once after the last edit. A change that breaks the build is not a completed change.
+
 ## File Conventions
 
 - **CommonJS** in build-time / Node files (gulp tasks, commands, lib/). **ESM** in `src/index.js` (frontend Manager — webpack-bundled).
@@ -201,6 +205,7 @@ Deep references live in `docs/`. Treat docs as a first-class deliverable. **When
 
 ### Pages, layouts, content
 
+- [docs/animation-studio.md](docs/animation-studio.md) — Animation Studio admin page: clip registration via `window.STUDIO_CLIPS`, helpers (`animate`, `el`, `flowClip`, `cardClip`, `chatClip`), resolution picker, recording, aspect ratio modes
 - [docs/themes.md](docs/themes.md) — theme system: selection + resolution (SCSS loadPaths, `__theme__`, classy layout fallback), shared vs per-theme layers, authoring a theme inside UJM OR in a consumer project, live validation
 - [docs/layouts-and-pages.md](docs/layouts-and-pages.md) — page types, layout chain, `asset_path` frontmatter
 - [docs/images.md](docs/images.md) — `@post/` shortcut for blog post images, BEM admin/post image handling, imagemin pipeline + source-size constraints + `UJ_IMAGEMIN_REWRITE_SOURCES` cleanup flag

package/dist/assets/css/_studio.scss

@@ -0,0 +1,229 @@
+// ============================================
+// Studio Layout — theme-agnostic boilerplate
+// Forces a fullscreen dark takeover regardless
+// of whatever theme chrome wraps the page.
+// ============================================
+body:has(#studio:not([hidden])) {
+  overflow: hidden !important;
+  background: #111 !important;
+}
+
+#studio {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+  display: flex;
+  background: #0d0d0d;
+  color: #f5f5f5;
+  overflow: hidden;
+}
+
+// ============================================
+// Sidebar nav
+// ============================================
+#studio-nav {
+  width: 240px;
+  flex-shrink: 0;
+  background: rgba(0, 0, 0, 0.3);
+  border-right: 1px solid rgba(255, 255, 255, 0.08);
+  padding: 24px 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  z-index: 10;
+}
+
+.studio-brand {
+  font-weight: 700;
+  font-size: 1.1rem;
+  color: var(--bs-primary, #0d6efd);
+  padding-bottom: 16px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+}
+
+.studio-clips {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  flex: 1;
+  overflow-y: auto;
+}
+
+.studio-clip-btn {
+  background: transparent;
+  border: none;
+  color: rgba(255, 255, 255, 0.6);
+  text-align: left;
+  padding: 10px 14px;
+  border-radius: 8px;
+  font-size: 0.88rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all 0.15s ease;
+
+  &:hover {
+    color: #f5f5f5;
+    background: rgba(255, 255, 255, 0.06);
+  }
+
+  &.active {
+    color: #fff;
+    background: var(--bs-primary, #0d6efd);
+  }
+}
+
+// ============================================
+// Controls panel
+// ============================================
+.studio-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding-top: 16px;
+  border-top: 1px solid rgba(255, 255, 255, 0.08);
+
+  fieldset {
+    border: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+
+    &:disabled { opacity: 0.4; pointer-events: none; }
+  }
+}
+
+.studio-label {
+  font-size: 0.72rem;
+  font-family: var(--bs-font-monospace, monospace);
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: rgba(255, 255, 255, 0.4);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+
+  input, select {
+    background: rgba(255, 255, 255, 0.08);
+    border: 1px solid rgba(255, 255, 255, 0.12);
+    border-radius: 6px;
+    color: #f5f5f5;
+    padding: 4px 8px;
+    font-size: 0.82rem;
+  }
+
+  input[type="range"] {
+    padding: 0;
+    accent-color: var(--bs-primary, #0d6efd);
+  }
+}
+
+.studio-aspect-btn,
+.studio-toggle-btn {
+  flex: 1;
+  background: rgba(255, 255, 255, 0.06);
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 6px;
+  color: rgba(255, 255, 255, 0.5);
+  padding: 6px 12px;
+  font-size: 0.78rem;
+  font-weight: 700;
+  font-family: var(--bs-font-monospace, monospace);
+  cursor: pointer;
+  transition: all 0.15s ease;
+
+  &:hover { color: #f5f5f5; background: rgba(255, 255, 255, 0.1); }
+  &.active { background: var(--bs-primary, #0d6efd); color: #fff; border-color: var(--bs-primary, #0d6efd); }
+}
+
+.studio-play-btn {
+  background: rgba(255, 255, 255, 0.08);
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  border-radius: 8px;
+  color: #f5f5f5;
+  padding: 8px;
+  font-size: 0.85rem;
+  font-weight: 600;
+  cursor: pointer;
+
+  &:hover { background: rgba(255, 255, 255, 0.14); }
+}
+
+.studio-record-btn {
+  background: rgba(220, 53, 69, 0.15);
+  border: 1px solid rgba(220, 53, 69, 0.4);
+  border-radius: 8px;
+  color: #f5f5f5;
+  padding: 8px;
+  font-size: 0.85rem;
+  font-weight: 600;
+  cursor: pointer;
+
+  &:hover { background: rgba(220, 53, 69, 0.3); }
+  &.recording {
+    background: rgba(220, 53, 69, 0.5);
+    border-color: #dc3545;
+    animation: studio-pulse-record 1s ease infinite;
+  }
+}
+
+@keyframes studio-pulse-record {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.6; }
+}
+
+// ============================================
+// Stage — where animations render
+// ============================================
+#studio-stage {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  overflow: hidden;
+}
+
+#studio-canvas {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 40px;
+  border: 2px dashed rgba(0, 0, 0, 0.15);
+  border-radius: 8px;
+  transition: width 0.4s ease, height 0.4s ease;
+
+  background: var(--lm-paper, #FAF5EC);
+  color: var(--lm-ink, #191613);
+
+  // Width/height set by JS from resolution picker
+
+  &.recording {
+    border-color: transparent;
+    border-radius: 0;
+    &::after { display: none; }
+  }
+}
+
+#studio-canvas::after {
+  content: attr(data-aspect) " · " attr(data-size);
+  position: absolute;
+  top: -24px;
+  right: 0;
+  font-family: var(--bs-font-monospace, monospace);
+  font-size: 0.62rem;
+  letter-spacing: 0.08em;
+  color: rgba(255, 255, 255, 0.35);
+  text-transform: uppercase;
+}
+
+// ============================================
+// Generic clip primitives — used by framework
+// builder helpers (flowClip, cardClip, chatClip)
+// ============================================
+.s-hidden { opacity: 0; }
+.s-step-bg { background: rgba(0, 0, 0, 0.04); }
+.s-bar-fill { height: 100%; width: 0; }

package/dist/assets/js/core/auth.js

@@ -105,6 +105,9 @@ export default function () {
           }
         }
 
+        // Prompt for push notification subscription (fire-and-forget)
+        webManager.notifications().subscribe().catch(() => {});
+
         // Check if page requires user to be unauthenticated (e.g., signin page)
         if (policy === 'unauthenticated') {
           // Check for authReturnUrl first (takes precedence)
@@ -316,7 +319,7 @@ async function sendUserSignupMetadata(account) {
     /* @dev-only:start */
     webManager.utilities().showNotification(
       `[DEV] Failed to send signup metadata. Will retry on next page load (flags.signupProcessed is still false).`,
-      { type: 'warning', timeout: 0 }
+      { type: 'warning', timeout: 1000 }
     );
     /* @dev-only:end */
   }

package/dist/assets/js/pages/admin/studio/index.js

@@ -0,0 +1,535 @@
+/**
+ * Animation Studio — UJM default admin page
+ *
+ * Uses FormManager for sidebar controls. Canvas content is designed at a
+ * base resolution (960×540) and CSS-scaled to match the selected resolution,
+ * so clips look identical at any size.
+ */
+
+import webManager from 'web-manager';
+import { FormManager } from '__main_assets__/js/libs/form-manager.js';
+
+const BASE_W = 960;
+const BASE_H = 540;
+
+let currentClip = null;
+let loopTimer = null;
+let paused = false;
+let speed = 1;
+let clips = {};
+let recording = false;
+let formManager = null;
+
+export default () => {
+  return new Promise(async function (resolve) {
+    await webManager.dom().ready();
+
+    webManager.auth().listen({ once: true }, (auth) => {
+      if (!auth.user) {
+        return;
+      }
+
+      clips = window.STUDIO_CLIPS || {};
+
+      const clipIds = Object.keys(clips);
+      if (clipIds.length === 0) {
+        const $studio = document.getElementById('studio');
+        if ($studio) {
+          $studio.hidden = false;
+          $studio.innerHTML = '<div style="display:flex;align-items:center;justify-content:center;min-height:100vh;color:rgba(255,255,255,0.5);font-size:1.1rem">No clips registered. Set <code style="color:#fff;margin:0 6px">window.STUDIO_CLIPS</code> in your project JS.</div>';
+        }
+        return;
+      }
+
+      buildNav(clipIds);
+      setupForm();
+      setupRecord();
+
+      document.getElementById('studio').hidden = false;
+      updateCanvasSize();
+
+      currentClip = clipIds[0];
+      playClip(currentClip);
+    });
+
+    return resolve();
+  });
+};
+
+// ============================================
+// Navigation — built from registered clips
+// ============================================
+function buildNav(clipIds) {
+  const $container = document.getElementById('studio-clips');
+  if (!$container) {
+    return;
+  }
+
+  clipIds.forEach((id, i) => {
+    const $btn = document.createElement('button');
+    $btn.className = 'studio-clip-btn' + (i === 0 ? ' active' : '');
+    $btn.dataset.clip = id;
+    $btn.textContent = clips[id].label || id;
+    $container.appendChild($btn);
+
+    $btn.addEventListener('click', () => {
+      if (recording) {
+        return;
+      }
+      document.querySelector('.studio-clip-btn.active')?.classList.remove('active');
+      $btn.classList.add('active');
+      currentClip = id;
+      if (!paused) {
+        playClip(currentClip);
+      }
+    });
+  });
+}
+
+// ============================================
+// FormManager for sidebar controls
+// ============================================
+function setupForm() {
+  formManager = new FormManager('#studio-controls-form', {
+    autoReady: true,
+    allowResubmit: true,
+  });
+
+  // Aspect ratio buttons
+  document.querySelectorAll('.studio-aspect-btn').forEach($btn => {
+    $btn.addEventListener('click', () => {
+      if (recording) {
+        return;
+      }
+      document.querySelector('.studio-aspect-btn.active')?.classList.remove('active');
+      $btn.classList.add('active');
+
+      const $canvas = document.getElementById('studio-canvas');
+      if ($canvas) {
+        $canvas.setAttribute('data-aspect', $btn.dataset.aspect);
+      }
+
+      updateCanvasSize();
+      playClip(currentClip);
+    });
+  });
+
+  // Pause slider
+  const $pause = document.getElementById('studio-pause');
+  const $pauseVal = document.getElementById('studio-pause-val');
+  $pause?.addEventListener('input', () => {
+    $pauseVal.textContent = $pause.value;
+  });
+
+  // Speed select
+  const $speed = document.getElementById('studio-speed');
+  $speed?.addEventListener('change', () => {
+    speed = parseFloat($speed.value);
+  });
+
+  // Resolution select
+  const $res = document.getElementById('studio-resolution');
+  $res?.addEventListener('change', () => {
+    updateCanvasSize();
+    playClip(currentClip);
+  });
+
+  // Play/pause toggle
+  const $toggle = document.getElementById('studio-toggle');
+  $toggle?.addEventListener('click', () => {
+    if (recording) {
+      return;
+    }
+    paused = !paused;
+    $toggle.textContent = paused ? '▶ Play' : '⏸ Pause';
+    if (!paused) {
+      playClip(currentClip);
+    }
+  });
+}
+
+// ============================================
+// Canvas sizing + content scaling
+// ============================================
+function getResolution() {
+  const $res = document.getElementById('studio-resolution');
+  const val = $res?.value || '1920x1080';
+  const [w, h] = val.split('x').map(Number);
+  return { w, h };
+}
+
+function updateCanvasSize() {
+  const $canvas = document.getElementById('studio-canvas');
+  if (!$canvas) {
+    return;
+  }
+
+  const aspect = $canvas.getAttribute('data-aspect');
+  const { w, h } = getResolution();
+
+  let cw, ch;
+  if (aspect === '9:16') {
+    ch = h;
+    cw = Math.round(h * 9 / 16);
+  } else {
+    cw = w;
+    ch = h;
+  }
+
+  // Canvas is always rendered at base size, then CSS-scaled
+  const baseW = aspect === '9:16' ? Math.round(BASE_H * 9 / 16) : BASE_W;
+  const baseH = BASE_H;
+  const scaleX = cw / baseW;
+  const scaleY = ch / baseH;
+
+  $canvas.style.width = baseW + 'px';
+  $canvas.style.height = baseH + 'px';
+  $canvas.style.transform = `scale(${scaleX}, ${scaleY})`;
+  $canvas.style.transformOrigin = 'center center';
+  $canvas.setAttribute('data-size', `${cw} × ${ch}`);
+}
+
+// ============================================
+// Clip runner — delay BEFORE animation
+// ============================================
+function playClip(clipId) {
+  clearTimeout(loopTimer);
+  const $canvas = document.getElementById('studio-canvas');
+  if (!$canvas) {
+    return;
+  }
+
+  $canvas.innerHTML = '';
+
+  const clip = clips[clipId];
+  if (!clip) {
+    return;
+  }
+
+  const pauseMs = parseInt(document.getElementById('studio-pause')?.value || 1500);
+  const totalDuration = clip.duration / speed;
+
+  loopTimer = setTimeout(() => {
+    clip.build($canvas, getHelpers($canvas));
+
+    loopTimer = setTimeout(() => {
+      if (!paused && currentClip === clipId && !recording) {
+        playClip(clipId);
+      }
+    }, totalDuration);
+  }, pauseMs);
+}
+
+// ============================================
+// Recording
+// ============================================
+function setupRecord() {
+  const $btn = document.getElementById('studio-record');
+  if (!$btn) {
+    return;
+  }
+
+  $btn.addEventListener('click', () => {
+    if (recording) {
+      return;
+    }
+    recordClip();
+  });
+}
+
+async function recordClip() {
+  const $canvas = document.getElementById('studio-canvas');
+  const $btn = document.getElementById('studio-record');
+  const $fieldset = document.getElementById('studio-fieldset');
+  const clip = clips[currentClip];
+  if (!$canvas || !clip) {
+    return;
+  }
+
+  console.log(`[Studio] Recording clip: ${currentClip}`);
+
+  recording = true;
+  paused = true;
+  clearTimeout(loopTimer);
+
+  // Disable all controls via fieldset
+  if ($fieldset) {
+    $fieldset.disabled = true;
+  }
+  // Keep record button enabled to show state
+  $btn.disabled = false;
+  $btn.classList.add('recording');
+  $btn.textContent = '⏺ Recording...';
+
+  let stream;
+  try {
+    console.log('[Studio] Requesting screen capture...');
+    stream = await navigator.mediaDevices.getDisplayMedia({
+      video: { displaySurface: 'browser', frameRate: { ideal: 60 } },
+      preferCurrentTab: true,
+    });
+    console.log('[Studio] Screen capture granted');
+  } catch (err) {
+    console.warn('[Studio] Screen capture denied:', err.message);
+    resetRecordState($btn, $fieldset);
+    return;
+  }
+
+  // Attempt Region Capture (CropTarget) to scope to canvas element
+  try {
+    if (typeof CropTarget !== 'undefined' && stream.getVideoTracks()[0].cropTo) {
+      const cropTarget = await CropTarget.fromElement($canvas);
+      await stream.getVideoTracks()[0].cropTo(cropTarget);
+      console.log('[Studio] CropTarget applied — recording canvas only');
+    } else {
+      console.log('[Studio] CropTarget not available — recording full tab');
+    }
+  } catch (err) {
+    console.log('[Studio] CropTarget failed:', err.message, '— recording full tab');
+  }
+
+  const mimeType = getSupportedMimeType();
+  console.log(`[Studio] Using mime type: ${mimeType}`);
+
+  const recorder = new MediaRecorder(stream, {
+    mimeType,
+    videoBitsPerSecond: 16_000_000,
+  });
+
+  const chunks = [];
+  recorder.ondataavailable = (e) => {
+    if (e.data.size > 0) {
+      chunks.push(e.data);
+      console.log(`[Studio] Chunk received: ${(e.data.size / 1024).toFixed(1)}KB (${chunks.length} total)`);
+    }
+  };
+
+  recorder.onstop = () => {
+    stream.getTracks().forEach(t => t.stop());
+
+    const ext = recorder.mimeType.includes('mp4') ? 'mp4' : 'webm';
+    const aspect = $canvas.getAttribute('data-aspect') || '16-9';
+    const { w, h } = getResolution();
+    const blob = new Blob(chunks, { type: recorder.mimeType });
+    const filename = `${currentClip}-${aspect.replace(':', 'x')}-${w}x${h}.${ext}`;
+
+    console.log(`[Studio] Recording complete — ${chunks.length} chunks, ${(blob.size / 1024).toFixed(1)}KB, mime: ${recorder.mimeType}`);
+    console.log(`[Studio] Downloading: ${filename}`);
+
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+
+    resetRecordState($btn, $fieldset);
+    playClip(currentClip);
+  };
+
+  recorder.onerror = (e) => {
+    console.error('[Studio] Recorder error:', e.error);
+  };
+
+  stream.getVideoTracks()[0].addEventListener('ended', () => {
+    console.log('[Studio] Screen sharing ended by user');
+    if (recorder.state !== 'inactive') {
+      recorder.stop();
+    }
+  });
+
+  // Clear canvas, enter recording mode, settle
+  $canvas.innerHTML = '';
+  $canvas.classList.add('recording');
+  await sleep(1000);
+  console.log('[Studio] Canvas settled, starting recorder...');
+
+  await new Promise((resolve) => {
+    recorder.onstart = () => {
+      console.log('[Studio] Recorder started');
+      resolve();
+    };
+    recorder.start(100);
+  });
+
+  const pauseMs = parseInt(document.getElementById('studio-pause')?.value || 1500);
+  const totalDuration = clip.duration / speed;
+
+  console.log(`[Studio] Pre-delay: ${pauseMs}ms, clip duration: ${totalDuration}ms (speed: ${speed}x)`);
+
+  await sleep(pauseMs);
+
+  console.log('[Studio] Building clip animation...');
+  clip.build($canvas, getHelpers($canvas));
+
+  await sleep(totalDuration);
+
+  console.log('[Studio] Clip finished, stopping recorder...');
+  if (recorder.state !== 'inactive') {
+    recorder.stop();
+  }
+}
+
+function resetRecordState($btn, $fieldset) {
+  recording = false;
+  paused = false;
+  $btn.classList.remove('recording');
+  $btn.textContent = '⏺ Record';
+
+  if ($fieldset) {
+    $fieldset.disabled = false;
+  }
+
+  const $canvas = document.getElementById('studio-canvas');
+  if ($canvas) {
+    $canvas.classList.remove('recording');
+  }
+
+  const $toggle = document.getElementById('studio-toggle');
+  if ($toggle) {
+    $toggle.textContent = '⏸ Pause';
+  }
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+function getSupportedMimeType() {
+  const types = [
+    'video/webm;codecs=vp9',
+    'video/webm;codecs=vp8',
+    'video/webm',
+  ];
+
+  for (const type of types) {
+    if (MediaRecorder.isTypeSupported(type)) {
+      return type;
+    }
+  }
+
+  return 'video/webm';
+}
+
+// ============================================
+// Helpers — passed to clip build() functions
+// ============================================
+function getHelpers($canvas) {
+  return { animate, el, flowClip: (opts) => buildFlowClip($canvas, opts), cardClip: (opts) => buildCardClip($canvas, opts), chatClip: (opts) => buildChatClip($canvas, opts) };
+}
+
+function animate(element, keyframes, options = {}) {
+  const delay = (options.delay || 0) / speed;
+  const duration = (options.duration || 500) / speed;
+  const fill = options.fill || 'forwards';
+  const easing = options.easing || 'cubic-bezier(0.34, 1.56, 0.64, 1)';
+
+  return element.animate(keyframes, { delay, duration, fill, easing });
+}
+
+function el(tag, classes, html) {
+  const node = document.createElement(tag);
+  if (classes) {
+    node.className = classes;
+  }
+  if (html) {
+    node.innerHTML = html;
+  }
+  return node;
+}
+
+// ============================================
+// Builder helpers — reusable clip patterns
+// ============================================
+function buildFlowClip($c, { title, nodes }) {
+  const isV = $c.getAttribute('data-aspect') === '9:16';
+
+  const titleEl = el('div', 's-hero-title text-center px-3');
+  titleEl.innerHTML = `<span class="s-display d-block fw-bold">${title}</span>`;
+  $c.appendChild(titleEl);
+
+  const arrow = isV ? '↓' : '→';
+  const flow = el('div', `s-hidden d-flex align-items-center justify-content-center gap-3 px-4 ${isV ? 'flex-column' : ''}`);
+
+  nodes.forEach((n, i) => {
+    if (i > 0) {
+      flow.appendChild(el('span', 's-hidden s-accent fw-bold fs-4 flex-shrink-0', arrow));
+    }
+    const node = el('div', 's-hidden card rounded-4 p-3 text-center');
+    node.style.width = '140px';
+    node.innerHTML = `
+      <span class="d-block fs-4 mb-2">${n.icon}</span>
+      <span class="d-block fw-bold small">${n.label}</span>
+      <small class="d-block font-monospace text-body-secondary" style="font-size:0.65rem">${n.stat}</small>
+    `;
+    flow.appendChild(node);
+  });
+
+  $c.appendChild(flow);
+
+  animate(titleEl, [
+    { opacity: 0, transform: 'translateY(-20px)' },
+    { opacity: 1, transform: 'translateY(0)' },
+  ], { duration: 600 });
+
+  animate(flow, [{ opacity: 0 }, { opacity: 1 }], { delay: 300, duration: 300, easing: 'ease' });
+
+  flow.querySelectorAll('.card').forEach((node, i) => {
+    animate(node, [
+      { opacity: 0, transform: 'scale(0.5) translateY(20px)' },
+      { opacity: 1, transform: 'scale(1) translateY(0)' },
+    ], { delay: 500 + i * 250, duration: 500 });
+  });
+
+  flow.querySelectorAll('.s-accent').forEach((a, i) => {
+    animate(a, [{ opacity: 0 }, { opacity: 1 }], { delay: 650 + i * 250, duration: 300, easing: 'ease' });
+  });
+}
+
+function buildCardClip($c, { badge, title, contentFn }) {
+  const card = el('div', 's-hidden card rounded-4 p-4');
+  card.style.maxWidth = '500px';
+  card.style.width = '90%';
+  card.innerHTML = `
+    <div class="d-flex align-items-center gap-2 mb-3">${badge}</div>
+    <div class="s-display fs-5 fw-bold mb-3">${title}</div>
+    <div class="d-flex flex-column gap-2" data-content></div>
+  `;
+  $c.appendChild(card);
+
+  animate(card, [
+    { opacity: 0, transform: 'scale(0.8) translateY(30px)' },
+    { opacity: 1, transform: 'scale(1) translateY(0)' },
+  ], { duration: 600 });
+
+  contentFn(card.querySelector('[data-content]'), { animate, el });
+}
+
+function buildChatClip($c, { header, messages }) {
+  const headerEl = el('div', 's-hidden text-center px-3');
+  headerEl.innerHTML = header;
+  $c.appendChild(headerEl);
+
+  animate(headerEl, [
+    { opacity: 0, transform: 'translateY(-20px)' },
+    { opacity: 1, transform: 'translateY(0)' },
+  ], { duration: 500 });
+
+  const chat = el('div', 'd-flex flex-column gap-2 px-4 w-100');
+  chat.style.maxWidth = '480px';
+
+  messages.forEach((m, i) => {
+    const isAI = m.type === 'ai';
+    const bubble = el('div', `s-hidden rounded-4 px-3 py-2 small lh-sm ${isAI ? 's-bubble-ai align-self-end' : 's-bubble-them align-self-start'}`);
+    bubble.style.maxWidth = '85%';
+    bubble.innerHTML = m.text + (m.label ? `<span class="s-chat-label d-block text-uppercase mt-1">${m.label}</span>` : '');
+    chat.appendChild(bubble);
+
+    animate(bubble, [
+      { opacity: 0, transform: 'translateY(16px) scale(0.92)' },
+      { opacity: 1, transform: 'translateY(0) scale(1)' },
+    ], { delay: 800 + i * 800, duration: 500 });
+  });
+
+  $c.appendChild(chat);
+}

package/dist/defaults/CLAUDE.md

@@ -38,6 +38,26 @@ npx mgr install live # restore the published ultimate-jekyll-manager from npm
 
 > Editing the UJM framework source while working here? Run `npx mgr install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/ultimate-jekyll-manager`). Run `npx mgr install live` to switch back.
 
+## 🚨 BOOTSTRAP-FIRST — NEVER reinvent the wheel
+
+**UJM is built on Bootstrap 5.** Every page MUST use Bootstrap classes for layout, spacing, typography, buttons, cards, grid, flex, and all standard components. Custom CSS exists ONLY to override how Bootstrap classes LOOK (via theme SCSS), NOT to replace them with parallel classes.
+
+- **DO:** Use `.btn .btn-primary`, `.container`, `.row`, `.col-*`, `.d-flex`, `.gap-*`, `.py-5`, `.text-center`, `.card`, `.lead`, `.shadow`, `.rounded-*`, etc.
+- **DO NOT:** Create custom `.my-btn`, `.my-wrap`, `.my-section` classes when Bootstrap already has equivalents. Don't write `padding`, `display: flex`, `gap`, `margin`, `text-align`, `font-weight` in custom CSS when a Bootstrap utility does the same thing.
+- **Theme SCSS overrides appearance:** `.btn { border-radius: 50px; box-shadow: ... }` changes ALL buttons site-wide. You don't need `.lm-btn` — just restyle `.btn`.
+- **Custom CSS is for genuinely novel components only:** animated hero illustrations, grain overlays, marquee strips — things with no Bootstrap equivalent.
+
+See `node_modules/ultimate-jekyll-manager/docs/themes.md` for the full "Bootstrap-first" convention.
+
+## 🚨 Development workflow — MUST follow
+
+- **🚫 NEVER run `npm start`, `npm run build`, or `npm test`** unless the user explicitly asks. Assume the user is already running the dev server. Running these commands kills the user's process and wastes time.
+- **✅ ALWAYS check `logs/dev.log`** after editing source files (SCSS, JS, HTML, config) to confirm the build succeeded. The dev server's gulp watcher recompiles on file change — check the log for errors.
+  - Success: `Reloading Browsers...`
+  - Failure: `'sass' errored`, `'webpack' errored`, `'build-error'`, `'jekyll' errored`
+- If editing multiple files in a batch, check the log once after the last edit. Wait a few seconds for the watcher to recompile before reading the log.
+- **If the log shows an error, fix it immediately.** A change that breaks the build is not a completed change.
+
 ## Where things live
 
 - `src/_config.yml` — Jekyll config: brand, theme, meta, web_manager (Firebase). `Manager.getConfig('project')` reads this. **`brand.id` + `theme.id` are required.**
@@ -54,6 +74,16 @@ npx mgr install live # restore the published ultimate-jekyll-manager from npm
 - `dist/` — intermediate compile output (webpack bundles, sass, processed images) before Jekyll merges them into `_site/`.
 - `test/**/*.js` — your project test suites (framework auto-runs them alongside its own).
 
+## Animation Studio
+
+UJM ships a default Animation Studio admin page at `/admin/studio` for creating screen-recording-ready product demo clips. The framework provides all boilerplate (sidebar, controls, canvas, clip runner engine). Consumer projects only supply clip definitions and clip-specific CSS:
+
+- **Clips:** Set `window.STUDIO_CLIPS` in `src/assets/js/pages/admin/studio/index.js` — each clip has a `label`, `duration`, and `build($canvas, helpers)` function. Helpers include `animate`, `el`, and reusable builders: `flowClip`, `cardClip`, `chatClip`.
+- **Clip CSS:** Put animation primitives in `src/assets/css/pages/admin/studio/index.scss` (must include `@use 'studio'` to pull in boilerplate)
+- **No page file needed** — the framework default provides the page
+
+See `node_modules/ultimate-jekyll-manager/docs/animation-studio.md` for the full reference (clip contract, helpers, aspect ratios, playback controls).
+
 ## Per-context imports
 
 ```js

package/dist/defaults/dist/_includes/admin/sections/sidebar.json

@@ -44,6 +44,15 @@
       href: '/admin/calendar',
       icon: 'calendar-days'
     },
+    {
+      header: true,
+      label: 'Content'
+    },
+    {
+      label: 'Animation Studio',
+      href: '/admin/studio',
+      icon: 'clapperboard',
+    },
     {
       header: true,
       label: 'External tools'

package/dist/defaults/dist/_layouts/blueprint/admin/studio/index.html

@@ -0,0 +1,92 @@
+---
+### ALL PAGES ###
+layout: themes/[ site.theme.id ]/frontend/core/base
+
+### THEME CONFIG ###
+theme:
+  nav:
+    enabled: false
+  footer:
+    enabled: false
+
+### REGULAR PAGES ###
+meta:
+  title: "Animation Studio"
+  index: false
+sitemap:
+  include: false
+
+### WEB MANAGER CONFIG ###
+web_manager:
+  auth:
+    config:
+      policy: "authenticated"
+  cookieConsent:
+    enabled: false
+  chatsy:
+    enabled: false
+  exitPopup:
+    enabled: false
+---
+
+<div id="studio" hidden>
+  <!-- Clip selector sidebar -->
+  <nav id="studio-nav">
+    <div class="studio-brand">{{ site.brand.name }} Studio</div>
+    <div class="studio-clips" id="studio-clips">
+      <!-- Populated by JS from registered clips -->
+    </div>
+    <form id="studio-controls-form" class="studio-controls">
+      <fieldset id="studio-fieldset">
+        <!-- Aspect ratio toggle -->
+        <label class="studio-label">
+          Aspect Ratio
+          <div class="d-flex gap-1">
+            <button type="button" class="studio-aspect-btn active" data-aspect="16:9">16:9</button>
+            <button type="button" class="studio-aspect-btn" data-aspect="9:16">9:16</button>
+          </div>
+        </label>
+        <label class="studio-label">
+          Resolution
+          <select name="resolution" id="studio-resolution">
+            <option value="960x540">540p (960×540)</option>
+            <option value="1280x720">720p (1280×720)</option>
+            <option value="1920x1080" selected>1080p (1920×1080)</option>
+            <option value="3840x2160">4K (3840×2160)</option>
+          </select>
+        </label>
+        <label class="studio-label">
+          Pause (ms)
+          <input type="range" name="pause" id="studio-pause" min="500" max="4000" value="1500" step="100">
+          <span id="studio-pause-val">1500</span>
+        </label>
+        <label class="studio-label">
+          Speed
+          <select name="speed" id="studio-speed">
+            <option value="0.5">0.5×</option>
+            <option value="1" selected>1×</option>
+            <option value="1.5">1.5×</option>
+            <option value="2">2×</option>
+          </select>
+        </label>
+        <label class="studio-label">
+          Appearance
+          <div class="d-flex gap-1">
+            <button type="button" class="studio-toggle-btn" data-appearance-set="light">Light</button>
+            <button type="button" class="studio-toggle-btn" data-appearance-set="dark">Dark</button>
+            <button type="button" class="studio-toggle-btn" data-appearance-set="system">System</button>
+          </div>
+        </label>
+        <button type="button" id="studio-toggle" class="studio-play-btn">⏸ Pause</button>
+        <button type="button" id="studio-record" class="studio-record-btn">⏺ Record</button>
+      </fieldset>
+    </form>
+  </nav>
+
+  <!-- Animation stage -->
+  <main id="studio-stage">
+    <div id="studio-canvas" data-aspect="16:9">
+      <!-- Animation content injected by JS -->
+    </div>
+  </main>
+</div>

package/dist/defaults/dist/pages/admin/studio/index.html

@@ -0,0 +1,7 @@
+---
+### ALL PAGES ###
+layout: blueprint/admin/studio/index
+permalink: /admin/studio
+
+### REGULAR PAGES ###
+---

package/docs/animation-studio.md

@@ -0,0 +1,166 @@
+# Animation Studio
+
+Admin page at `/admin/studio` for creating screen-recording-ready product demo animation clips. Ships with UJM as a default admin page — consumer projects supply only clip definitions and clip-specific CSS.
+
+## Architecture
+
+The Studio page is a standalone full-viewport dark canvas with a sidebar for clip selection and playback controls. It bypasses the standard admin sidebar/topbar/header chrome (`theme.sidebar/topbar/header: enabled: false` in the blueprint).
+
+**Framework provides (boilerplate):**
+- Page file (`dist/pages/admin/studio/index.html`) + blueprint layout
+- Sidebar with auto-generated clip buttons from registered clips
+- Playback controls (pause duration slider, speed selector, play/pause toggle)
+- Aspect ratio toggle (16:9 landscape / 9:16 vertical for reels/stories)
+- Recording-ready canvas with dashed border and aspect ratio label
+- Clip runner loop with speed-scaled timing
+- `animate()` helper — wraps Web Animations API with auto-speed scaling
+- `el()` helper — DOM element factory (`el(tag, classes, innerHTML)`)
+- Admin role gate (redirects non-admins to `/dashboard`)
+- All boilerplate CSS (sidebar, controls, canvas frame — theme-agnostic)
+
+**Consumer provides (project-specific):**
+- Clip definitions via `window.STUDIO_CLIPS` (set in the project JS layer)
+- Clip-specific CSS (animation primitives, keyframes, component styles)
+
+## Clip registration
+
+Consumer projects register clips by setting `window.STUDIO_CLIPS` in their page-specific JS at `src/assets/js/pages/admin/studio/index.js`. The framework's main-layer JS reads this object after auth resolves (by which time the project-layer module has executed).
+
+```js
+// src/assets/js/pages/admin/studio/index.js (consumer project)
+
+window.STUDIO_CLIPS = {
+  'hero': {
+    label: 'Hero Intro',         // sidebar button text
+    duration: 3000,              // total animation duration in ms (before speed scaling)
+    build($canvas, { animate, el }) {
+      // Create DOM elements and animate them
+      const title = el('div', 'my-title-class');
+      title.innerHTML = '<h1>Hello World</h1>';
+      $canvas.appendChild(title);
+
+      animate(title, [
+        { opacity: 0, transform: 'translateY(30px)' },
+        { opacity: 1, transform: 'translateY(0)' },
+      ], { duration: 800 });
+    },
+  },
+
+  'feature-demo': {
+    label: 'Feature Demo',
+    duration: 5000,
+    build($canvas, { animate, el }) {
+      // ...
+    },
+  },
+};
+
+export default () => {};
+```
+
+### Clip contract
+
+Each clip in `window.STUDIO_CLIPS` is keyed by a unique ID string and must have:
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | `string` | Button text in the sidebar. Falls back to the clip ID if omitted. |
+| `duration` | `number` | Total animation duration in milliseconds (pre-speed scaling). Used to calculate when the loop restarts. |
+| `build` | `function($canvas, helpers)` | Called each loop iteration. Receives the cleared canvas element and helper functions. Must build DOM and start animations. |
+
+### `build()` helpers
+
+The `build` function receives helpers as its second argument:
+
+**Core helpers:**
+
+**`animate(element, keyframes, options)`** — Wraps `Element.animate()` (Web Animations API). Auto-scales `delay` and `duration` by the current speed setting. Returns the `Animation` object.
+
+Options:
+- `delay` (ms, default `0`) — scaled by speed
+- `duration` (ms, default `500`) — scaled by speed
+- `fill` (default `'forwards'`)
+- `easing` (default `'cubic-bezier(0.34, 1.56, 0.64, 1)'`)
+
+**`el(tag, classes, innerHTML)`** — Creates a DOM element. All three arguments are optional strings.
+
+**Builder helpers** (reusable clip patterns — zero boilerplate in consumer):
+
+**`flowClip({ title, nodes })`** — Animated title + horizontal/vertical flow of cards with arrows between them. Automatically switches to vertical layout in 9:16. Each node has `{ icon, label, stat }`.
+
+**`cardClip({ badge, title, contentFn })`** — Animated neobrutalist card (uses Bootstrap `.card` with theme shadow). `badge` is badge HTML, `title` is the heading, `contentFn(container, { animate, el })` is called to populate the card body.
+
+**`chatClip({ header, messages })`** — Header + animated chat bubble sequence. Each message has `{ type: 'them'|'ai', text, label? }`.
+
+### Speed scaling
+
+The `animate()` helper divides `delay` and `duration` by the current speed multiplier (0.5×, 1×, 1.5×, 2×). At 2× speed, a 1000ms animation completes in 500ms. The clip's `duration` is also scaled when calculating the loop restart time.
+
+If a clip uses raw `Element.animate()` directly (bypassing the helper), it must manually divide timings by the speed — but this is not recommended.
+
+## Clip-specific CSS
+
+Animation primitives go in the consumer's page-specific CSS at `src/assets/css/pages/admin/studio/index.scss`. These are project-specific styles for the animation content rendered inside the canvas — things like card shapes, flow diagrams, chat bubbles, custom keyframes.
+
+**Important:** The consumer's page CSS MUST import the framework's boilerplate partial with `@use 'studio'`. This is required because page-specific CSS compiles independently per layer, and the consumer's file overwrites the framework's. The `@use 'studio'` directive pulls in the boilerplate (sidebar, controls, canvas) from `dist/assets/css/_studio.scss` via the SASS loadPaths. Consumer CSS should NOT redefine these boilerplate styles.
+
+```scss
+// src/assets/css/pages/admin/studio/index.scss (consumer project)
+@use 'ultimate-jekyll-manager' as *;
+@use 'studio';
+
+// Animation card
+.my-card {
+  background: var(--my-theme-color);
+  border-radius: 18px;
+  padding: 24px;
+  opacity: 0; // animated in by JS
+}
+
+// Custom keyframe
+@keyframes my-slide-in {
+  0% { opacity: 0; transform: translateX(-40px); }
+  100% { opacity: 1; transform: translateX(0); }
+}
+```
+
+## Canvas dimensions
+
+The canvas has two aspect ratio modes, toggled via the sidebar buttons:
+
+| Aspect | Width | Height | Use case |
+|---|---|---|---|
+| 16:9 | 960px | 540px | Landscape video, website demos |
+| 9:16 | 405px | 720px | Vertical reels, stories, TikTok |
+
+The canvas transitions smoothly between sizes. The currently selected aspect ratio is shown as a label above the top-right corner.
+
+## Playback controls
+
+| Control | Default | Range | Description |
+|---|---|---|---|
+| Pause (ms) | 1500 | 500–4000 | Delay between clip loop iterations |
+| Speed | 1× | 0.5×–2× | Playback speed multiplier |
+| Play/Pause | Playing | — | Toggle clip loop |
+
+## Admin gating
+
+The Studio page requires `admin` role authentication (inherited from the `classy/admin/core/minimal` layout). Non-admin users are redirected to `/dashboard`. The `#studio` container starts `hidden` and is revealed after auth confirms admin access.
+
+## No-clips fallback
+
+If `window.STUDIO_CLIPS` is not set or is empty (no clips registered), the Studio page shows a message: "No clips registered. Set `window.STUDIO_CLIPS` in your project JS." This is the expected state for consumer projects that haven't defined clips yet.
+
+## File locations
+
+**Framework (UJM):**
+- `src/defaults/dist/pages/admin/studio/index.html` — page file
+- `src/defaults/dist/_layouts/blueprint/admin/studio/index.html` — blueprint layout (HTML + sidebar + controls)
+- `src/assets/js/pages/admin/studio/index.js` — boilerplate JS (engine, helpers)
+- `src/assets/css/_studio.scss` — boilerplate CSS partial (sidebar, controls, canvas). Consumers import via `@use 'studio'`.
+- `src/defaults/dist/_includes/admin/sections/sidebar.json` — includes Studio link
+
+**Consumer project:**
+- `src/assets/js/pages/admin/studio/index.js` — clip definitions (`window.STUDIO_CLIPS`)
+- `src/assets/css/pages/admin/studio/index.scss` — clip-specific animation CSS (must include `@use 'studio'` to pull in boilerplate)
+- No page file needed — the framework default provides `/admin/studio`

package/docs/themes.md

@@ -345,6 +345,56 @@ their own (frozen) text color. Nav/dropdown/footer links already win on specific
 
 ---
 
+## 🚨 BOOTSTRAP-FIRST — NEVER reinvent the wheel
+
+**This is the #1 theme authoring mistake.** A theme's job is to RESTYLE Bootstrap — not to build a parallel design system alongside it.
+
+### The rule
+
+Every HTML element must use **Bootstrap classes first**. Custom CSS exists ONLY to override how those Bootstrap classes look (colors, shadows, borders, radii, typography) via the theme's SCSS. You should NEVER:
+
+- Invent custom layout classes when Bootstrap grid/flex utilities exist (`.row`, `.col-*`, `.d-flex`, `.gap-*`, `.justify-content-*`, `.align-items-*`, `.text-center`, `.mx-auto`, etc.)
+- Create custom button classes (`.my-btn`, `.lm-btn`) when `.btn .btn-primary`, `.btn .btn-outline-dark`, etc. already exist — restyle `.btn` in theme SCSS instead
+- Create custom spacing/sizing classes when Bootstrap has `p-*`, `m-*`, `w-*`, `rounded-*`, `shadow-*`
+- Create custom text utilities when Bootstrap has `.text-muted`, `.lead`, `.display-*`, `.fw-*`, `.fs-*`
+- Create custom card/container classes when `.card`, `.card-body`, `.container`, `.lh-*` exist
+- Write `position`, `display`, `flex`, `gap`, `padding`, `margin`, `border-radius`, `text-align`, `font-weight`, `font-size` in custom CSS when a Bootstrap utility class does the same thing
+
+### What theme CSS IS for
+
+- Overriding Bootstrap component appearance: `.btn { border-radius: 50px; box-shadow: ... }` — changes how ALL buttons look
+- Setting design tokens: `$primary`, `$border-radius`, `$font-family-sans-serif` — passed to Bootstrap's `@forward`
+- CSS custom properties for the theme palette: `--lm-accent`, `--lm-ink`, etc.
+- Dark mode overrides via `[data-bs-theme="dark"]` variable remapping
+- Truly novel components with no Bootstrap equivalent (grain overlays, animated hero cards, marquee strips)
+- Mixins/utilities that compose Bootstrap patterns, not replace them
+
+### How to check yourself
+
+Before writing ANY custom CSS class, ask: "Does Bootstrap already have a class for this?" If yes, use it. If the Bootstrap class doesn't look right, override its appearance in theme SCSS — don't create a parallel class. The HTML should be 90%+ Bootstrap classes with custom classes only for genuinely novel UI patterns.
+
+### Anti-pattern example
+
+```html
+<!-- BAD: parallel design system -->
+<div class="lm-wrap">
+  <div class="lm-section">
+    <a class="lm-btn lm-btn-primary">Click</a>
+  </div>
+</div>
+
+<!-- GOOD: Bootstrap classes, theme restyled -->
+<div class="container">
+  <section class="py-5">
+    <a class="btn btn-primary">Click</a>
+  </section>
+</div>
+```
+
+The GOOD version uses zero custom CSS for layout/buttons — the theme's `_buttons.scss` restyled `.btn` and `.btn-primary` to look however it wants. The page `main.scss` only adds styles for genuinely novel components.
+
+---
+
 ## Authoring conventions (both paths)
 
 1. **Every token is `!default`** so consumers can override without forking.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate-jekyll-manager",
-  "version": "1.6.8",
+  "version": "1.7.0",
   "description": "Ultimate Jekyll dependency manager",
   "main": "dist/index.js",
   "exports": {