hyperframes 0.2.2 → 0.2.3-alpha.1

package/dist/skills/hyperframes/references/css-patterns.md

@@ -0,0 +1,371 @@
+# CSS Patterns for Marker Highlighting
+
+Pure CSS + GSAP implementations of all five MarkerHighlight.js drawing modes. Use these for deterministic rendering in HyperFrames compositions — no external library dependency, full GSAP timeline control.
+
+## Table of Contents
+
+- [1. Highlight Mode](#1-highlight-mode) — Yellow marker sweep behind text
+- [2. Circle Mode](#2-circle-mode) — Hand-drawn ellipse around text
+- [3. Burst Mode](#3-burst-mode) — Radiating lines from text
+- [4. Scribble Mode](#4-scribble-mode) — Chaotic scribble over text
+- [5. Sketchout Mode](#5-sketchout-mode) — Rough rectangle outline
+
+## 1. Highlight Mode
+
+Yellow marker sweep behind text. The most common mode.
+
+```html
+<div class="mh-highlight-wrap">
+  <div class="mh-highlight-bar" id="hl-1"></div>
+  <span class="mh-highlight-text">highlighted text</span>
+</div>
+```
+
+```css
+.mh-highlight-wrap {
+  position: relative;
+  display: inline-block;
+}
+.mh-highlight-bar {
+  position: absolute;
+  top: 0;
+  left: -6px;
+  right: -6px;
+  bottom: 0;
+  background: #fdd835;
+  opacity: 0.35;
+  transform: scaleX(0);
+  transform-origin: left center;
+  border-radius: 3px;
+  z-index: 0;
+}
+.mh-highlight-text {
+  position: relative;
+  z-index: 1;
+}
+```
+
+```js
+// Sweep in from left
+tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);
+
+// Optional: skew for hand-drawn feel
+// gsap.set("#hl-1", { skewX: -2 });
+```
+
+### Multi-line Highlight
+
+Stagger bars across multiple lines:
+
+```js
+tl.to(
+  ".mh-highlight-bar",
+  {
+    scaleX: 1,
+    duration: 0.5,
+    ease: "power2.out",
+    stagger: 0.3,
+  },
+  0.6,
+);
+```
+
+## 2. Circle Mode
+
+Hand-drawn circle around text. Use `border-radius: 50%` with a slight rotation for organic feel.
+
+```html
+<div class="mh-circle-wrap">
+  <span class="mh-circle-text" id="circle-word">IMPORTANT</span>
+  <div class="mh-circle-ring" id="circle-1"></div>
+</div>
+```
+
+```css
+.mh-circle-wrap {
+  position: relative;
+  display: inline-block;
+}
+.mh-circle-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-circle-ring {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 130%;
+  height: 160%;
+  transform: translate(-50%, -50%) rotate(-3deg) scale(0);
+  border: 3px solid #e53935;
+  border-radius: 50%;
+  pointer-events: none;
+  z-index: 0;
+}
+```
+
+```js
+// Circle scales in with a wobble
+tl.to(
+  "#circle-1",
+  {
+    scale: 1,
+    rotation: -3,
+    duration: 0.6,
+    ease: "back.out(1.7)",
+    transformOrigin: "center center",
+  },
+  0.7,
+);
+```
+
+### Variations
+
+```css
+/* Tighter circle (for short words) */
+.mh-circle-ring.tight {
+  width: 150%;
+  height: 180%;
+}
+
+/* Squared circle (rounded rectangle) */
+.mh-circle-ring.rounded {
+  border-radius: 30%;
+  width: 120%;
+  height: 140%;
+}
+
+/* Ellipse (wider than tall) */
+.mh-circle-ring.ellipse {
+  width: 150%;
+  height: 130%;
+  border-radius: 50%;
+}
+```
+
+## 3. Burst Mode
+
+Radiating lines from text center. Each line is a positioned div rotated to its angle.
+
+```html
+<div class="mh-burst-wrap">
+  <span class="mh-burst-text">WOW</span>
+  <div class="mh-burst-container" id="burst-1">
+    <div class="mh-burst-line" style="--angle: 0deg; --len: 70px;"></div>
+    <div class="mh-burst-line" style="--angle: 30deg; --len: 55px;"></div>
+    <div class="mh-burst-line" style="--angle: 60deg; --len: 80px;"></div>
+    <div class="mh-burst-line" style="--angle: 90deg; --len: 45px;"></div>
+    <div class="mh-burst-line" style="--angle: 120deg; --len: 65px;"></div>
+    <div class="mh-burst-line" style="--angle: 150deg; --len: 75px;"></div>
+    <div class="mh-burst-line" style="--angle: 180deg; --len: 50px;"></div>
+    <div class="mh-burst-line" style="--angle: 210deg; --len: 60px;"></div>
+    <div class="mh-burst-line" style="--angle: 240deg; --len: 80px;"></div>
+    <div class="mh-burst-line" style="--angle: 270deg; --len: 40px;"></div>
+    <div class="mh-burst-line" style="--angle: 300deg; --len: 70px;"></div>
+    <div class="mh-burst-line" style="--angle: 330deg; --len: 55px;"></div>
+  </div>
+</div>
+```
+
+```css
+.mh-burst-wrap {
+  position: relative;
+  display: inline-block;
+}
+.mh-burst-text {
+  position: relative;
+  z-index: 2;
+}
+.mh-burst-container {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 0;
+  height: 0;
+  z-index: 1;
+}
+.mh-burst-line {
+  position: absolute;
+  width: 3px;
+  height: var(--len);
+  background: #1e88e5;
+  left: -1.5px;
+  top: calc(-1 * var(--len));
+  transform: rotate(var(--angle));
+  transform-origin: bottom center;
+  opacity: 0;
+}
+```
+
+```js
+// All lines burst outward simultaneously with slight stagger
+tl.fromTo(
+  "#burst-1 .mh-burst-line",
+  { scaleY: 0, opacity: 0 },
+  { scaleY: 1, opacity: 1, duration: 0.4, ease: "power2.out", stagger: 0.03 },
+  0.7,
+);
+```
+
+**Vary line lengths** (40-80px range) for an organic, hand-drawn feel. Equal lengths look mechanical.
+
+## 4. Scribble Mode
+
+Wavy SVG underlines and strikethroughs that draw themselves via `stroke-dashoffset`.
+
+```html
+<div class="mh-scribble-wrap">
+  <span class="mh-scribble-text">underlined text</span>
+  <svg class="mh-scribble-svg" viewBox="0 0 500 24" preserveAspectRatio="none">
+    <path
+      id="scribble-1"
+      d="M0,12 Q31,0 62,12 Q93,24 125,12 Q156,0 187,12 Q218,24 250,12 Q281,0 312,12 Q343,24 375,12 Q406,0 437,12 Q468,24 500,12"
+      fill="none"
+      stroke="#FDD835"
+      stroke-width="3"
+      stroke-linecap="round"
+    />
+  </svg>
+</div>
+```
+
+```css
+.mh-scribble-wrap {
+  position: relative;
+  display: inline-block;
+}
+.mh-scribble-text {
+  position: relative;
+  z-index: 1;
+}
+.mh-scribble-svg {
+  position: absolute;
+  left: 0;
+  bottom: -6px;
+  width: 100%;
+  height: 24px;
+  z-index: 0;
+}
+```
+
+```js
+// Measure path length and set initial dash state
+var path = document.querySelector("#scribble-1");
+var len = path.getTotalLength();
+gsap.set(path, { strokeDasharray: len, strokeDashoffset: len });
+
+// Draw the line
+tl.to(
+  "#scribble-1",
+  {
+    strokeDashoffset: 0,
+    duration: 0.8,
+    ease: "power1.inOut",
+  },
+  0.7,
+);
+```
+
+### Strikethrough Variant
+
+Position the SVG at `top: 50%; transform: translateY(-50%)` instead of `bottom: -6px`.
+
+### Wavy Path Generator
+
+Scale the path's viewBox width to match text width. The wave pattern `Q x1,y1 x2,y2` alternates between `y=0` and `y=24` for a natural wobble. Adjust the control points for tighter or looser waves:
+
+- **Tight waves**: smaller x-increments (25px per half-wave)
+- **Loose waves**: larger x-increments (50px per half-wave)
+- **Amplitude**: change the y range (0-24 for standard, 0-16 for subtle)
+
+## 5. Sketchout Mode
+
+Cross-hatch lines over de-emphasized text. Multiple angled lines create a "crossed out" effect.
+
+```html
+<div class="mh-sketchout-wrap">
+  <span class="mh-sketchout-text">old price</span>
+  <div class="mh-sketchout-lines" id="sketchout-1">
+    <div class="mh-sketchout-line mh-sketchout-fwd"></div>
+    <div class="mh-sketchout-line mh-sketchout-bwd"></div>
+  </div>
+</div>
+```
+
+```css
+.mh-sketchout-wrap {
+  position: relative;
+  display: inline-block;
+}
+.mh-sketchout-text {
+  position: relative;
+  z-index: 0;
+}
+.mh-sketchout-lines {
+  position: absolute;
+  top: 0;
+  left: -4px;
+  right: -4px;
+  bottom: 0;
+  overflow: hidden;
+  z-index: 1;
+}
+.mh-sketchout-line {
+  position: absolute;
+  top: 50%;
+  left: 0;
+  width: 100%;
+  height: 2px;
+  background: #e53935;
+  transform-origin: left center;
+  transform: scaleX(0);
+}
+.mh-sketchout-fwd {
+  transform: scaleX(0) rotate(-12deg);
+}
+.mh-sketchout-bwd {
+  transform: scaleX(0) rotate(12deg);
+}
+```
+
+```js
+// Forward slash draws first
+tl.to(
+  "#sketchout-1 .mh-sketchout-fwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.0,
+);
+
+// Backward slash follows
+tl.to(
+  "#sketchout-1 .mh-sketchout-bwd",
+  {
+    scaleX: 1,
+    duration: 0.3,
+    ease: "power2.out",
+  },
+  1.15,
+);
+```
+
+## Combining Modes in Captions
+
+Use mode cycling for visual variety across caption groups:
+
+```js
+var MODES = ["highlight", "circle", "burst", "scribble"];
+
+GROUPS.forEach(function (group, gi) {
+  var mode = MODES[gi % MODES.length];
+  // Apply the mode's CSS pattern to emphasis words in this group
+  group.emphasisWords.forEach(function (word) {
+    applyMode(word.el, mode, tl, word.start);
+  });
+});
+```
+
+Cycle every 2-3 groups for high energy, every 3-4 for medium, every 4-5 for low.

package/dist/skills/hyperframes/references/examples.md

@@ -0,0 +1,146 @@
+# Marker Highlight Examples
+
+## Recipes
+
+### Underline
+
+```html
+<mark
+  data-height="0.15"
+  data-offset="0.8"
+  data-padding="0"
+  data-highlight='{"amplitude":0.2,"wavelength":5,"roughEnds":0}'
+  data-color="rgba(30, 136, 229, 0.6)"
+  >important</mark
+>
+```
+
+### Strikethrough
+
+```html
+<mark
+  data-drawing-mode="highlight"
+  data-height="0.1"
+  data-offset="0"
+  data-highlight='{"amplitude":0.1,"wavelength":3}'
+  data-color="rgba(229, 57, 53, 0.8)"
+  >wrong answer</mark
+>
+```
+
+### Circled Annotation
+
+```html
+<mark
+  data-drawing-mode="circle"
+  data-circle='{"curve":0.8,"wobble":0.4,"loops":2,"thickness":3}'
+  data-animation-speed="1200"
+  data-color="rgba(229, 57, 53, 0.6)"
+  >this one</mark
+>
+```
+
+## Full Example in a Composition
+
+```html
+<div data-composition-id="highlight-demo" data-width="1920" data-height="1080">
+  <div
+    id="content"
+    style="
+    position: absolute; inset: 0;
+    display: flex; align-items: center; justify-content: center;
+    font-family: 'Inter', sans-serif; font-size: 72px; color: #fff;
+    background: #111;
+  "
+  >
+    <p id="hero">
+      The <mark id="m1" data-color="rgba(255, 220, 50, 0.5)">fastest</mark> way to
+      <mark
+        id="m2"
+        data-drawing-mode="circle"
+        data-circle='{"curve":0.8,"wobble":0.3,"loops":2,"thickness":3}'
+        data-color="rgba(229, 57, 53, 0.6)"
+        >ship</mark
+      >
+    </p>
+  </div>
+
+  <style>
+    [data-composition-id="highlight-demo"] mark {
+      background-color: transparent;
+      color: inherit;
+    }
+  </style>
+
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+  <script src="marker-highlight.global.js"></script>
+  <script>
+    window.__timelines = window.__timelines || {};
+    var tl = gsap.timeline({ paused: true });
+
+    // Set colors via data attribute (no visible flash)
+    document.querySelectorAll("mark[data-color]").forEach(function (m) {
+      m.setAttribute("data-original-bgcolor", m.getAttribute("data-color"));
+    });
+
+    // Init once after fonts, then hide all canvases
+    var hl;
+    document.fonts.ready.then(function () {
+      setTimeout(function () {
+        hl = new MarkerHighlighter(document.getElementById("hero"), {
+          animate: false,
+          animationSpeed: 800,
+          padding: 0.3,
+          highlight: { amplitude: 0.3, wavelength: 5 },
+        });
+        setTimeout(function () {
+          document.querySelectorAll(".highlight").forEach(function (d) {
+            d.style.opacity = "0";
+          });
+        }, 100);
+      }, 50);
+    });
+
+    function addHighlight(markId, time) {
+      tl.to(
+        {},
+        {
+          duration: 0.001,
+          onStart: function () {
+            var mark = document.getElementById(markId);
+            var ref = mark.getAttribute("data-mark-ref");
+            if (!ref || !hl) return;
+            mark.parentElement
+              .querySelectorAll('.highlight[data-mark-id="' + ref + '"]')
+              .forEach(function (div) {
+                var c = div.querySelector("canvas");
+                if (c) c.getContext("2d").clearRect(0, 0, c.width, c.height);
+                div.style.opacity = "1";
+              });
+            hl.reanimateMark(mark);
+          },
+          onReverseComplete: function () {
+            var mark = document.getElementById(markId);
+            var ref = mark.getAttribute("data-mark-ref");
+            if (!ref) return;
+            mark.parentElement
+              .querySelectorAll('.highlight[data-mark-id="' + ref + '"]')
+              .forEach(function (div) {
+                div.style.opacity = "0";
+              });
+          },
+        },
+        time,
+      );
+    }
+
+    gsap.set("#hero", { opacity: 0 });
+    tl.to("#hero", { opacity: 1, duration: 0.6 }, 0);
+
+    addHighlight("m1", 0.8);
+    addHighlight("m2", 1.6);
+
+    window.__timelines["highlight-demo"] = tl;
+  </script>
+</div>
+```

package/dist/skills/hyperframes/references/marker-highlight.md

@@ -0,0 +1,158 @@
+# Marker Highlight
+
+Animated canvas-based text highlighting using MarkerHighlight.js. Wraps text in `<mark>` tags and renders effects (marker pen, circle, burst, scribble, sketchout) on a canvas overlay without modifying text DOM.
+
+The library runs its own requestAnimationFrame loop — **not** GSAP-driven. Use `tl.call()` to trigger at specific timeline points.
+
+## Required Script
+
+Download and convert to global script:
+
+```bash
+curl -sL "https://cdn.jsdelivr.net/gh/Robincodes-Sandbox/marker-highlight@main/dist/marker-highlight.min.js" \
+  | sed 's/export{[^}]*};$/window.MarkerHighlighter=W;/' > marker-highlight.global.js
+```
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+<script src="marker-highlight.global.js"></script>
+```
+
+## Color Setup
+
+Set via `data-color`, copy to `data-original-bgcolor` before constructing. Never set `background-color` in CSS.
+
+```css
+mark {
+  color: inherit;
+  background-color: transparent;
+}
+```
+
+```html
+<mark id="m1" data-color="rgba(255, 220, 50, 0.5)">highlighted</mark>
+```
+
+```js
+document
+  .querySelectorAll("mark[data-color]")
+  .forEach((m) => m.setAttribute("data-original-bgcolor", m.getAttribute("data-color")));
+```
+
+## GSAP Integration Pattern
+
+ONE MarkerHighlighter per container with `animate: false`, hide all canvases, then clear+show+reanimate per mark at trigger time.
+
+```js
+var hl = new MarkerHighlighter(document.getElementById("text-container"), {
+  animate: false,
+  animationSpeed: 800,
+  padding: 0.3,
+  highlight: { amplitude: 0.3, wavelength: 5 },
+});
+
+setTimeout(function () {
+  document.querySelectorAll(".highlight").forEach((div) => (div.style.opacity = "0"));
+}, 100);
+
+function addHighlight(highlighter, markId, time) {
+  tl.to(
+    {},
+    {
+      duration: 0.001,
+      onStart: function () {
+        var mark = document.getElementById(markId);
+        var ref = mark.getAttribute("data-mark-ref");
+        var divs = mark.parentElement.querySelectorAll('.highlight[data-mark-id="' + ref + '"]');
+        divs.forEach(function (div) {
+          var canvas = div.querySelector("canvas");
+          if (canvas) canvas.getContext("2d").clearRect(0, 0, canvas.width, canvas.height);
+          div.style.opacity = "1";
+        });
+        highlighter.reanimateMark(mark);
+      },
+      onReverseComplete: function () {
+        var mark = document.getElementById(markId);
+        var ref = mark.getAttribute("data-mark-ref");
+        mark.parentElement
+          .querySelectorAll('.highlight[data-mark-id="' + ref + '"]')
+          .forEach((div) => (div.style.opacity = "0"));
+      },
+    },
+    time,
+  );
+}
+
+addHighlight(hl, "m1", 1.0);
+```
+
+## Drawing Modes
+
+| Mode        | Effect                       | Best for                   |
+| ----------- | ---------------------------- | -------------------------- |
+| `highlight` | Wavy marker stroke (default) | Phrases, key terms         |
+| `circle`    | Hand-drawn ellipse           | Single words, annotations  |
+| `burst`     | Radiating lines/curves/puffs | Excitement, energy         |
+| `scribble`  | Chaotic scribble             | Crossing out, messy energy |
+| `sketchout` | Rough rectangle outline      | Boxed callouts, blueprint  |
+
+```html
+<mark data-drawing-mode="circle" data-color="rgba(229, 57, 53, 0.6)">critical</mark>
+<mark
+  data-drawing-mode="burst"
+  data-burst='{"style":"cloud","count":20}'
+  data-color="rgba(255, 220, 50, 0.5)"
+  >amazing</mark
+>
+```
+
+## Configuration
+
+### Global (constructor)
+
+| Option           | Default       | Description               |
+| ---------------- | ------------- | ------------------------- |
+| `animate`        | `true`        | `false` to defer for GSAP |
+| `animationSpeed` | `5000`        | Duration in ms            |
+| `drawingMode`    | `"highlight"` | Default mode              |
+| `height`         | `1`           | Relative to line height   |
+| `offset`         | `0`           | Vertical shift            |
+| `padding`        | `0`           | Horizontal padding        |
+
+### Per-Mode
+
+**highlight**: `amplitude` (0.25), `wavelength` (1), `roughEnds` (5), `jitter` (0.1)
+**circle**: `curve` (0.5), `wobble` (0.3), `loops` (3), `thickness` (5)
+**burst**: `style` ("lines"/"curve"/"cloud"), `count` (10), `power` (1), `randomness` (0.5)
+
+### Named Styles
+
+```js
+MarkerHighlighter.defineStyle("underline", {
+  animationSpeed: 400,
+  height: 0.15,
+  offset: 0.8,
+  padding: 0,
+  highlight: { amplitude: 0.2, wavelength: 5, roughEnds: 0 },
+});
+```
+
+## Mode-to-Caption Energy Mapping
+
+| Energy      | Mode                  | Use for             |
+| ----------- | --------------------- | ------------------- |
+| High        | `burst` + `highlight` | Launches, hype      |
+| Medium-high | `circle`              | Key stats, terms    |
+| Medium      | `highlight`           | Standard emphasis   |
+| Medium-low  | `scribble`            | Subtle, tutorials   |
+| Low         | `sketchout`           | Contrast, blueprint |
+
+## Notes
+
+- One highlighter per container (clears all `.highlight` divs on init)
+- Canvas pre-draw + clear pattern for clean reveals
+- rAF-based — not seekable mid-stroke
+- Use `onReverseComplete` for rewind support
+
+For CSS+GSAP fallback (no library, fully seekable), see [css-patterns.md](css-patterns.md).
+For full examples, see [examples.md](examples.md).