@dloizides/marketing-astro-kit 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -1,64 +1,90 @@
-# Changelog
-
-## 1.2.1
-
-- **a11y fix (serious): the pricing comparison was SILENT to screen readers.**
-  `PricingComparison.astro` marked each cell with `aria-label` on a bare
-  `<span>`. `aria-label` is *prohibited* on a roleless generic element, so
-  assistive tech ignored it — and the inner `<svg>` is `aria-hidden`. Net
-  effect: a screen-reader user reached every included/not-included cell and
-  heard **nothing**, so they could not tell which plan carried which feature,
-  on a public pricing page. Fixed by giving the span `role="img"` alongside
-  the existing label. Found by the `a11y-public` E2E axe scan against the live
-  kefi landing: `aria-prohibited-attr`, 27 nodes. Swept the rest of the kit —
-  no other instances of this shape.
-
-## 1.2.0
-
-- New `DemoFrame.astro` — a themeable, **client-side "try it" demo** shell for
-  static marketing sites (no backend): an eyebrow/title/intro, a row of clickable
-  example chips, a per-example result panel (bespoke product body injected via a
-  named slot `result-<example.id>`), a clearly-visible "sample data" disclaimer,
-  and a primary CTA (reuses `PrimaryCta`). Tiny inline vanilla JS toggles which
-  result shows on chip click (+ arrow-key roving tablist); the first example is
-  visible without JS (progressive enhancement). New `DemoExample` / `DemoFrameData`
-  types in `schema.ts`.
-- New `GuideCard.astro` — a themeable card for a **guides / SEO content-hub**
-  listing, rendering one guide's tags, title, description and date. New
-  `GuideCardData` type.
-- New `guideFrontmatterSchema` (Zod, built on `astro/zod`) + `GuideFrontmatter`
-  type in `schema.ts` — plug straight into an Astro content collection
-  (`defineCollection({ loader: glob(...), schema: guideFrontmatterSchema })`) so
-  every product's guides validate the same shape (title, description, slug?,
-  publishDate, updatedDate?, tags, ogImage?, canonical?, draft?). The article
-  page + routes + JSON-LD stay product-owned.
-- `schema.ts` now imports `z` from `astro/zod` (Astro is already a peer dep) —
-  the ONE runtime import; every other export stays plain types.
-
-## 1.1.0
-
-- New `PrimaryCta.astro` — a themeable primary call-to-action (link OR spam-safe
-  contact) with an optional secondary CTA and a `tone: 'light' | 'dark'` for
-  dark bands. Renders a `MarketingCta` so link-vs-lead-capture + analytics wiring
-  is no longer hand-coded per page.
-- New `buildPrimaryCta(opts)` helper + `PrimaryCtaOptions` in `schema.ts`: drive
-  a primary CTA from ONE `SIGNUP_URL` constant — a real signup link when set,
-  spam-safe lead-capture when `null` (flip at GA with no template change).
-- `ctaAttrs()` promoted from `PricingComparison.astro` into `schema.ts` and now
-  shared by every CTA-rendering component (no duplication).
-- `TrustSection` gains three optional, guarded fields (existing sites
-  unaffected): `foundingPartner` ("first N free during beta" panel),
-  `founder` (honest one-line credibility) and `sampleDeliverable` (a "here's the
-  actual report you get" showcase — image, or a `slot="sample-deliverable"` for
-  bespoke mock markup while the section chrome stays shared).
-
-## 1.0.0
-
-- Initial release. `PricingComparison.astro` (Free-vs-Pro comparison table with
-  tier columns, grouped feature rows, optional footnote + one-time callout card)
-  and `TrustSection.astro` (security cards with inline icons, customer-logo row
-  with placeholders, testimonial placeholders, discreet built-by line).
-- Framework-agnostic data schema (`schema.ts`) + inline icon set (`icons.ts`).
-- Themed via host CSS custom properties with fallbacks; no image assets.
-- Extracted from `kefi-marketing` as the 2nd genuine use of the pricing/trust
-  sections across the Astro marketing sites.
+# Changelog
+
+## 1.3.0
+
+### Added
+
+- `<HeroBackdrop />` plus the named hero-backdrop preset catalog (`./heroBackdrop`).
+  Nine animated hero treatments -- three canvas, one SVG-filter, five pure-CSS --
+  that until now existed ONLY in a disposable per-session scratchpad and had been
+  rebuilt from scratch more than once. `HERO_BACKDROP_PRESETS` is the permanent
+  record: preset name -> `{ variant, engine, palette, css, ember }`, using the
+  design studio's own parameter names verbatim so a studio export pastes in with
+  no translation step.
+- `csdf-ember-sparse` -- CSDF's shipped configuration. 40 particles, an eighth of
+  the studio default, which is what makes a canvas backdrop affordable against a
+  hard Lighthouse >= 80 budget.
+- Only the ember canvas engine ships as a RENDERER. The CSS/SVG entries are
+  recorded PARAMETER SETS painted by the host stylesheet; the component renders
+  nothing for those, leaving the host's own backdrop untouched.
+
+### Notes
+
+- The component's script is `is:inline` deliberately -- a bundled Astro script
+  emits a root-absolute `/_astro/*.js` reference, which 404s under kefi-landings'
+  host-based per-tenant nginx roots.
+- Respects `prefers-reduced-motion` (one still frame, no loop) and stops the rAF
+  loop on `visibilitychange` and when the canvas leaves the viewport.
+
+## 1.2.1
+
+- **a11y fix (serious): the pricing comparison was SILENT to screen readers.**
+  `PricingComparison.astro` marked each cell with `aria-label` on a bare
+  `<span>`. `aria-label` is *prohibited* on a roleless generic element, so
+  assistive tech ignored it — and the inner `<svg>` is `aria-hidden`. Net
+  effect: a screen-reader user reached every included/not-included cell and
+  heard **nothing**, so they could not tell which plan carried which feature,
+  on a public pricing page. Fixed by giving the span `role="img"` alongside
+  the existing label. Found by the `a11y-public` E2E axe scan against the live
+  kefi landing: `aria-prohibited-attr`, 27 nodes. Swept the rest of the kit —
+  no other instances of this shape.
+
+## 1.2.0
+
+- New `DemoFrame.astro` — a themeable, **client-side "try it" demo** shell for
+  static marketing sites (no backend): an eyebrow/title/intro, a row of clickable
+  example chips, a per-example result panel (bespoke product body injected via a
+  named slot `result-<example.id>`), a clearly-visible "sample data" disclaimer,
+  and a primary CTA (reuses `PrimaryCta`). Tiny inline vanilla JS toggles which
+  result shows on chip click (+ arrow-key roving tablist); the first example is
+  visible without JS (progressive enhancement). New `DemoExample` / `DemoFrameData`
+  types in `schema.ts`.
+- New `GuideCard.astro` — a themeable card for a **guides / SEO content-hub**
+  listing, rendering one guide's tags, title, description and date. New
+  `GuideCardData` type.
+- New `guideFrontmatterSchema` (Zod, built on `astro/zod`) + `GuideFrontmatter`
+  type in `schema.ts` — plug straight into an Astro content collection
+  (`defineCollection({ loader: glob(...), schema: guideFrontmatterSchema })`) so
+  every product's guides validate the same shape (title, description, slug?,
+  publishDate, updatedDate?, tags, ogImage?, canonical?, draft?). The article
+  page + routes + JSON-LD stay product-owned.
+- `schema.ts` now imports `z` from `astro/zod` (Astro is already a peer dep) —
+  the ONE runtime import; every other export stays plain types.
+
+## 1.1.0
+
+- New `PrimaryCta.astro` — a themeable primary call-to-action (link OR spam-safe
+  contact) with an optional secondary CTA and a `tone: 'light' | 'dark'` for
+  dark bands. Renders a `MarketingCta` so link-vs-lead-capture + analytics wiring
+  is no longer hand-coded per page.
+- New `buildPrimaryCta(opts)` helper + `PrimaryCtaOptions` in `schema.ts`: drive
+  a primary CTA from ONE `SIGNUP_URL` constant — a real signup link when set,
+  spam-safe lead-capture when `null` (flip at GA with no template change).
+- `ctaAttrs()` promoted from `PricingComparison.astro` into `schema.ts` and now
+  shared by every CTA-rendering component (no duplication).
+- `TrustSection` gains three optional, guarded fields (existing sites
+  unaffected): `foundingPartner` ("first N free during beta" panel),
+  `founder` (honest one-line credibility) and `sampleDeliverable` (a "here's the
+  actual report you get" showcase — image, or a `slot="sample-deliverable"` for
+  bespoke mock markup while the section chrome stays shared).
+
+## 1.0.0
+
+- Initial release. `PricingComparison.astro` (Free-vs-Pro comparison table with
+  tier columns, grouped feature rows, optional footnote + one-time callout card)
+  and `TrustSection.astro` (security cards with inline icons, customer-logo row
+  with placeholders, testimonial placeholders, discreet built-by line).
+- Framework-agnostic data schema (`schema.ts`) + inline icon set (`icons.ts`).
+- Themed via host CSS custom properties with fallbacks; no image assets.
+- Extracted from `kefi-marketing` as the 2nd genuine use of the pricing/trust
+  sections across the Astro marketing sites.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dloizides/marketing-astro-kit",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Reusable, themeable Astro marketing sections for product sites — a Free-vs-Pro pricing comparison table, a trust / credibility section (security cards, customer-logo + testimonial placeholders, discreet built-by), a client-side \"try it\" demo shell, and an SEO guides/content-hub card + frontmatter schema. Data-driven via a shared TypeScript schema; themed entirely through the host site's CSS custom properties.",
   "keywords": [
     "astro",
@@ -13,7 +13,11 @@
     "content-hub",
     "seo",
     "landing-page",
-    "saas"
+    "saas",
+    "hero",
+    "background",
+    "canvas",
+    "animation"
   ],
   "author": "dloizides",
   "license": "MIT",
