Skip to content
← Public packages

@kentcdodds/cloudflare-connect-personal-software-ecosystem

I Built Your Personal Software Ecosystem: Kent C. Dodds's Cloudflare Connect 2026 lightning talk deck (Reveal.js). How Kody gives every user one of everything on Cloudflare.

FollowForkOpen app

Files

AGENTS.md

119 lines · 8.5 KB · Markdown

Agent guide: cloudflare-connect-personal-software-ecosystem

A Kody package app that serves one self-contained slide deck for Kent C. Dodds's Cloudflare Connect 2026 lightning talk. It makes no external requests: no CDNs, remote fonts, hotlinked images, or analytics. It declares no credentials, secrets, jobs, webhooks, or other capabilities; keep it that way so it can stay internet-visible.

It is a fork of the deck in kentcdodds/kcd-content at events/personal-software-ecosystem/slides/. That repo and its pages.dev deployment are separate; never edit them from here.

Layout

  • The deck is Reveal.js 5.2.1, pinned in package.json (devDependencies, exact version). Don't add a custom slide engine, and don't load Reveal from a CDN.
  • app/router.ts: the app entry (default export { fetch }). It serves index.html for every path, plus /favicon.ico and /health (JSON).
  • app/assets.generated.ts and dist/index.html: generated by npm run build. Never edit them by hand. Rebuild and commit both after any change under src/.
  • scripts/build.mjs composes src/deck.html with every src/slides/*.html (file-name order), wraps them in Reveal vertical stacks from src/slides/groups.json (one array of slide ids per column, mirroring the source deck's groups), and inlines everything: vendor:<path> references are read from node_modules (Reveal's CSS, JS and notes plugin), other names from src/c/, and every c/... file (including url(c/...) in inline styles) becomes a data URI. It fails if groups.json misses a slide, lists one twice, or reads in a different order than the files (so Space order and slide numbers match the files), if markup or CSS points anywhere else, if any owned file or the output contains an em dash (U+2014), or if visible slide text or notes contain "used to", "now", "switched", "removed" or "we moved".
  • src/slides/*.html: each starts with <section id="..." data-title="...">. The id is the Reveal hash (#/<id>), so keep ids stable. Each file is one slide; the build adds the outer stack <section>, so never nest sections in a slide file. A new slide goes in the column for its topic in groups.json. Slide CSS in a <style> wrapped in @scope { ... } is rewritten into selectors prefixed with .reveal .slides section#<id> (descendant, because slides sit inside their stack). Speaker notes go in <aside class="notes">.
  • data-state="connect" on a section turns on the Connect look (orange full-bleed background, Connect cloud mark, no corner marks or slide number). Only title and thank-you use it.
  • src/c/deck.js: the Reveal config on a 1280x720 canvas (the source deck's size), controls bottom-right, slide transition unless ?static, ?linear, notes plugin. Leave hashOneBasedIndex off: with it on, the speaker view opens one slide behind. slideNumber: 'c/t' counts every slide in Space order. Stack memory (from the source deck): Left / Right into a column return to the slide last seen there; it only acts on Left / Right keys and arrow controls, so deep links and deck.slide(h, v) land exactly. It also has the theme logic (system theme, ?theme=, the T key saved in localStorage under cf-connect-pse-theme) and a tiny TypeScript, JSON and Markdown highlighter. window.__deck is the Reveal instance, for tests.
  • Animated widgets (elephant, secret-gateway, primitives-manifest, agent-buttons): ported from the kody.codes features page, kody-hq/kody at b75b767. Each slide holds a .pw-host with the scene frame, a <template data-pw-state="..."> per state (the site's React components rendered to static HTML, then relabelled for the deck), and optional .pw-control buttons. data-pw-seq is the loop ([[state, ms], ...]) and data-pw-still the finished frame. src/c/pw.css is the site's .pw CSS (styles.css and feature-scenes/.css) with every selector prefixed by .reveal; its colours use light-dark(), so color-scheme follows html[data-theme]. Icons are <span class="pw-icon" data-icon="..."> mapped to `src/c/img/icons/.svgin pw.css.src/c/pw.js (initPrimitiveWidgets, window.__widgets) plays the loop only on the current slide: entering restarts it, leaving sets data-pausedand stops the timer.data-motion turns the site's keyframes on; without it (?staticonly) each scene is a still. Reduced motion keeps the widgets running withdata-soft(eased, no transitions); Kent wants them moving on phones with Remove animations or Reduce Motion on. Under 435px wide Reveal switches to its scroll view, which ignores the URL hash and landsslide(h, v)one page early; deck.js scrolls to the requested slide's page instead. Clicks on[data-pw-go]` swap state, and pointer events never reach Reveal. To change a widget, edit the rendered HTML in its slide (all states) and keep names consistent with the notes.
  • Flow widgets (how-execute, how-import, cloudflare-runtime, cloudflare-data): the deck's own, in the same style and with the same .pw-host structure. The markup sits between <!-- pw-flow:start --> and <!-- pw-flow:end --> in each slide: .pwf-card cards placed by left / top in stage pixels, .pwf-wire groups with data-from / data-to card indices (pw.js draws them edge to edge; data-dir="v" forces vertical, data-lane offsets parallel wires) and .pwf-label chips placed on wire data-wire. data-lit cards, wires and labels switch on at --d seconds into each state.
  • No widget has a scene panel: pw.js measures the cards over every state, shifts them to center, and trims the stage to their height, so the host centers them on the slide.
  • src/c/deck.css: the kody.codes theme from the source deck. src/c/connect.css: Connect tokens and slides, flow diagrams (.flow), Cloudflare product diagrams (.cfd), and the per-user list. Slides only use CSS variables, so both themes work. QR codes stay dark on white in both.

Content rules

  • Slides are for the audience: a headline plus a few short lines, a diagram, or a short code sample. No instructions or reminders on slides; cues go in the notes.
  • Present tense only. No em dashes anywhere (slides, notes, docs, commit messages).
  • Diagrams and titles stay optically centered; check screenshots in both themes.
  • A slide that names a specific package or PR links to it.
  • Only claim Cloudflare products that kody-hq/kody actually uses (check wrangler config and docs/ there). The deck claims Worker Loaders, Workflows, Queues, Email Routing, Durable Objects (named per user), Artifacts, D1, R2, Vectorize and Workers KV.
  • The shades example is @kentcdodds/home-controls (export bond-area-shades) everywhere. Use example secret names like bondApiToken or githubAccessToken; never a real host, password, or value.
  • No tokens, IDs, private URLs, emails, or personal details. The package is public.

Verify

npm run build
npm run verify   # needs playwright; set CHROMIUM_PATH to choose a browser

verify blocks all network access and walks every slide with Space in light and dark at 1920x1080 and 1280x720 with every fragment shown, checking each slide's column and row and its slide number, saving screenshots into verify-shots/<theme>-<width>/. It fails on console errors, any network request, missing fonts, content that overflows the slide or scrolls sideways, text under about 22px, a slide without notes, a broken deep link, a T toggle that doesn't flip the theme, a speaker view that doesn't show the notes, Down / Up leaving a column, Right not landing on the next column's top, Left not restoring the remembered slide, or an em dash in the page. For the widgets it fails when a ?static widget animates, a reduced-motion one doesn't, a widget isn't animating on its own slide, any other widget animates at the same time, a widget overflows mid-animation, or a click inside a widget moves the deck or doesn't change the widget. It also opens every widget slide on phones (Chromium as a Pixel 7 and WebKit as an iPhone 15, portrait and landscape, with and without reduced motion) by link and by swiping, checks the widget runs and that a tap changes it but not the slide, and saves verify-shots/mobile-<engine>-<orientation>/<slide>.png; WebKit needs npx playwright install webkit. It saves two frames of each into verify-shots/widgets-<theme>-<width>/. Widget labels keep the site's scale, with an 11px floor. It saves the overview (Esc), zoomed out to show every column, as verify-shots/overview-<theme>.png.