@deckio/deck-engine 1.7.8 → 1.8.1

package/components/Slide.jsx

@@ -1,15 +1,43 @@
+import { useRef, useEffect, useState } from 'react'
 import { useSlides } from '../context/SlideContext'
 
+const DEV = typeof import.meta !== 'undefined' && import.meta.env?.DEV
+
 export default function Slide({ index, className = '', children }) {
   const { current } = useSlides()
+  const ref = useRef(null)
+  const [overflow, setOverflow] = useState(false)
 
   let stateClass = ''
   if (index === current) stateClass = 'active'
   else if (index < current) stateClass = 'exit-left'
 
+  useEffect(() => {
+    if (!DEV || index !== current || !ref.current) return
+    const el = ref.current
+    const check = () => {
+      // Only check flow-positioned children; ignore absolute/fixed decorations (orbs, accent-bar)
+      const hasOverflow = Array.from(el.children).some(c => {
+        const pos = getComputedStyle(c).position
+        if (pos === 'absolute' || pos === 'fixed') return false
+        return c.offsetTop + c.offsetHeight > el.clientHeight
+      })
+      setOverflow(hasOverflow)
+    }
+    check()
+    const obs = new ResizeObserver(check)
+    obs.observe(el)
+    return () => obs.disconnect()
+  }, [index, current])
+
   return (
-    <div className={`slide ${stateClass} ${className}`} data-slide={index}>
+    <div ref={ref} className={`slide ${stateClass} ${className}`} data-slide={index}>
       {children}
+      {DEV && overflow && (
+        <div className="slide-overflow-warn">
+          ⚠ Content overflows slide — reduce content or use smaller elements
+        </div>
+      )}
     </div>
   )
 }

package/components/exportDeckPdf.js