@@ -34,7 +38,10 @@
     "./DemoFrame.astro": "./src/DemoFrame.astro",
     "./GuideCard.astro": "./src/GuideCard.astro",
     "./schema": "./src/schema.ts",
-    "./icons": "./src/icons.ts"
+    "./icons": "./src/icons.ts",
+    "./HeroBackdrop.astro": "./src/HeroBackdrop.astro",
+    "./heroBackdrop": "./src/heroBackdrop/presets.ts",
+    "./heroBackdrop/types": "./src/heroBackdrop/types.ts"
   },
   "peerDependencies": {
     "astro": ">=4"

package/src/HeroBackdrop.astro

@@ -0,0 +1,339 @@
+---
+// ============================================================================
+// <HeroBackdrop /> — an animated hero backdrop, pulled by name from the catalog.
+// ----------------------------------------------------------------------------
+// 🔴 READ BEFORE PUTTING THIS ON A NEW TENANT.
+//
+// Every other kefi hero backdrop is pure CSS/SVG with ZERO main-thread
+// JavaScript, and that is a deliberate design goal, not an accident — an
+// earlier rAF loop writing SVG filter attributes ~30x/sec cost roughly half the
+// frame budget of the page. This component is the ONE exception: a <canvas>
+// driven by requestAnimationFrame. It must therefore be OPT-IN PER TENANT and
+// must never become a site default. Seven kefi tenants share one deployment, so
+// a default here regresses all seven at once.
+//
+// Three things keep it affordable. All are load-bearing:
+//   1. `prefers-reduced-motion: reduce` paints ONE settled still frame and
+//      never starts the loop.
+//   2. The loop stops when the tab is hidden (`visibilitychange`) and when the
+//      canvas scrolls out of view (IntersectionObserver). A hero is off-screen
+//      for most of a session; without this the cost is paid for the whole visit.
+//   3. Particle COUNT dominates per-frame cost. `csdf-ember-sparse` runs 40 —
+//      an eighth of the studio default — precisely so this can sit on a site
+//      with a hard Lighthouse >= 80 budget.
+//
+// The script is `is:inline` ON PURPOSE, not by oversight. kefi-landings serves
+// each tenant from an nginx root pointed at that tenant's own subdirectory, and
+// a bundled Astro <script> emits a ROOT-ABSOLUTE `/_astro/*.js` reference,
+// which 404s under host-based serving (this is the same reason the site sets
+// `inlineStylesheets: 'always'`). Inline keeps the page self-contained. Do not
+// "clean this up" into a module import without changing how tenants are served.
+// ============================================================================
+import type { HeroBackdropPreset } from './heroBackdrop/types';
+
+interface Props {
+  /** A catalog entry — see `@dloizides/marketing-astro-kit/heroBackdrop`. */
+  preset: HeroBackdropPreset;
+  /** Extra class on the canvas, for host-side positioning / z-index. */
+  class?: string;
+  /**
+   * Optional selector for the element the canvas should be moved INTO, as its
+   * first child, before it is sized.
+   *
+   * Astro renders a layout's markup and then the caller's, so a component used
+   * alongside a layout cannot place a node inside that layout's hero at build
+   * time. The move happens synchronously in the inline script -- the hero has
+   * already been parsed by the time this script tag is reached -- so the canvas
+   * is in its final position before the first `getBoundingClientRect()`. Sizing
+   * it in place and moving it afterwards would measure the wrong box.
+   */
+  mountSelector?: string;
+}
+
+const { preset, class: className = '', mountSelector = '' } = Astro.props;
+
+// Only the ember engine is implemented here. Every other catalog entry is a
+// recorded PARAMETER SET, not a shipped renderer — the CSS families are painted
+// by the host site's own stylesheet, which is where they belong (no JS at all).
+// Rendering nothing is the correct degradation: the host's existing backdrop is
+// left exactly as it was.
+const isEmberCanvas = preset.engine === 'canvas' && preset.variant === 'ember';
+const cfg = isEmberCanvas ? { palette: preset.palette, ember: preset.ember } : null;
+---
+
+{
+  isEmberCanvas && (
+    <canvas
+      class:list={['hero-backdrop', className]}
+      data-hero-backdrop="ember"
+      aria-hidden="true"
+    />
+  )
+}
+
+{
+  isEmberCanvas && (
+    <script is:inline define:vars={{ heroBackdropCfg: cfg, heroBackdropMount: mountSelector }}>
+      (function () {
+        var cfg = heroBackdropCfg;
+        var cv = document.querySelector('canvas[data-hero-backdrop="ember"]');
+        if (!cv || !cv.getContext || !cfg || !cfg.ember) return;
+
+        if (heroBackdropMount) {
+          var host = document.querySelector(heroBackdropMount);
+          /* No host is not an error: the backdrop simply does not mount and the
+             page keeps whatever backdrop it already had. Never blank the hero. */
+          if (!host) {
+            if (cv.parentNode) cv.parentNode.removeChild(cv);
+            return;
+          }
+          host.insertBefore(cv, host.firstChild);
+        }
+
+        var EP = cfg.ember;
+        var ctx = cv.getContext('2d');
+        var reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+        /* ---- palette: six hex stops -> rgb triples + soft radial sprites ---- */
+        var STOPS = cfg.palette.map(function (h) {
+          var n = parseInt(h.slice(1), 16);
+          return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+        });
+        function rgba(i, a) {
+          var c = STOPS[i];
+          return 'rgba(' + c[0] + ',' + c[1] + ',' + c[2] + ',' + a + ')';
+        }
+        var SPRITE_PX = 64;
+        var sprites = {};
+        function sprite(i) {
+          if (sprites[i]) return sprites[i];
+          var rgb = STOPS[5 - i];
+          var c = document.createElement('canvas');
+          c.width = SPRITE_PX;
+          c.height = SPRITE_PX;
+          var g = c.getContext('2d');
+          var half = SPRITE_PX / 2;
+          var grad = g.createRadialGradient(half, half, 0, half, half, half);
+          var col = 'rgba(' + rgb[0] + ',' + rgb[1] + ',' + rgb[2] + ',';
+          grad.addColorStop(0, col + '1)');
+          grad.addColorStop(0.28, col + '0.55)');
+          grad.addColorStop(0.62, col + '0.16)');
+          grad.addColorStop(1, col + '0)');
+          g.fillStyle = grad;
+          g.fillRect(0, 0, SPRITE_PX, SPRITE_PX);
+          sprites[i] = c;
+          return c;
+        }
+
+        /* ---- value noise, seeded so the field is identical on every load ---- */
+        var PERM = new Uint8Array(512);
+        (function seedPerm() {
+          var p = new Uint8Array(256);
+          var i;
+          for (i = 0; i < 256; i++) p[i] = i;
+          var seed = 1337;
+          function rnd() {
+            seed = (seed * 1664525 + 1013904223) >>> 0;
+            return seed / 4294967296;
+          }
+          for (i = 255; i > 0; i--) {
+            var j = (rnd() * (i + 1)) | 0;
+            var tmp = p[i];
+            p[i] = p[j];
+            p[j] = tmp;
+          }
+          for (i = 0; i < 512; i++) PERM[i] = p[i & 255];
+        })();
+        function hash2(x, y) {
+          return PERM[(PERM[x & 255] + (y & 255)) & 255] / 255;
+        }
+        function smooth(v) {
+          return v * v * (3 - 2 * v);
+        }
+        function valueNoise(x, y) {
+          var xi = Math.floor(x);
+          var yi = Math.floor(y);
+          var u = smooth(x - xi);
+          var v = smooth(y - yi);
+          var a = hash2(xi, yi);
+          var b = hash2(xi + 1, yi);
+          var c = hash2(xi, yi + 1);
+          var d = hash2(xi + 1, yi + 1);
+          var top = a + (b - a) * u;
+          return top + (c + (d - c) * u - top) * v;
+        }
+
+        /* ---- particles ---- */
+        var parts = [];
+        var t = 0;
+        function gaussian() {
+          var r = (Math.random() + Math.random() + Math.random()) / 3 - 0.5;
+          return ((r < 0 ? -1 : 1) * Math.pow(Math.abs(r * 2), EP.focus)) / 2;
+        }
+        function spawn(p) {
+          p.x = 0.5 + gaussian() * EP.width;
+          p.y = 1.02 + Math.random() * 0.05;
+          p.vx = (Math.random() - 0.5) * 0.02;
+          p.vy = -(0.09 + Math.random() * 0.13) * EP.rise;
+          p.life = 0;
+          p.max = (0.85 + Math.random() * 1.05) * EP.life;
+          p.r0 = (0.028 + Math.random() * 0.055) * EP.size;
+          p.seed = Math.random() * 100;
+        }
+        function ensure() {
+          var want = EP.count | 0;
+          while (parts.length < want) {
+            var p = {};
+            spawn(p);
+            p.life = Math.random() * p.max;
+            parts.push(p);
+          }
+          if (parts.length > want) parts.length = want;
+        }
+        function step(dt) {
+          var s = Math.min(dt, 50) / 1000;
+          t += s;
+          for (var i = 0; i < parts.length; i++) {
+            var p = parts[i];
+            p.life += s;
+            if (p.life >= p.max || p.y < -0.12) {
+              spawn(p);
+              continue;
+            }
+            var n = valueNoise(p.x * 4.2 * EP.swirl + p.seed, p.y * 3.4 * EP.swirl - t * 1.25) - 0.5;
+            var n2 = valueNoise(p.x * 9.5 * EP.swirl + 31.7, p.y * 7.1 * EP.swirl - t * 2.1) - 0.5;
+            p.vx += (n * 0.3 + n2 * 0.14) * EP.drift * s * 2.4;
+            p.vx *= 0.965;
+            var age = p.life / p.max;
+            p.vy -= 0.055 * s * (1 - age) * EP.rise;
+            p.x += p.vx * s;
+            p.y += p.vy * s;
+          }
+        }
+        function draw() {
+          var w = cv.width;
+          var h = cv.height;
+          ctx.globalCompositeOperation = 'source-over';
+          ctx.globalAlpha = 1;
+          ctx.fillStyle = rgba(0, 1);
+          ctx.fillRect(0, 0, w, h);
+
+          /* The bed of heat the column sits in. Without it the sprites read as
+             confetti on black rather than as a fire. */
+          var bg = ctx.createRadialGradient(w * 0.5, h * 1.02, 0, w * 0.5, h * 1.02, h * EP.bloomH);
+          bg.addColorStop(0, rgba(3, 0.42 * EP.bloomA));
+          bg.addColorStop(0.35, rgba(2, 0.18 * EP.bloomA));
+          bg.addColorStop(0.7, rgba(1, 0.1 * EP.bloomA));
+          bg.addColorStop(1, rgba(0, 0));
+          ctx.fillStyle = bg;
+          ctx.fillRect(0, 0, w, h);
+
+          ctx.globalCompositeOperation = 'lighter';
+          for (var i = 0; i < parts.length; i++) {
+            var p = parts[i];
+            var age = p.life / p.max;
+            if (age < 0 || age > 1) continue;
+            /* cool gold -> flame -> ember -> deep, as the particle ages */
+            var ci = age < 0.1 ? 0 : age < 0.32 ? 1 : age < 0.58 ? 2 : age < 0.82 ? 3 : 4;
+            var rad = p.r0 * (1 + age * 0.55) * (1 - age * 0.42) * h;
+            if (rad < 0.5) continue;
+            var a = (age < 0.08 ? age / 0.08 : 1 - (age - 0.08) / 0.92) * EP.alpha;
+            if (a <= 0) continue;
+            ctx.globalAlpha = a;
+            ctx.drawImage(sprite(ci), p.x * w - rad, p.y * h - rad, rad * 2, rad * 2);
+          }
+          ctx.globalAlpha = 1;
+          ctx.globalCompositeOperation = 'source-over';
+        }
+
+        /* ---- sizing. DPR is capped: a 3x phone would trebl the fill cost for
+           a backdrop nobody inspects at pixel level. ---- */
+        var MAX_DPR = 2;
+        function resize() {
+          var dpr = Math.min(window.devicePixelRatio || 1, MAX_DPR);
+          var r = cv.getBoundingClientRect();
+          cv.width = Math.max(1, Math.round((r.width || 1) * dpr));
+          cv.height = Math.max(1, Math.round((r.height || 1) * dpr));
+          draw();
+        }
+
+        /* ---- the loop, and the two conditions that stop it ---- */
+        var rafId = 0;
+        var running = false;
+        var lastT = 0;
+        var visible = !document.hidden;
+        var onScreen = true;
+        function loop(now) {
+          if (!running) {
+            rafId = 0;
+            return;
+          }
+          var dt = lastT ? now - lastT : 16;
+          lastT = now;
+          if (dt > 100) dt = 100;
+          ensure();
+          step(dt);
+          draw();
+          rafId = window.requestAnimationFrame(loop);
+        }
+        function stopLoop() {
+          running = false;
+          if (rafId) {
+            window.cancelAnimationFrame(rafId);
+            rafId = 0;
+          }
+          lastT = 0;
+        }
+        function startLoop() {
+          if (reduced || running || !visible || !onScreen) return;
+          running = true;
+          lastT = 0;
+          rafId = window.requestAnimationFrame(loop);
+        }
+
+        resize();
+        ensure();
+
+        if (reduced) {
+          /* One settled still frame: the composition, none of the motion. */
+          for (var k = 0; k < 70; k++) step(16);
+          draw();
+          return;
+        }
+
+        document.addEventListener('visibilitychange', function () {
+          visible = !document.hidden;
+          if (visible) startLoop();
+          else stopLoop();
+        });
+        if ('IntersectionObserver' in window) {
+          new IntersectionObserver(
+            function (entries) {
+              for (var i = 0; i < entries.length; i++) onScreen = entries[i].isIntersecting;
+              if (onScreen) startLoop();
+              else stopLoop();
+            },
+            { threshold: 0.02 }
+          ).observe(cv);
+        }
+        var rz = 0;
+        window.addEventListener('resize', function () {
+          window.clearTimeout(rz);
+          rz = window.setTimeout(resize, 150);
+        });
+        startLoop();
+      })();
+    </script>
+  )
+}
+
+<style>
+  .hero-backdrop {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    display: block;
+    pointer-events: none;
+  }
+</style>

package/src/heroBackdrop/presets.ts

@@ -0,0 +1,193 @@
+// ============================================================================
+// Hero backdrop — the NAMED PRESET CATALOG.
+// ----------------------------------------------------------------------------
+// This file is DATA, deliberately. Every number below was tuned by eye in
+// `background-studio.html` and exported from it; nothing here is derived, and
+// nothing here should be computed at read time. If a value looks arbitrary that
+// is because it is — it is a design decision, not a calculation.
+//
+// WHY THIS FILE EXISTS AT ALL: the nine variants below only ever existed inside
+// a disposable per-session scratchpad. They were rebuilt from nothing more than
+// once because the previous copy had been garbage-collected. A named entry here
+// is the difference between "pull the backdrop by name" and "redesign it".
+//
+// Adding a preset: copy the studio's Export block verbatim. Its key names are
+// these key names on purpose.
+// ============================================================================
+
+import type {
+  HeroBackdropCssParams,
+  HeroBackdropEmberParams,
+  HeroBackdropPalette,
+  HeroBackdropPreset,
+  HeroBackdropPresetName,
+} from './types';
+
+/**
+ * The studio's default six stops, dark -> bright. This is the CSDF/Kefi ember
+ * ramp: near-black ground, oxblood, two flame oranges, gold, and a bone-white
+ * top end that reads as the hottest core.
+ */
+export const EMBER_PALETTE: HeroBackdropPalette = [
+  '#0d0d0d',
+  '#591202',
+  '#f23005',
+  '#f25d07',
+  '#f2a007',
+  '#ffe9b0',
+];
+
+/** Studio `CSS_PRESET.low|med|high` — the CSS-layer intensity triplet. */
+const CSS_LOW: HeroBackdropCssParams = { amp: 0.72, spd: 1.35, bri: 0.72, blurk: 1.25 };
+const CSS_MED: HeroBackdropCssParams = { amp: 1.0, spd: 1.0, bri: 1.0, blurk: 1.0 };
+const CSS_HIGH: HeroBackdropCssParams = { amp: 1.34, spd: 0.72, bri: 1.3, blurk: 0.82 };
+
+/** Studio `EP_DEFAULT` — every ember preset is this, overlaid. */
+const EMBER_BASE: HeroBackdropEmberParams = {
+  width: 0.46,
+  focus: 1.0,
+  count: 320,
+  rise: 0.95,
+  drift: 1.15,
+  swirl: 1.0,
+  size: 1.12,
+  life: 1.0,
+  alpha: 0.62,
+  bloomA: 1.0,
+  bloomH: 0.85,
+};
+
+/**
+ * The catalog.
+ *
+ * `*-med` is the studio's own default for that variant — the honest starting
+ * point, not a recommendation. The three `ember-*` entries are the studio's
+ * Low/Medium/High intensity triplet.
+ */
+export const HERO_BACKDROP_PRESETS: Record<HeroBackdropPresetName, HeroBackdropPreset> = {
+  // ── canvas + rAF: real main-thread cost, opt-in per tenant ───────────────
+  'ember-low': {
+    variant: 'ember',
+    engine: 'canvas',
+    label: 'Ember column — low',
+    palette: EMBER_PALETTE,
+    css: CSS_LOW,
+    ember: { ...EMBER_BASE, count: 250, rise: 0.72, drift: 0.85, size: 1.0 },
+  },
+  'ember-med': {
+    variant: 'ember',
+    engine: 'canvas',
+    label: 'Ember column — medium',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+    ember: { ...EMBER_BASE },
+  },
+  'ember-high': {
+    variant: 'ember',
+    engine: 'canvas',
+    label: 'Ember column — high',
+    palette: EMBER_PALETTE,
+    css: CSS_HIGH,
+    ember: { ...EMBER_BASE, count: 400, rise: 1.24, drift: 1.5, size: 1.24 },
+  },
+  /**
+   * CSDF's shipped backdrop, exported from the studio verbatim.
+   *
+   * Read `count: 40` before judging this against `ember-high`. It is High's
+   * CSS intensity and High's `size`/`drift` feel on a deliberately SPARSE
+   * field — an eighth of the 320-particle default. Per-frame cost is dominated
+   * by the sprite draw loop, so the sparse field is what makes a canvas
+   * backdrop defensible on a site with a hard Lighthouse >= 80 budget.
+   * A `focus` of 0.85 flattens the column into a wider sheet to compensate,
+   * and the longer `life` (1.7) keeps each of the few sprites on screen longer.
+   */
+  'csdf-ember-sparse': {
+    variant: 'ember',
+    engine: 'canvas',
+    label: 'CSDF ember — sparse column, high intensity',
+    palette: EMBER_PALETTE,
+    css: { amp: 1.34, spd: 0.72, bri: 1.3, blurk: 0.82 },
+    ember: {
+      width: 1.2,
+      focus: 0.85,
+      count: 40,
+      rise: 2.6,
+      drift: 1.15,
+      swirl: 2.7,
+      size: 1.24,
+      life: 1.7,
+      alpha: 0.62,
+      bloomA: 1,
+      bloomH: 0.85,
+    },
+  },
+  'doom-med': {
+    variant: 'doom',
+    engine: 'canvas',
+    label: 'Doom fire — 160x110 palette-index buffer, upscaled',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+  },
+  'noise-med': {
+    variant: 'noise',
+    engine: 'canvas',
+    label: 'Noise fire — fBm scrolling upward',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+  },
+
+  // ── SVG filter: no per-frame JS, but painted on the main thread ──────────
+  'haze-med': {
+    variant: 'haze',
+    engine: 'svg',
+    label: 'Turbulent haze — feTurbulence + feDisplacementMap',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+  },
+
+  // ── pure CSS: zero main-thread JavaScript. The safe default family ───────
+  'tongues-med': {
+    variant: 'tongues',
+    engine: 'css',
+    label: 'Tongues — stacked blurred gradient blades',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+  },
+  'cssnoise-med': {
+    variant: 'cssnoise',
+    engine: 'css',
+    label: 'Masked noise — static noise tile under an animated mask',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+  },
+  'silhouette-med': {
+    variant: 'silhouette',
+    engine: 'css',
+    label: 'Silhouettes — dark shapes over a glow layer',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+  },
+  'wash-med': {
+    variant: 'wash',
+    engine: 'css',
+    label: 'Heat wash — two counter-drifting radial glows (the kefi default)',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+  },
+  'stack-med': {
+    variant: 'stack',
+    engine: 'css',
+    label: 'Full stack — tongues + noise + silhouette + wash combined',
+    palette: EMBER_PALETTE,
+    css: CSS_MED,
+  },
+};
+
+/** Narrowing lookup. Returns `undefined` for an unknown name rather than throwing:
+ *  a bad tenant config must degrade to the site's default backdrop, never blank
+ *  the hero. */
+export function getHeroBackdropPreset(name: string): HeroBackdropPreset | undefined {
+  return Object.prototype.hasOwnProperty.call(HERO_BACKDROP_PRESETS, name)
+    ? HERO_BACKDROP_PRESETS[name as HeroBackdropPresetName]
+    : undefined;
+}

package/src/heroBackdrop/types.ts

@@ -0,0 +1,119 @@
+// ============================================================================
+// Hero backdrop — the shared type contract.
+// ----------------------------------------------------------------------------
+// Every animated hero treatment we have ever built for a Kefi tenant lived only
+// in a throwaway per-session scratchpad, so the same nine variants were rebuilt
+// from scratch more than once. This module is their permanent home: the
+// parameter NAMES here are the ones the design studio
+// (`BaseClient/docs/design/background-lab/background-studio.html`) exports
+// verbatim, so a config pasted out of the studio is a valid `HeroBackdropPreset`
+// with no translation step. Do not rename a key to something tidier — the
+// studio is the source of truth and a rename silently breaks the paste path.
+//
+// Unions rather than `const enum` on purpose: this package is consumed by Astro
+// under `isolatedModules`, where a `const enum` cannot be inlined across the
+// module boundary, and the sibling contracts in @dloizides/site-template-kit
+// (`'light' | 'dark'`, `'primary' | 'ghost'`) already use unions.
+// ============================================================================
+
+/**
+ * Which engine paints the backdrop.
+ *
+ * - `doom`, `noise`, `ember` — <canvas> + requestAnimationFrame. Real
+ *   main-thread cost, opt-in per tenant only.
+ * - `haze` — SVG feTurbulence/feDisplacementMap. No per-frame JS, but the
+ *   filter is painted on the main thread and cannot be composited.
+ * - `tongues`, `cssnoise`, `silhouette`, `wash`, `stack` — pure CSS keyframes
+ *   on transform/opacity. Zero main-thread JavaScript; the compositor runs
+ *   them off-thread. This is the family every existing kefi tenant uses.
+ */
+export type HeroBackdropVariant =
+  | 'doom'
+  | 'noise'
+  | 'ember'
+  | 'haze'
+  | 'tongues'
+  | 'cssnoise'
+  | 'silhouette'
+  | 'wash'
+  | 'stack';
+
+/** True when the variant needs a <canvas> and a rAF loop. */
+export type HeroBackdropEngine = 'canvas' | 'svg' | 'css';
+
+/**
+ * Six palette stops, dark -> bright, as `#rrggbb`.
+ * Canvas variants ramp all six into a 37-step LUT; the CSS variants read
+ * stops 1..4 as `--c1rgb` .. `--c4rgb`.
+ */
+export type HeroBackdropPalette = readonly [string, string, string, string, string, string];
+
+/** Knobs the CSS layers read as custom properties. Studio key names. */
+export interface HeroBackdropCssParams {
+  /** Movement amplitude multiplier. */
+  amp: number;
+  /** Speed multiplier — HIGHER IS SLOWER (it scales the keyframe duration). */
+  spd: number;
+  /** Brightness multiplier. */
+  bri: number;
+  /** Blur multiplier applied to every blurred layer. */
+  blurk: number;
+}
+
+/** Knobs the ember-column particle simulation reads. Studio key names. */
+export interface HeroBackdropEmberParams {
+  /** Half-width of the spawn base, as a fraction of the hero width. */
+  width: number;
+  /** Spawn concentration. >1 tightens the core, <1 flattens it to a sheet. */
+  focus: number;
+  /** Live particle count. The single biggest lever on main-thread cost. */
+  count: number;
+  /** Buoyancy multiplier. */
+  rise: number;
+  /** Horizontal turbulence gain. */
+  drift: number;
+  /** Noise frequency — high is fine and busy. */
+  swirl: number;
+  /** Sprite radius multiplier. */
+  size: number;
+  /** Lifetime multiplier. */
+  life: number;
+  /** Per-sprite peak alpha. */
+  alpha: number;
+  /** Strength of the base bloom the column sits in. */
+  bloomA: number;
+  /** Height of that bloom, as a fraction of the hero height. */
+  bloomH: number;
+}
+
+/**
+ * One named, complete backdrop configuration.
+ *
+ * `ember` is present only for `variant: 'ember'`; the other variants ignore it.
+ * `css` applies to every variant, canvas included, because the CSS scrim and
+ * glow layers sit above the canvas in all of them.
+ */
+export interface HeroBackdropPreset {
+  variant: HeroBackdropVariant;
+  engine: HeroBackdropEngine;
+  /** Human-readable note for the catalog page / code review. */
+  label: string;
+  palette: HeroBackdropPalette;
+  css: HeroBackdropCssParams;
+  ember?: HeroBackdropEmberParams;
+}
+
+/** Keys of the shipped catalog — see `presets.ts`. */
+export type HeroBackdropPresetName =
+  | 'ember-low'
+  | 'ember-med'
+  | 'ember-high'
+  | 'csdf-ember-sparse'
+  | 'doom-med'
+  | 'noise-med'
+  | 'haze-med'
+  | 'tongues-med'
+  | 'cssnoise-med'
+  | 'silhouette-med'
+  | 'wash-med'
+  | 'stack-med';