deckpipe.dev

deckpipe is a slide deck rendering engine. You author each slide as HTML/CSS/JS — deckpipe renders it inside a sandboxed 1920×1080 shadow root and gives every deck a shareable viewer URL with built-in commenting. WORKFLOW - Use create_deck for NEW decks. Use update_deck to modify EXISTING decks. - START FROM A TEMPLATE: to base a new deck on an existing one, use clone_deck (any deck ID works as a template) to get a fresh deck with its own URL + edit key and no inherited comments, then shape it with update_deck. Don't hand-copy slides through create_deck, and never edit the template itself when you mean to make a copy. - NEVER recreate a deck to make changes. Recreating loses the URL, edit key, and comment history. Always update in place. - CALIBRATE DENSITY FIRST: before authoring a whole deck, build ONE representative content-heavy slide via preview_slide and look at the actual screenshot. The cover/title is the wrong slide to calibrate on — pick one that carries real text. If the user hasn't specified slide count or a reference style (Apple keynote / Pentagram case study / NYT Magazine / investor pitch / status update), ASK before committing — those signals are what tell you how much whitespace to use. - ITERATE BEFORE COMMITTING: use preview_slide to render an HTML/CSS/JS draft and get a screenshot + render report. Both preview_slide and get_slide_screenshot return the actual rendered PNG inline — read it. The image is ground truth. - SWEEP FOR OVERFLOWS AFTER CREATING: after create_deck, call get_slide_screenshot on every slide that carries dense text, large headlines, charts, or images. Read the "overflows" list. Any entry with reason:"off_canvas" or reason:"clipped" is a real bug — fix with update_deck before declaring the deck done. Pay special attention to slides where headlines + body + footer compete for vertical space. - Round trip on an existing deck: get_deck (read state + open comments) → get_slide_screenshot (see how a slide actually renders) → update_deck (make changes) → reply_to_comment (explain what you changed). - Check the "warnings" array in every create/update response. CONTENT DENSITY - One idea per slide. If a slide is carrying a headline + lede + tag row + callout + pull-quote + attribution, you have three slides compressed into one — split it. - Whitespace is a design element, not wasted space. Editorial decks read better at 20 sparse slides than 12 dense ones. Prefer breathing room unless the user explicitly asked for an information-dense format. - Headlines ≤ 8 words. One concept per paragraph. Strip ornamentation before the final pass. - The render report's "overflows" list is a SYNTACTIC check (off-canvas elements, content clipped by overflow:hidden). It says nothing about whether the slide looks good. A wall of text with no overflows is still a wall of text — the screenshot is the only signal that catches "too dense to read". Look at the image. THE CANVAS LAYOUT - Every slide is { layout: "canvas", content: { html (required), css?, js?, static_render_only? } }. - "html" is the full slide markup, rendered into a 1920×1080 frame. CSS in "css" is scoped to this slide only; for shared styles use deck.stylesheet. - Each slide mounts in an open shadow root, so your CSS is auto-scoped — no BEM, no class prefixes. - "js" runs on slide enter with (root, slide) in scope. Return a cleanup function for slide exit. Set static_render_only: true to skip JS in print/PDF and screenshots. LAYOUT SAFETY (the box-sizing + footer-reserve trap) - Open every deck.stylesheet with a universal box-sizing reset: `*, *::before, *::after { box-sizing: border-box }`. Without it, an element with `height:100%; padding:Xpx` becomes 100% + 2X in computed height and overflows its parent. This is the #1 cause of "content overlaps the footer" bugs. - If a slide has a bottom-fixed footer/page-number row (e.g. `position:absolute; bottom:48px`), the in-flow content's bottom padding must clear it. A safe pattern is `.slide { padding: 112px 128px 160px }` so content never reaches the footer band. Same for any full-bleed slide's `.hero-content` analogue — its padding-bottom must reserve ~160px. - After authoring the stylesheet, build the most VERTICALLY DENSE slide first (one with big headline + body + chart/diagram + footer) and screenshot it. If a headline + body + chart overflows, you'll see it here before propagating the same mistake to every slide. DECK-LEVEL THEMING (define once, reference everywhere) - stylesheet: global CSS string (up to 100KB) adopted by every canvas slide. Define your design system here. Worked example for a real 1920×1080 design system: *, *::before, *::after { box-sizing: border-box; } .slide { width: 1920px; height: 1080px; padding: 112px 144px 160px; font-family: 'Inter', system-ui, sans-serif; color: #0f172a; background: #fafaf9; position: relative; overflow: hidden; } .h1 { font-family: 'Fraunces', serif; font-size: 128px; line-height: 0.98; letter-spacing: -0.03em; margin: 0; } .h2 { font-family: 'Fraunces', serif; font-size: 64px; line-height: 1.05; margin: 0; } .lead { font-size: 32px; line-height: 1.45; color: #475569; max-width: 1500px; } .label { font-family: 'JetBrains Mono', monospace; font-size: 18px; letter-spacing: 0.18em; text-transform: uppercase; color: #94a3b8; } .card { padding: 56px; border-radius: 28px; background: #ffffff; border: 1px solid #e2e8f0; } .row { display: flex; gap: 48px; align-items: stretch; } Notice the scale: padding in 100s of px, body in 24–32px, h1 in 100+px. Designs sized for a 16px-base browser look tiny at 1920×1080. - tokens: a flat { "--name": "value" } map injected into every slide as :host { … }. Put your palette / spacing / radius here, reference with var(--name) in stylesheet and slide css. Unlike stylesheet, tokens are PATCHABLE one at a time via update_deck — flip --accent without re-sending the whole stylesheet. - head: array of { tag, attrs?, body? } entries injected into the page head. Load Google Fonts here as <link> entries, then set font-family in deck.stylesheet on .h1/.h2/.body classes (or whatever your design system calls them). COMMENTING - Reviewers can comment on ANY DOM element in a canvas slide — deckpipe auto-assigns a content_path to every element at render time. - For comment threads that survive edits, mark target elements with data-dp-anchor="<stable-name>" (e.g. data-dp-anchor="hero-title"). Preserve those IDs in updates so threads stay attached. - Unmarked elements get auto:<index> paths — stable within a render but may shift if you restructure. Use anchors for anything you'll iterate on. INLINE EDITS - The viewer's edit mode makes text-bearing leaf elements (h1, p, span, etc.) contenteditable. On blur the full html is saved back via PATCH. - Your "js" should be resilient to text changes — find elements with selectors or data attributes, never with exact strings. IMAGES - search_images returns full-resolution URLs (url, url_full), photographer info, and a pre-built attribution_html snippet. Drop the url into <img src> on a canvas slide and the attribution_html into a small caption near the image. Download tracking fires server-side automatically. - upload_image hosts your own image (PNG/JPG/WebP/GIF/SVG, max 10MB) and returns a URL for <img src>. Three ways to provide it, simplest first: a local file "path" (only when the server runs on your machine), a remote "url" the server fetches and re-hosts, or base64 "image_data" + filename + content_type. Pass exactly one. CONTENT STYLE - Short, crisp, scannable. Headlines ≤ 8 words. Stats abbreviated ("2.4M" not "2,400,000"). Quotes under 30 words. AUTHORING GOTCHAS (the things you'd otherwise learn by trial and error) - CSS lives in a SHADOW ROOT. deck.stylesheet and per-slide css are adopted into each slide's shadow tree, so selectors only match inside the slide (no leakage, no prefixes needed). Declare deck-wide custom properties on :host — a bare ":root { … }" is auto-rewritten to ":host" for you, so either works. Once a token is defined there (or in the tokens map), var() resolves EVERYWHERE, including background:, background-image:, and gradients. - Change one value cheaply. To tweak a single design value, PATCH the tokens map (update_deck { tokens: { "--accent": "#e11" } }) instead of re-sending the whole stylesheet. And pass return:"summary" so update_deck returns a small ack instead of echoing every slide's html/css/js back at you. - Fonts DO load from head <link>s. Add a Google Fonts <link> in head (or an @font-face in stylesheet), then set font-family in stylesheet/tokens. Screenshots explicitly wait for head <link>s and force the used faces to load before capturing, so the font shows up in the render. The report's fonts_loaded/fonts_missing now lists only the faces your slide actually paints with — not every weight permutation. - Uploading images: pass a local "path" (stdio/local server) or a remote "url" — the server reads/fetches and re-hosts it, and only the short string crosses the wire. Reserve base64 "image_data" for tiny images; a multi-hundred-KB base64 blob will bloat (and may be truncated in) your context. - Inspect without re-authoring. preview_slide AND get_slide_screenshot both return the rendered PNG inline — read the image, it's ground truth. get_slide_screenshot renders a slide of an EXISTING deck, so you can see a live slide without re-sending its html. - Address slides by slide_id. In update_deck.slides, prefer { slide_id, content } over { index, content } — slide_id won't drift if the same call also inserts/moves slides via slide_operations. LEGACY LAYOUTS - 25 templated layouts (title, title_and_bullets, stats, chart, swot, …) are deprecated and not advertised. Existing decks using them still render. New slides should always use the "canvas" layout.