@@ -79,6 +79,14 @@ export async function exportDeckPdf({
 
   if (document.fonts?.ready) await document.fonts.ready
 
+  // Force deck to canonical PDF dimensions so slides render at exactly
+  // PAGE_W × PAGE_H regardless of the current viewport size.
+  const origDeckCss = deck.style.cssText
+  deck.style.width = `${PAGE_W}px`
+  deck.style.height = `${PAGE_H}px`
+  await waitForPaint()
+  await wait(SETTLE_MS)
+
   try {
     for (let i = 0; i < totalSlides; i++) {
       onProgress?.({ current: i + 1, total: totalSlides })
@@ -95,8 +103,8 @@ export async function exportDeckPdf({
       let dataUrl
       try {
         dataUrl = await domToPng(active, {
-          width: active.clientWidth || PAGE_W,
-          height: active.clientHeight || PAGE_H,
+          width: PAGE_W,
+          height: PAGE_H,
           backgroundColor: bg,
           scale,
           style: {
@@ -114,6 +122,7 @@ export async function exportDeckPdf({
       pdf.addImage(dataUrl, 'PNG', 0, 0, PAGE_W, PAGE_H, undefined, 'FAST')
     }
   } finally {
+    deck.style.cssText = origDeckCss
     goTo(current)
     await waitForPaint()
   }

package/instructions/slide-css.instructions.md

@@ -10,12 +10,13 @@ applyTo: "**/slides/**/*.module.css"
 ```css
 .mySlide {
   background: var(--bg-deep);
-  flex-direction: column;
   padding: 0 0 44px 0;        /* reserve BottomBar height */
 }
 ```
 
-Add `justify-content: center` for cover or thank-you slides.
+The engine's `.slide` class already sets `flex-direction: column`, `justify-content: center`, and `overflow: hidden`. The engine also sets `flex-grow: 0` on all direct slide children, so **content stays at its natural height and is vertically centered by default** — building from the center outward. No scrolling is allowed.
+
+For dense slides that need top-alignment, override with `justify-content: flex-start`.
 
 ## Orb positioning recipe
 
@@ -40,12 +41,12 @@ Add `justify-content: center` for cover or thank-you slides.
   z-index: 10;
   display: flex;
   flex-direction: column;
-  justify-content: center;
-  flex: 1;
-  min-height: 0;
+  gap: 24px;
 }
 ```
 
+> **Do NOT add `flex: 1` or `flex-grow: 1`** to the body wrapper or any direct slide child — it stretches the wrapper to fill the slide and defeats the engine's built-in vertical centering. The engine sets `flex-grow: 0` on all direct slide children to ensure content builds from the center outward. Inner elements within the body wrapper should also avoid `flex: 1` unless they genuinely need to fill remaining space within the body.
+
 ## Theme variables (always use these, never hard-code colors)
 
 | Variable | Value |
@@ -89,3 +90,7 @@ Add `justify-content: center` for cover or thank-you slides.
 | Subtitle | `17px` | 300–400 | — |
 | Body | `13px–14px` | 400 | — |
 | Badge | `10px–11px` | 600–700 | `1.5px` |
+
+## Content density limits
+
+Slides must never overflow the viewport. The engine shows a **red dashed border warning** in dev mode when content exceeds the slide bounds. When content doesn't fit, split across multiple slides rather than cramming. A presentation with more slides is better than one with clipped content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deckio/deck-engine",
-  "version": "1.7.8",
+  "version": "1.8.1",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/skills/deck-add-slide/SKILL.md

@@ -59,16 +59,16 @@ Create a companion `.module.css` file matching the JSX filename (e.g., `MyNewSli
 ```css
 .myNewSlide {
   background: var(--bg-deep);
-  flex-direction: column;
   padding: 0 0 44px 0;
 }
 ```
 
 - `background: var(--bg-deep)` — dark background on every slide
-- `flex-direction: column` — global `.slide` sets `display: flex`; this orients content vertically
 - `padding: 0 0 44px 0` — reserves space for the 44px BottomBar
 
-Optional: add `justify-content: center` to vertically center content (cover slides, thank-you slides).
+The engine's `.slide` class provides `flex-direction: column`, `justify-content: center`, `align-items: stretch`, and `overflow: hidden` by default. It also sets `flex-grow: 0` on all direct slide children, so **content stays at its natural height and is vertically centered by default** — building from the center outward. No scrolling is allowed.
+
+For dense slides that need top-alignment, override with `justify-content: flex-start`.
 
 ### Orb positioning (standard recipe)
 
@@ -85,7 +85,7 @@ Optional: add `justify-content: center` to vertically center content (cover slid
 }
 ```
 
-### Vertical centering body wrapper
+### Body wrapper
 
 ```css
 .body {
@@ -93,12 +93,12 @@ Optional: add `justify-content: center` to vertically center content (cover slid
   z-index: 10;
   display: flex;
   flex-direction: column;
-  justify-content: center;
-  flex: 1;
-  min-height: 0;
+  gap: 24px;
 }
 ```
 
+> **Do NOT add `flex: 1` or `flex-grow: 1`** to the body wrapper or any direct slide child — it stretches the wrapper to fill the slide and defeats the engine's built-in vertical centering. Inner elements within the body should also avoid `flex: 1` unless they genuinely need to fill remaining space within the body.
+
 ### Available CSS custom properties
 
 ```
@@ -190,7 +190,23 @@ export default {
 
 ---
 
-## F. Anti-Patterns to Avoid
+## F. Content Density Limits
+
+Slides must never overflow the viewport. The engine shows a **red dashed border warning** in dev mode when content exceeds the slide bounds. Follow these limits:
+
+| Layout | Max items | Notes |
+|--------|-----------|-------|
+| Cards (3-col grid) | 6 (2 rows) | Reduce card padding if tight |
+| Cards (2-col grid) | 4 (2 rows) | Preferred for detailed cards |
+| Timeline / event list | 3–4 items | Use compact card height for 4 |
+| Bullet points | 6–8 | Depends on line length |
+| Full-width content blocks | 2–3 | E.g. quote + detail section |
+
+**When content exceeds limits**, split across multiple slides rather than cramming.
+
+---
+
+## G. Anti-Patterns to Avoid
 
 1. **Missing `accent-bar`** — include on every slide.
 2. **Missing `content-frame content-gutter`** — content will be full-width without standard margins.
@@ -198,10 +214,13 @@ export default {
 4. **String paths for images** — always use `import logo from '../data/...'` (Vite resolves to URL).
 5. **Missing `padding: 0 0 44px 0`** on the slide root CSS class — content will overlap the BottomBar.
 6. **Inconsistent `BottomBar text`** — check existing slides and match their footer text.
+7. **Using `flex: 1` on body wrapper** — defeats vertical centering; the body should size to its content.
+8. **Adding `flex-direction: column` on slide root** — already provided by the engine's `.slide` class.
+9. **Overloading a slide** — if the dev server shows a red dashed border, the slide has too much content. Split into multiple slides.
 
 ---
 
-## G. Complete Step-by-Step
+## H. Complete Step-by-Step
 
 1. **Create** `src/slides/<SlideName>Slide.jsx` following the mandatory skeleton (section A).
 2. **Create** `src/slides/<SlideName>Slide.module.css` with required root properties (section B).
@@ -211,7 +230,7 @@ export default {
 ### Quick checklist
 
 - [ ] Created `<SlideName>Slide.jsx` with Slide, accent-bar, orbs, content-frame, BottomBar
-- [ ] Created `<SlideName>Slide.module.css` with `background: var(--bg-deep)`, `flex-direction: column`, `padding: 0 0 44px 0`, body centering wrapper
+- [ ] Created `<SlideName>Slide.module.css` with `background: var(--bg-deep)`, `padding: 0 0 44px 0`, body wrapper (no `flex: 1`)
 - [ ] Import added to `deck.config.js`
 - [ ] Component added to `slides` array at correct position
 - [ ] `BottomBar text` matches project convention

package/skills/deck-validate-project/SKILL.md

@@ -35,8 +35,9 @@ For each slide `.jsx` file in `src/slides/`, verify:
 
 For each `.module.css` file, verify the root class has:
 - [ ] `background: var(--bg-deep)`
-- [ ] `flex-direction: column`
 - [ ] `padding: 0 0 44px 0`
+- [ ] Does NOT use `flex: 1` on the body wrapper (defeats vertical centering)
+- [ ] Does NOT redundantly set `flex-direction: column` (inherited from engine `.slide` class)
 
 ---
 
@@ -76,5 +77,5 @@ Summarize findings:
 - [ ] Every `.jsx` slide has a companion `.module.css`
 - [ ] All slides have accent-bar, content-frame, BottomBar
 - [ ] BottomBar text is consistent across the project
-- [ ] CSS root classes have required properties
+- [ ] CSS root classes have required properties (`background`, `padding`) and no `flex: 1` on body wrapper
 - [ ] Project metadata (id, title, subtitle, icon, accent) is present

package/styles/global.css

@@ -40,6 +40,9 @@ html, body, #root {
   position: absolute;
   inset: 0;
   display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: stretch;
   opacity: 0;
   pointer-events: none;
   transition: opacity 0.6s cubic-bezier(0.4, 0, 0.2, 1),
@@ -47,6 +50,9 @@ html, body, #root {
   transform: translateX(60px);
   overflow: hidden;
 }
+.slide > * {
+  flex-grow: 0;
+}
 .slide.active {
   opacity: 1;
   pointer-events: auto;
@@ -57,6 +63,24 @@ html, body, #root {
   transform: translateX(-60px);
 }
 
+/* ── Dev-mode overflow warning ── */
+.slide-overflow-warn {
+  position: absolute;
+  inset: 0;
+  border: 3px dashed #f85149;
+  pointer-events: none;
+  z-index: 9999;
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  padding-bottom: 56px;
+  background: rgba(248, 81, 73, 0.04);
+  font-size: 13px;
+  font-weight: 600;
+  color: #f85149;
+  letter-spacing: 0.3px;
+}
+
 /* ── Shared Decorations ── */
 .orb {
   position: absolute;
@@ -98,11 +122,7 @@ html, body, #root {
    ══════════════════════════════════════════════════ */
 .deck-ty {
   background: var(--bg-deep);
-  flex-direction: column;
-  align-items: stretch;
-  justify-content: center;
   padding: 0 0 44px 0;
-  overflow: hidden;
 }
 
 /* Ambient glow orbs */