@dopaminefx/effect-comic 0.1.0

package/src/comic-renderer.ts

@@ -0,0 +1,336 @@
+/**
+ * Comic Impact Canvas2D PANEL drawing + bundled-font loading.
+ *
+ * The crisp, vector-y parts of Comic Impact — the jagged starburst and the
+ * blocky hand-lettered onomatopoeia word with bold ink outlines — are drawn into
+ * an OFFSCREEN Canvas2D each frame (cheap: a few paths) and uploaded as the
+ * "panel" texture; the fragment shader (comic-shader.ts) adds the Ben-Day
+ * halftone, action lines, flash and noir↔pop-art styling. `drawPanel` (the
+ * offscreen draw) and `ensureComicFonts` (the bundled-face loader) live here and
+ * are consumed by the Comic `EffectFactory` (effects/comic.ts), which owns the
+ * GL pass via the shared, program-cached context + the conductor.
+ *
+ * Panel channel encoding consumed by the shader:
+ *   R = word fill · G = ink (all black contours) · B = starburst fill
+ */
+
+import { type ComicRenderParams, isCheckmark } from "./comic-params.js";
+import { mulberry32, type PanelDraw } from "@dopaminefx/core";
+import { impactScale, impactPresence } from "./comic-tempo.js";
+import { EMBEDDED_FACES } from "./comic-fonts.js";
+
+// ---------------------------------------------------------------------------
+// BUNDLED FONT LOADING
+//
+// The effect must NOT silently depend on a host font being installed, so the
+// SIL OFL display faces (Bangers / Anton / Luckiest Guy) ship base64-embedded
+// (comic-fonts.ts) and are registered via the FontFace API. We kick this off
+// once at module import and await it before the first paint; if it fails for
+// any reason the renderer still draws using the robust fallback stack (and the
+// mood/whimsy difference still reads via the procedural treatment).
+// ---------------------------------------------------------------------------
+
+let fontsReady: Promise<void> | null = null;
+
+function base64ToArrayBuffer(b64: string): ArrayBuffer {
+  const bin = atob(b64);
+  const len = bin.length;
+  const bytes = new Uint8Array(len);
+  for (let i = 0; i < len; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes.buffer;
+}
+
+/** Register + load the embedded faces once. Resolves even if loading fails. */
+export function ensureComicFonts(): Promise<void> {
+  if (fontsReady) return fontsReady;
+  if (
+    typeof document === "undefined" ||
+    typeof FontFace === "undefined" ||
+    !(document as Document).fonts
+  ) {
+    fontsReady = Promise.resolve();
+    return fontsReady;
+  }
+  fontsReady = (async () => {
+    await Promise.all(
+      EMBEDDED_FACES.map(async (f) => {
+        try {
+          // Skip if a face by this family is already registered (e.g. host has it).
+          const face = new FontFace(f.family, base64ToArrayBuffer(f.base64));
+          await face.load();
+          (document as Document).fonts.add(face);
+        } catch {
+          /* fall back to the system stack for this face */
+        }
+      }),
+    );
+    try {
+      await (document as Document).fonts.ready;
+    } catch {
+      /* ignore */
+    }
+  })();
+  return fontsReady;
+}
+
+// Begin loading as soon as the module is imported so faces are usually ready by
+// the time the user fires the effect.
+if (typeof document !== "undefined") void ensureComicFonts();
+
+/**
+ * Draw the offscreen panel for this frame: a jagged starburst balloon, the
+ * onomatopoeia word in blocky outlined block caps, all at the current impact
+ * scale + a tiny rotation tilt. Encodes masks into channels:
+ *   R = word fill, G = ink (contours), B = burst fill.
+ *
+ * We draw ink as the GREEN channel and the two fills as RED/BLUE so we can
+ * blend them independently in the shader. To keep channels independent we draw
+ * each layer onto the same 2D context but only write the intended channel.
+ */
+/** Starburst + word size relative to the targeted element box (≈1.5×). See the
+ * Swift `COMIC_TARGET_FILL` — keep the two in sync. */
+const COMIC_TARGET_FILL = 1.7;
+
+/**
+ * The per-frame panel draw in the generic `PanelDraw` shape — the ONE
+ * code-shaped hook the data-driven factory wires (`registerDopePanelEffect`).
+ * Computes the DRAW-SIDE tempo (the per-letter slam SCALE + the panel presence,
+ * which stay code by design — the per-frame values the SHADER reads ride
+ * `tempo.frame`) and hands off to {@link drawPanel}.
+ */
+export const drawComicFrame: PanelDraw = (pctx, w, h, params, info) => {
+  const p = params as unknown as ComicRenderParams;
+  const scale = impactScale(info.elapsedMs, p.overshoot);
+  const presence = impactPresence(info.life);
+  const span = Math.min(info.targetPx.width, info.targetPx.height);
+  drawPanel(pctx, w, h, p, scale, presence, info.dpr, info.centerPx, span);
+};
+
+export function drawPanel(
+  ctx: CanvasRenderingContext2D,
+  w: number,
+  h: number,
+  params: ComicRenderParams,
+  scale: number,
+  presence: number,
+  dpr: number,
+  center: { x: number; y: number },
+  span: number,
+): void {
+  ctx.clearRect(0, 0, w, h);
+  if (presence <= 0.001) return;
+
+  // Position + size the word/starburst to the targeted element (defaults to the
+  // canvas centre + full canvas, reproducing the old screen-centred pose).
+  const cx = center.x;
+  const cy = center.y;
+  // The starburst + word read at ~150% of the targeted element, clamped to the
+  // canvas so a full-page fire (target == canvas) keeps its original size. Kept in
+  // sync with ComicPanel.swift. TUNABLE.
+  const minDim = Math.min(span * COMIC_TARGET_FILL, Math.min(w, h));
+  const rng = mulberry32((params.comicSeed * 1000) >>> 0);
+
+  // Deterministic per-fire tilt so the panel feels hand-placed (a few degrees).
+  const tilt = ((params.comicSeed % 1) - 0.5) * 0.18; // ~±5deg
+
+  // ---------- STARBURST BALLOON (B channel) --------------------------------
+  // A classic many-pointed jagged star: alternating long/short radii with
+  // per-point jitter. Drawn solid into BLUE; its bold outline into GREEN.
+  const points = Math.max(8, Math.round(params.burstPoints));
+  const outerR = minDim * params.scale * 1.3 * scale;
+  const innerR = outerR * 0.64;
+  const burstPts: [number, number][] = [];
+  for (let i = 0; i < points * 2; i++) {
+    const t = i / (points * 2);
+    const a = t * Math.PI * 2 - Math.PI / 2 + tilt;
+    const even = i % 2 === 0;
+    const jitter = 0.82 + rng() * 0.36;
+    const r = (even ? outerR : innerR) * jitter;
+    burstPts.push([cx + Math.cos(a) * r, cy + Math.sin(a) * r]);
+  }
+  const tracePath = () => {
+    ctx.beginPath();
+    burstPts.forEach(([x, y], i) => (i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y)));
+    ctx.closePath();
+  };
+
+  const ink = params.inkWeight * dpr * scale;
+
+  // Burst FILL -> BLUE only.
+  ctx.save();
+  ctx.globalCompositeOperation = "lighter"; // additive into channels
+  tracePath();
+  ctx.fillStyle = `rgba(0,0,${Math.round(255 * presence)},1)`;
+  ctx.fill();
+  ctx.restore();
+
+  // Burst OUTLINE -> GREEN (ink). Thick bold contour.
+  ctx.save();
+  ctx.globalCompositeOperation = "lighter";
+  ctx.lineJoin = "miter";
+  ctx.miterLimit = 2;
+  tracePath();
+  ctx.lineWidth = ink * 1.3;
+  ctx.strokeStyle = `rgba(0,${Math.round(255 * presence)},0,1)`;
+  ctx.stroke();
+  ctx.restore();
+
+  // ---------- LETTERING (success word) or CHECKMARK ------------------------
+  // Mood selects the bundled display face + base character (skew/stretch/tilt);
+  // whimsy shifts the treatment from restrained inked caps (noir) to fat,
+  // inflated, multi-layer-inked, 3D-extruded, per-letter-bounced pop-art. The
+  // owner also wants a big bold ✓ as a selectable option — that's drawn as a
+  // VECTOR path (not a font glyph) so it's reliable everywhere.
+  const fillA = Math.round(255 * presence);
+  const inkStyle = `rgba(0,${fillA},0,1)`;
+  const fillStyle = `rgba(${fillA},0,0,1)`;
+  const round = params.inkRoundness;
+
+  // Per-letter / per-shape deterministic jitter, derived from the per-fire seed.
+  const jrng = mulberry32((params.comicSeed * 2654435761) >>> 0);
+
+  ctx.save();
+  ctx.translate(cx, cy);
+  ctx.rotate(tilt + params.fontTilt);
+  // Italic lean + non-uniform stretch as a shared transform on the whole word.
+  // matrix: [stretchX, 0, skewX, 1] (a=stretch horiz, c=shear).
+  ctx.transform(params.fontStretchX, 0, params.fontSkew, 1, 0, 0);
+  ctx.lineJoin = round > 0.5 ? "round" : "miter";
+  ctx.lineCap = round > 0.5 ? "round" : "butt";
+  ctx.miterLimit = 2;
+  ctx.globalCompositeOperation = "lighter"; // additive into channels
+
+  if (isCheckmark(params.word)) {
+    // ----- VECTOR CHECKMARK -----------------------------------------------
+    // A bold two-segment tick centred on the panel, sized to the burst's inner
+    // span. Drawn as a stroked path; ink contour + 3D extrude + bright fill use
+    // the same treatment knobs as the word path below.
+    const span = innerR * 1.25; // overall check width
+    const strokeW = span * 0.24 * (0.85 + round * 0.25);
+    const extrude = span * params.extrudeDepth;
+    // Check geometry (down-stroke then long up-flick), centred.
+    const pts: [number, number][] = [
+      [-span * 0.42, span * 0.02],
+      [-span * 0.12, span * 0.34],
+      [span * 0.46, -span * 0.36],
+    ];
+    const traceCheck = () => {
+      ctx.beginPath();
+      pts.forEach(([x, y], i) => (i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y)));
+    };
+    // 3D extrude: stacked ink copies stepping down-right (pop-art only).
+    if (extrude > 0.5) {
+      const steps = 8;
+      for (let s = steps; s >= 1; s--) {
+        const dx = (extrude * s) / steps;
+        const dy = (extrude * s) / steps;
+        ctx.save();
+        ctx.translate(dx, dy);
+        traceCheck();
+        ctx.lineWidth = strokeW;
+        ctx.strokeStyle = inkStyle;
+        ctx.stroke();
+        ctx.restore();
+      }
+    }
+    // Bold ink contour (heavier toward pop-art via outlineLayers).
+    traceCheck();
+    ctx.lineWidth = strokeW + ink * (1.2 + params.outlineLayers * 0.5);
+    ctx.strokeStyle = inkStyle;
+    ctx.stroke();
+    // Bright fill body.
+    traceCheck();
+    ctx.lineWidth = strokeW;
+    ctx.strokeStyle = fillStyle;
+    ctx.stroke();
+    ctx.restore();
+    return;
+  }
+
+  // ----- WORD RUN ---------------------------------------------------------
+  const word = params.word;
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+  const fontFor = (px: number) => `${px}px ${params.fontStack}`;
+
+  // Target size, then SHRINK-TO-FIT so longer words (GREAT!/DONE!) never spill
+  // out of the burst. Account for the extra horizontal stretch + tracking.
+  let fontPx = minDim * params.scale * 0.92 * scale;
+  ctx.font = fontFor(fontPx);
+  const chars = [...word];
+  const trackPx = () => fontPx * params.fontTracking;
+  const runWidth = (): number => {
+    let total = 0;
+    for (const ch of chars) total += ctx.measureText(ch).width + trackPx();
+    return Math.max(1, total - trackPx());
+  };
+  const maxW = (innerR * 1.7) / Math.max(0.6, params.fontStretchX);
+  let measured = runWidth();
+  if (measured > maxW) {
+    fontPx *= maxW / measured;
+    ctx.font = fontFor(fontPx);
+    measured = runWidth();
+  }
+
+  const extrude = fontPx * params.extrudeDepth;
+  const inkLine = ink * (1.3 + (params.outlineLayers - 1) * 0.7);
+
+  // Lay out letters individually so we can apply per-letter rotation/baseline
+  // jitter (the pop-art bounce). Start at the left edge of the centred run.
+  let penX = -measured / 2;
+  type Letter = { ch: string; x: number; rot: number; dy: number; wgt: number };
+  const letters: Letter[] = chars.map((ch) => {
+    const wpx = ctx.measureText(ch).width;
+    const x = penX + wpx / 2;
+    penX += wpx + trackPx();
+    const rot = (jrng() - 0.5) * 2 * params.letterRotJitter;
+    const dy = (jrng() - 0.5) * 2 * params.letterBaselineJitter * fontPx;
+    return { ch, x, rot, dy, wgt: jrng() };
+  });
+
+  const drawLetters = (
+    cb: (ctx: CanvasRenderingContext2D, l: Letter) => void,
+  ) => {
+    for (const l of letters) {
+      ctx.save();
+      ctx.translate(l.x, l.dy);
+      ctx.rotate(l.rot);
+      cb(ctx, l);
+      ctx.restore();
+    }
+  };
+
+  // 3D extrude / drop: stacked ink copies stepping down-right behind the body
+  // (pop-art pops, flat at noir).
+  if (extrude > 0.5) {
+    const steps = 8;
+    for (let s = steps; s >= 1; s--) {
+      const dx = (extrude * s) / steps;
+      const dy = (extrude * s) / steps;
+      drawLetters((c, l) => {
+        c.fillStyle = inkStyle;
+        c.fillText(l.ch, dx, dy);
+      });
+    }
+  }
+
+  // Bold INK contour — drawn under the fill so the outline frames the letters.
+  // outlineLayers stacks slightly fattening passes for the inflated balloon look.
+  for (let layer = params.outlineLayers; layer >= 1; layer--) {
+    const lw = inkLine * (1 + (layer - 1) * 0.5);
+    drawLetters((c, l) => {
+      c.lineJoin = round > 0.5 ? "round" : "miter";
+      c.lineWidth = lw;
+      c.strokeStyle = inkStyle;
+      c.strokeText(l.ch, 0, 0);
+    });
+  }
+
+  // Bright FILL body on top.
+  drawLetters((c, l) => {
+    c.fillStyle = fillStyle;
+    c.fillText(l.ch, 0, 0);
+  });
+
+  ctx.restore();
+}

package/src/comic-shader.ts

@@ -0,0 +1,247 @@
+/**
+ * GLSL ES 3.00 source for **Comic Impact** — Dopamine's third success effect: a
+ * Golden/Silver-Age comic-book "BAM! POW!" fight-panel impact.
+ *
+ * This is a HYBRID effect. Crisp blocky vector lettering and bold ink contours
+ * are hard to do well in a pure fragment shader, so the renderer draws the
+ * onomatopoeia word + jagged starburst + ink outlines into an OFFSCREEN Canvas2D
+ * and hands it to this shader as a single "panel" texture. The shader then does
+ * everything that wants to be procedural and screen-space:
+ *   - Ben-Day / halftone DOT shading (rotated screen, dot radius driven by the
+ *     underlying value) — subtle/fine at the noir end, loud/large at pop-art.
+ *   - RADIATING action / speed lines bursting from the impact centre.
+ *   - A FLASH that throws colored light onto the page (the screen-blend cast).
+ *   - The NOIR ↔ POP-ART styling: near-monochrome high-contrast chiaroscuro with
+ *     one spot color → screaming saturated pop, keyed off uStyle/uSaturation.
+ *
+ * Everything is summed as light (canvas is black, composited via
+ * `mix-blend-mode: screen`, so black == no change, bright == cast light).
+ *
+ * Panel texture channel encoding (see comic-renderer.ts):
+ *   R = word FILL mask        (letter interiors)
+ *   G = INK mask              (all black ink: letter + burst + line outlines)
+ *   B = burst FILL mask       (starburst balloon interior, behind the word)
+ *   A = unused
+ *
+ * Pure function of uniforms → frame-perfect & cheap under SwiftShader.
+ */
+
+import {
+  GLSL_CONSTANTS,
+  GLSL_DITHER,
+  GLSL_HALFTONE,
+  GLSL_HASH,
+  GLSL_ROT2,
+  GLSL_TONEMAP_ACES,
+} from "@dopaminefx/core";
+
+export const COMIC_VERTEX_SRC = /* glsl */ `#version 300 es
+out vec2 vUv;
+void main() {
+  vec2 pos = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
+  vUv = pos;
+  gl_Position = vec4(pos * 2.0 - 1.0, 0.0, 1.0);
+}`;
+
+export const COMIC_FRAGMENT_SRC = /* glsl */ `#version 300 es
+precision highp float;
+in vec2 vUv;
+out vec4 fragColor;
+
+uniform sampler2D uPanel;     // R=wordFill G=ink B=burstFill
+uniform vec2  uResolution;    // device pixels
+uniform vec2  uTarget;        // targeted element size (device px); scales the action lines
+uniform vec2  uOrigin;        // impact centre (the anchor), device px
+uniform float uLife;          // whole-effect progress 0..1
+uniform float uTimeS;         // elapsed seconds
+uniform float uPresence;      // panel opacity / presence 0..1
+uniform float uFlash;         // 0..1 impact flash amount (fast spike, decays)
+uniform float uExposure;      // cast-light gain
+uniform float uHalftone;      // 0..1 Ben-Day dot strength
+uniform float uDotSize;       // Ben-Day cell size in device px
+uniform float uSaturation;    // 0..1 panel color saturation (noir->pop)
+uniform float uActionLines;   // count of radiating speed lines
+uniform float uInkBoost;      // ink darkness/spread multiplier (pop fattens ink)
+uniform float uSeed;          // per-fire hash
+uniform float uStyle;         // 0..1 noir -> pop-art (whimsy)
+uniform float uShadow;        // 0 = light pass (screen), 1 = shadow pass (multiply)
+uniform vec2  uShadowOffset;  // device-px offset of the cast silhouette (away from light)
+uniform float uShadowSoft;    // penumbra softness in device px (blur tap radius)
+uniform float uShadowStrength;// 0..1 max darkening of the multiply layer
+uniform vec3  uC0;            // word fill color
+uniform vec3  uC1;            // secondary / burst color
+uniform vec3  uC2;            // dot / accent color
+
+${GLSL_CONSTANTS}
+${GLSL_HASH}
+${GLSL_ROT2}
+${GLSL_HALFTONE}
+${GLSL_TONEMAP_ACES}
+${GLSL_DITHER}
+
+void main(){
+  vec2 frag = vUv * uResolution;
+  vec2 res = uResolution;
+  float minDim = min(res.x, res.y);
+  // The word/burst (panel) are sized to the targeted element box; scale the
+  // radiating action lines to the SAME basis so they streak off the word, not the
+  // whole canvas. Clamped to the canvas so a full-page fire (uTarget == res) is
+  // unchanged. Must match the comic renderer's COMIC_TARGET_FILL (1.7).
+  float comicSpan = min(min(uTarget.x, uTarget.y) * 1.7, minDim);
+
+  // ---- SHADOW PASS (multiply layer) ---------------------------------------
+  // Cheap occlusion: the panel's solid forms (word fill + burst fill) sampled
+  // at an offset toward the implied key light, with a small ring blur for a
+  // penumbra. White = no shadow (multiply identity); darker = cast shadow. The
+  // panel already encodes presence, so the shadow fades with the effect.
+  if (uShadow > 0.5) {
+    vec2 px = 1.0 / res;
+    vec2 souv = vUv - uShadowOffset * px;
+    float occ = 0.0;
+    for (int i = 0; i < 8; i++) {
+      float a = float(i) / 8.0 * TAU;
+      vec2 o = vec2(cos(a), sin(a)) * uShadowSoft * px;
+      vec2 tuv = souv + o;
+      // Gate samples that fall OUTSIDE the panel: the texture is CLAMP_TO_EDGE,
+      // so without this an offset sample past an edge smears that edge row into
+      // a phantom band (the streaks at the top of the frame). Outside == no
+      // occluder == no shadow.
+      vec2 inb = step(vec2(0.0), tuv) * step(tuv, vec2(1.0));
+      float mask = inb.x * inb.y;
+      vec4 s = texture(uPanel, tuv);
+      occ += clamp(s.r + s.b, 0.0, 1.0) * mask;
+    }
+    occ /= 8.0;
+    float dark = clamp(occ * uShadowStrength, 0.0, 1.0);
+    fragColor = vec4(vec3(1.0 - dark), 1.0);
+    return;
+  }
+
+  vec2 fromC = frag - uOrigin;
+  float rad = length(fromC);
+  float ang = atan(fromC.y, fromC.x);
+
+  vec4 panel = texture(uPanel, vUv);
+  float wordFill = panel.r;
+  float inkMask  = clamp(panel.g * uInkBoost, 0.0, 1.0);
+  float burstFill = panel.b;
+
+  vec3 col = vec3(0.0);
+
+  // ---- RADIATING ACTION / SPEED LINES -------------------------------------
+  // Thin wedges bursting outward from the impact centre. Procedural so they're
+  // crisp and cheap. They live in a ring OUTSIDE the burst balloon (so they
+  // read as motion lines streaking off the hit, not hatching on the word).
+  float lineN = max(uActionLines, 1.0);
+  float a01 = (ang / TAU) + 0.5;                 // 0..1 around the circle
+  float idx = floor(a01 * lineN);
+  // per-line random angular jitter + length so they aren't a clean fan.
+  float jr = hash11(idx + uSeed * 3.1);
+  float jr2 = hash11(idx * 1.7 + uSeed * 7.3);
+  float cellPhase = fract(a01 * lineN);
+  float wedge = abs(cellPhase - 0.5);
+  // Thin tapered streaks: a sharp spine that fattens slightly outward (classic
+  // motion-line wedge), kept narrow so they read as speed lines, not pie slices.
+  float thick = mix(0.05, 0.14, jr);
+  float lineBody = 1.0 - smoothstep(thick * 0.35, thick, wedge);
+  // radial extent: lines start OUTSIDE the burst and streak outward to the edge.
+  float innerR = comicSpan * (0.30 + 0.05 * jr2);
+  float outerR = comicSpan * (0.46 + 0.30 * jr);
+  float radialMask = smoothstep(innerR, innerR + comicSpan * 0.015, rad)
+                   * (1.0 - smoothstep(outerR - comicSpan * 0.10, outerR, rad));
+  // fade the lines in fast on impact, hold, then they thin out late.
+  float linePresence = smoothstep(0.0, 0.06, uLife) * (1.0 - smoothstep(0.6, 1.0, uLife));
+  // taper opacity along the line so the inner end is boldest (ink-streak feel).
+  float taper = 1.0 - smoothstep(innerR, outerR, rad);
+  float lines = lineBody * radialMask * linePresence * taper;
+  // animate-on-twos flicker toward the pop end (snappy comic motion).
+  float beat = floor(uTimeS * 12.0);
+  float flick = mix(1.0, step(0.25, hash11(idx + beat + uSeed)), uStyle * 0.5);
+  lines *= flick;
+
+  // Action lines cast a thin streak of light off the hit. White/cool ink at the
+  // noir end (a hard glint), the accent hue at the pop end. Kept dim so they
+  // read as speed lines around the panel rather than flooding the frame.
+  vec3 lineCol = mix(vec3(0.7, 0.74, 0.82), uC2, uStyle);
+  col += lineCol * lines * 0.32 * uExposure;
+
+  // ---- STARBURST BALLOON (behind the word) --------------------------------
+  // Filled with the secondary hue; gets the strongest Ben-Day shading so it
+  // reads as a flat printed color field. In noir it's a pale near-white field
+  // with a fine subtle screen; in pop-art it's a saturated yellow/red blast.
+  vec3 burstBase = mix(vec3(0.9), uC1, uSaturation);
+  // tone for the dots: more dots where the field is "darker" value. We want a
+  // lively mid coverage so the classic dot field shows.
+  float burstTone = mix(0.35, 0.7, uHalftone);
+  float dots = benday(frag, uDotSize, burstTone, radians(15.0) + uSeed);
+  // Ben-Day strength: subtle at noir, dominant at pop. The dots ADD the accent
+  // color on the printed field.
+  vec3 burstCol = burstBase + (uC2 - burstBase) * dots * uHalftone * 0.55;
+  col += burstCol * burstFill * uPresence * uExposure;
+
+  // A second, finer rotated screen on the word fill for that printed sheen at
+  // the pop end (kept subtle so letters stay legible). The word is the HERO:
+  // a bright, saturated fill that screams off the page (pop) or a luminous
+  // near-white with a spot tint (noir). Brighter than the burst so it reads
+  // as the foreground shout.
+  float wordDots = benday(frag, uDotSize * 0.7, 0.5, radians(75.0) + uSeed);
+  vec3 wordBright = clamp(uC0 * 1.35 + 0.25, 0.0, 1.4);
+  vec3 wordBase = mix(vec3(0.96, 0.97, 1.0), wordBright, clamp(uSaturation + 0.2, 0.0, 1.0));
+  vec3 wordCol = wordBase + (uC2 - wordBase) * wordDots * uHalftone * 0.25 * uStyle;
+  // Word fill is largely PROTECTED from ink suppression (its own outline should
+  // frame it, not eat it), so render it after a softened ink mask below.
+  col += wordCol * wordFill * uPresence * uExposure * 1.7;
+
+  // ---- INK ----------------------------------------------------------------
+  // Bold black contours. Ink is the ABSENCE of light on a screen-blend canvas,
+  // so we can't literally darken the page from here — instead we let ink CARVE
+  // the lit shapes (it suppresses the fills it overlaps) and, at the noir end,
+  // we add a faint cool rim so the chiaroscuro edge still reads as light catches
+  // the ink ridge. The actual black is achieved by NOT lighting those pixels.
+  float ink = inkMask * uPresence;
+  // Suppress fills under ink (so outlines punch through as unlit black). But
+  // where the ink overlaps the WORD fill we soften the carve a lot, so the
+  // outline frames the letters instead of eating their bright bodies.
+  // Gentle carve: the outline should FRAME the burst, not gut it. A near-total
+  // carve (old 0.96) left the burst outline reading as a transparent gap that
+  // masked the balloon — worse at high whimsy, where inkBoost fattens the ink.
+  // Keep the word's soft carve (0.26 at wordFill=1) but darken the burst outline
+  // only partway so the balloon shows through.
+  float carve = ink * (0.45 - 0.19 * wordFill);
+  col *= (1.0 - carve);
+  // Subtle chiaroscuro rim-light on ink edges toward the noir end (a glint).
+  float rim = ink * (1.0 - uStyle) * 0.18;
+  col += mix(uC2, vec3(0.8, 0.85, 1.0), 0.5) * rim * uExposure;
+
+  // ---- IMPACT FLASH -------------------------------------------------------
+  // A hot radial flash at the moment of impact that throws colored light onto
+  // the page (the cast-light proof). Fast spike, quick decay (driven by uFlash).
+  float flashFall = exp(-rad / (minDim * 0.42));
+  vec3 flashCol = mix(mix(uC0, uC1, 0.5), vec3(1.0), 0.45 + 0.3 * uStyle);
+  col += flashCol * flashFall * uFlash * uExposure * 1.4;
+  // a tight white-hot core right at the centre on the very first frames.
+  float core = exp(-rad / (minDim * 0.10));
+  col += vec3(1.0) * core * uFlash * uFlash * 1.6;
+
+  // ---- TONE + FINISH ------------------------------------------------------
+  // ACES filmic tonemap (shared look/glsl) for a cleaner highlight rolloff than
+  // the old x/(1+x) compress — the impact flash highlights roll off gracefully
+  // while the saturated printed mids stay rich. A mild pre-exposure keeps the
+  // pop-art color from dimming.
+  col = tonemapACES(col * 0.85);
+
+  // Pop-art posterize: snap the lit panel to a few flat ink levels toward the
+  // pop end (flat printed color), leaving the dark page untouched so we don't
+  // shatter it into camouflage. Noir stays smooth chiaroscuro.
+  if (uStyle > 0.001) {
+    float lit = smoothstep(0.02, 0.2, max(max(col.r, col.g), col.b));
+    vec3 q = floor(col * 4.0 + 0.5) / 4.0;
+    col = mix(col, mix(col, q, lit), uStyle * 0.7);
+  }
+
+  // Ordered dither (shared look/glsl) to kill banding the screen-blend reveals
+  // (faded toward the pop end where the flat printed look is intended).
+  col = ditherAdd(col, frag, uTimeS, 1.0 - uStyle * 0.7);
+
+  fragColor = vec4(max(col, 0.0), 1.0);
+}`;

package/src/comic-tempo.ts

@@ -0,0 +1,46 @@
+/**
+ * Comic Impact bespoke timing — the slam/recoil + proud-hold-then-fade.
+ *
+ * The word arrives oversized and slams down past its rest size, recoils (a quick
+ * spring), holds, then eases out at the tail. Deliberately very short IMPACT so
+ * the word reads as a punch landing, not a tween. Built on `easeOutCubic`.
+ */
+
+import { easeOutCubic, clamp01 } from "@dopaminefx/core";
+
+/** Window (ms) over which the comic onomatopoeia word SLAMS in. */
+export const IMPACT_MS = 200;
+
+/** Hold (ms) the word sits proud at full size before it begins to settle out. */
+export const IMPACT_HOLD_MS = 650;
+
+/**
+ * Comic impact SCALE over elapsed ms. Returns a multiplier on rest size: large
+ * at t≈0, slamming to ≈1 by IMPACT_MS (with a small spring), then resting.
+ * `overshoot` scales the slam magnitude (driven by intensity).
+ */
+export function impactScale(elapsedMs: number, overshoot = 1): number {
+  const t = elapsedMs;
+  if (t <= 0) return 1 + 0.85 * overshoot;
+  if (t < IMPACT_MS) {
+    const x = t / IMPACT_MS;
+    const eased = easeOutCubic(x);
+    const big = 1 + 0.85 * overshoot;
+    const dip = -0.12 * overshoot * Math.sin(x * Math.PI) * (1 - x);
+    return big + (1 - big) * eased + dip;
+  }
+  return 1;
+}
+
+/**
+ * Comic impact OPACITY/presence over normalized life (0..1). A near-instant
+ * appearance, a long proud hold, then a quick fade at the very end so the panel
+ * clears. The fade occupies the last ~18%.
+ */
+export function impactPresence(life: number): number {
+  const t = clamp01(life);
+  if (t < 0.04) return easeOutCubic(t / 0.04); // snap in
+  if (t < 0.82) return 1;
+  const fade = clamp01(1 - (t - 0.82) / 0.18);
+  return Math.pow(fade, 1.4); // quick clean fade
+}