@cube-drone/marquee-html-renderer 0.1.1 → 0.3.0

package/dist/render.js

@@ -158,7 +158,7 @@ export function usedFontTokens(html) {
 }
 /** One rung of the font-element seven-step dial: presentational floor
  * (works with no stylesheet, under any CSP), stylesheet class as ceiling.
- * The named rungs - miniscule, tiny, huge, enormous - are unnecessary
+ * The named rungs - teeny, tiny, huge, enormous - are unnecessary
  * given the dial, and yet. */
 function sizeRung(value, inner) {
     return `<font class="mq-size-${value}" size="${value}">${inner}</font>`;
@@ -315,6 +315,14 @@ function directive(name, attrs, nodes, ctx) {
         }
         case "table":
             return renderTable(attrs, nodes, ctx);
+        case "center":
+        case "right":
+        case "left":
+            // The <center> tag, back from the dead in directive clothing - plus
+            // its siblings: right for symmetry, left as the un-aligner (useful
+            // only inside the other two, which is exactly when you want it).
+            // Physical directions, deliberately: predictable beats logical.
+            return `<div class="mq-${name}">${inner}</div>`;
     }
     // Unknown vocabulary: a container renders its children with an affordance
     // that something wrapped them; a leaf renders the inert placeholder.
@@ -404,7 +412,7 @@ function span(name, attrs, nodes, ctx) {
             }
             return inner; // not on the list: the words survive in their own clothes
         }
-        case "miniscule":
+        case "teeny":
             return sizeRung("1", inner);
         case "tiny":
             return sizeRung("2", inner);
@@ -419,7 +427,12 @@ function span(name, attrs, nodes, ctx) {
             }
             return inner; // invalid value: the effect degrades, the words survive
         }
-        case "sidenote": {
+        case "sidenote":
+        case "aside":
+        case "footnote": {
+            // Permanent synonyms (SPEC.md): nobody keeps these three words
+            // distinct in their head, and an aside that silently isn't an aside
+            // is worse than two extra names - the list-marker rule, one layer up.
             // A numbered mark in the flow; the note itself flushes just below the
             // triggering paragraph (see flushNotes). Numbering runs sequentially
             // through the whole document.
@@ -438,18 +451,41 @@ function span(name, attrs, nodes, ctx) {
             const rate = attrs["rate"] !== undefined && COUNT.test(attrs["rate"])
                 ? ` style="--mq-rate:${attrs["rate"]}"`
                 : "";
+            if (attrs["by"] === "letter" || attrs["by"] === "word") {
+                // Split blink: ramp is theater-marquee chase lights, scatter is
+                // twinkle. The rate var rides the container; units inherit it.
+                return bySegments(name, attrs["by"], attrs["phase"], nodes, ctx, rate);
+            }
             return `<span class="mq-blink"${rate}>${inner}</span>`;
         }
         case "rainbow":
         case "bounce":
         case "jitter":
         case "wave":
+        case "rubber":
             if (attrs["by"] === "letter" || attrs["by"] === "word") {
                 return bySegments(name, attrs["by"], attrs["phase"], nodes, ctx);
             }
             return `<span class="mq-${name}">${inner}</span>`;
-        case "typewriter":
-            return `<span class="mq-${name}">${inner}</span>`;
+        case "typewriter": {
+            // Inherently per-unit: the reveal IS a by=letter effect (by=word for
+            // word-at-a-time). speed= is units per second; the container carries
+            // the per-unit delay step, each unit its ordinal in --mq-o.
+            const by = attrs["by"] === "word" ? "word" : "letter";
+            const step = revealStep(attrs["speed"], 14);
+            return bySegments(name, by, attrs["phase"], nodes, ctx, ` style="--mq-tw-step:${step}s"`);
+        }
+        case "fadein": {
+            // The ghostly reveal. Bare [fadein] fades the whole run in once;
+            // by=letter / by=word drift units in on staggered starts (same
+            // one-shot family as typewriter: sequential ordinals, high cap);
+            // phase=scatter is apparition weather.
+            if (attrs["by"] === "letter" || attrs["by"] === "word") {
+                const step = revealStep(attrs["speed"], 16);
+                return bySegments(name, attrs["by"], attrs["phase"], nodes, ctx, ` style="--mq-fi-step:${step}s"`);
+            }
+            return `<span class="mq-fadein">${inner}</span>`;
+        }
     }
     return inner; // unknown span: pure shrug, children as plain content
 }
@@ -461,9 +497,13 @@ const SEGMENTERS = {
     letter: new Intl.Segmenter("en", { granularity: "grapheme" }),
     word: new Intl.Segmenter("en", { granularity: "word" }),
 };
-/** DOM-weight discipline: past this many units, the run animates whole. */
+/** DOM-weight discipline: past this many units, the run animates whole.
+ * Loopers pay a live animation per element forever, so they cap low;
+ * typewriter's units are 1ms one-shots (finished animations cost nothing)
+ * and its natural material is long text, so it caps high. */
 const MAX_SPLIT_UNITS = 400;
-function bySegments(effect, by, phaseAttr, nodes, ctx) {
+const MAX_REVEAL_UNITS = 2000;
+function bySegments(effect, by, phaseAttr, nodes, ctx, containerStyle = "") {
     // Each effect has a natural phase order (jitter scatters, the rest sweep);
     // the knob overrides it either way. Invalid values degrade to the default.
     const phase = phaseAttr === "scatter" || phaseAttr === "ramp"
@@ -473,10 +513,11 @@ function bySegments(effect, by, phaseAttr, nodes, ctx) {
             : "ramp";
     const state = { effect, by, phase, i: 0, total: 0 };
     state.total = countUnits(nodes, by);
-    if (state.total === 0 || state.total > MAX_SPLIT_UNITS) {
+    const cap = isReveal(effect) ? MAX_REVEAL_UNITS : MAX_SPLIT_UNITS;
+    if (state.total === 0 || state.total > cap) {
         return `<span class="mq-${effect}">${children(nodes, ctx)}</span>`;
     }
-    return `<span class="mq-${effect} mq-split">${splitRender(nodes, ctx, state)}</span>`;
+    return `<span class="mq-${effect} mq-split"${containerStyle}>${splitRender(nodes, ctx, state)}</span>`;
 }
 /** A segment gets wrapped if it's animatable: for words, word-like segments
  * (spaces and bare punctuation ride along); for letters, anything that
@@ -488,6 +529,19 @@ function isUnit(seg, by) {
  * twice) in both phase orders: ramp sweeps, scatter scrambles by a fixed
  * integer hash - randomness-shaped, never random. */
 function unitOffset(state) {
+    // Reveal offsets (typewriter, fadein) are sequential INTEGERS (the
+    // ordinal; delay = ordinal x step), unlike the cyclic 0..1 fractions the
+    // looping effects replay. phase=scatter reveals in a
+    // scrambled-but-deterministic order: a stride at the run's golden-ratio
+    // point, nudged coprime with the total, walks a well-spread permutation
+    // at EVERY length. (A fixed prime stride is a trap: 7919 mod 40 = 39 =
+    // -1, so forty-unit runs typed in backwards.)
+    if (isReveal(state.effect)) {
+        const o = state.phase === "scatter"
+            ? (state.i * scatterStride(state.total)) % state.total
+            : state.i;
+        return String(o);
+    }
     let o;
     if (state.phase === "scatter") {
         o = ((state.i * 7919) % 101) / 101;
@@ -510,6 +564,30 @@ function unitOffset(state) {
     }
     return String(Math.round(o * 1000) / 1000);
 }
+/** speed= (units per second, a COUNT) into a per-unit delay step in
+ * seconds; invalid or absent falls to the effect's default rate. */
+function revealStep(speedAttr, dflt) {
+    const speed = speedAttr !== undefined && COUNT.test(speedAttr) && Number(speedAttr) > 0
+        ? Number(speedAttr)
+        : dflt;
+    return Math.round(1000 / speed) / 1000;
+}
+/** The one-shot reveals: sequential ordinals, the high unit cap. */
+function isReveal(effect) {
+    return effect === "typewriter" || effect === "fadein";
+}
+function gcd(a, b) {
+    return b === 0 ? a : gcd(b, a % b);
+}
+/** The smallest stride >= ~61.8% of total that's coprime with it (falls
+ * back to 1 for degenerate totals - a 1- or 2-unit "scramble" is fate). */
+function scatterStride(total) {
+    let stride = Math.max(1, Math.round(total * 0.618));
+    while (stride < total && gcd(stride, total) !== 1) {
+        stride += 1;
+    }
+    return gcd(stride, total) === 1 ? stride : 1;
+}
 function countUnits(nodes, by) {
     let n = 0;
     for (const node of nodes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-drone/marquee-html-renderer",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Reference static HTML renderer for the Marquee markup language",
   "license": "MPL-2.0",
   "repository": {
@@ -35,12 +35,12 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@cube-drone/marquee-parser": "^0.1.1"
+    "@cube-drone/marquee-parser": "^0.3.0"
   },
   "devDependencies": {
-    "@cube-drone/marquee-css": "^0.1.1",
-    "@cube-drone/marquee-fonts": "^0.1.1",
-    "@cube-drone/marquee-turbolink": "^0.1.1",
+    "@cube-drone/marquee-css": "^0.3.0",
+    "@cube-drone/marquee-fonts": "^0.3.0",
+    "@cube-drone/marquee-turbolink": "^0.3.0",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0"
   }

package/src/render.ts

@@ -180,7 +180,7 @@ export function usedFontTokens(html: string): string[] {
 
 /** One rung of the font-element seven-step dial: presentational floor
  * (works with no stylesheet, under any CSP), stylesheet class as ceiling.
- * The named rungs - miniscule, tiny, huge, enormous - are unnecessary
+ * The named rungs - teeny, tiny, huge, enormous - are unnecessary
  * given the dial, and yet. */
 function sizeRung(value: string, inner: string): string {
   return `<font class="mq-size-${value}" size="${value}">${inner}</font>`;
@@ -349,6 +349,14 @@ function directive(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string
     }
     case "table":
       return renderTable(attrs, nodes, ctx);
+    case "center":
+    case "right":
+    case "left":
+      // The <center> tag, back from the dead in directive clothing - plus
+      // its siblings: right for symmetry, left as the un-aligner (useful
+      // only inside the other two, which is exactly when you want it).
+      // Physical directions, deliberately: predictable beats logical.
+      return `<div class="mq-${name}">${inner}</div>`;
   }
   // Unknown vocabulary: a container renders its children with an affordance
   // that something wrapped them; a leaf renders the inert placeholder.
@@ -440,7 +448,7 @@ function span(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string {
       }
       return inner; // not on the list: the words survive in their own clothes
     }
-    case "miniscule":
+    case "teeny":
       return sizeRung("1", inner);
     case "tiny":
       return sizeRung("2", inner);
@@ -455,7 +463,12 @@ function span(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string {
       }
       return inner; // invalid value: the effect degrades, the words survive
     }
-    case "sidenote": {
+    case "sidenote":
+    case "aside":
+    case "footnote": {
+      // Permanent synonyms (SPEC.md): nobody keeps these three words
+      // distinct in their head, and an aside that silently isn't an aside
+      // is worse than two extra names - the list-marker rule, one layer up.
       // A numbered mark in the flow; the note itself flushes just below the
       // triggering paragraph (see flushNotes). Numbering runs sequentially
       // through the whole document.
@@ -474,18 +487,41 @@ function span(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string {
       const rate = attrs["rate"] !== undefined && COUNT.test(attrs["rate"])
         ? ` style="--mq-rate:${attrs["rate"]}"`
         : "";
+      if (attrs["by"] === "letter" || attrs["by"] === "word") {
+        // Split blink: ramp is theater-marquee chase lights, scatter is
+        // twinkle. The rate var rides the container; units inherit it.
+        return bySegments(name, attrs["by"], attrs["phase"], nodes, ctx, rate);
+      }
       return `<span class="mq-blink"${rate}>${inner}</span>`;
     }
     case "rainbow":
     case "bounce":
     case "jitter":
     case "wave":
+    case "rubber":
       if (attrs["by"] === "letter" || attrs["by"] === "word") {
         return bySegments(name, attrs["by"], attrs["phase"], nodes, ctx);
       }
       return `<span class="mq-${name}">${inner}</span>`;
-    case "typewriter":
-      return `<span class="mq-${name}">${inner}</span>`;
+    case "typewriter": {
+      // Inherently per-unit: the reveal IS a by=letter effect (by=word for
+      // word-at-a-time). speed= is units per second; the container carries
+      // the per-unit delay step, each unit its ordinal in --mq-o.
+      const by = attrs["by"] === "word" ? "word" : "letter";
+      const step = revealStep(attrs["speed"], 14);
+      return bySegments(name, by, attrs["phase"], nodes, ctx, ` style="--mq-tw-step:${step}s"`);
+    }
+    case "fadein": {
+      // The ghostly reveal. Bare [fadein] fades the whole run in once;
+      // by=letter / by=word drift units in on staggered starts (same
+      // one-shot family as typewriter: sequential ordinals, high cap);
+      // phase=scatter is apparition weather.
+      if (attrs["by"] === "letter" || attrs["by"] === "word") {
+        const step = revealStep(attrs["speed"], 16);
+        return bySegments(name, attrs["by"], attrs["phase"], nodes, ctx, ` style="--mq-fi-step:${step}s"`);
+      }
+      return `<span class="mq-fadein">${inner}</span>`;
+    }
   }
   return inner; // unknown span: pure shrug, children as plain content
 }
@@ -502,8 +538,12 @@ const SEGMENTERS = {
 
 type SplitBy = keyof typeof SEGMENTERS;
 
-/** DOM-weight discipline: past this many units, the run animates whole. */
+/** DOM-weight discipline: past this many units, the run animates whole.
+ * Loopers pay a live animation per element forever, so they cap low;
+ * typewriter's units are 1ms one-shots (finished animations cost nothing)
+ * and its natural material is long text, so it caps high. */
 const MAX_SPLIT_UNITS = 400;
+const MAX_REVEAL_UNITS = 2000;
 
 type Phase = "ramp" | "scatter";
 
@@ -521,6 +561,7 @@ function bySegments(
   phaseAttr: string | undefined,
   nodes: Node[],
   ctx: Ctx,
+  containerStyle = "",
 ): string {
   // Each effect has a natural phase order (jitter scatters, the rest sweep);
   // the knob overrides it either way. Invalid values degrade to the default.
@@ -532,10 +573,11 @@ function bySegments(
         : "ramp";
   const state: SplitState = { effect, by, phase, i: 0, total: 0 };
   state.total = countUnits(nodes, by);
-  if (state.total === 0 || state.total > MAX_SPLIT_UNITS) {
+  const cap = isReveal(effect) ? MAX_REVEAL_UNITS : MAX_SPLIT_UNITS;
+  if (state.total === 0 || state.total > cap) {
     return `<span class="mq-${effect}">${children(nodes, ctx)}</span>`;
   }
-  return `<span class="mq-${effect} mq-split">${splitRender(nodes, ctx, state)}</span>`;
+  return `<span class="mq-${effect} mq-split"${containerStyle}>${splitRender(nodes, ctx, state)}</span>`;
 }
 
 /** A segment gets wrapped if it's animatable: for words, word-like segments
@@ -549,6 +591,20 @@ function isUnit(seg: Intl.SegmentData, by: SplitBy): boolean {
  * twice) in both phase orders: ramp sweeps, scatter scrambles by a fixed
  * integer hash - randomness-shaped, never random. */
 function unitOffset(state: SplitState): string {
+  // Reveal offsets (typewriter, fadein) are sequential INTEGERS (the
+  // ordinal; delay = ordinal x step), unlike the cyclic 0..1 fractions the
+  // looping effects replay. phase=scatter reveals in a
+  // scrambled-but-deterministic order: a stride at the run's golden-ratio
+  // point, nudged coprime with the total, walks a well-spread permutation
+  // at EVERY length. (A fixed prime stride is a trap: 7919 mod 40 = 39 =
+  // -1, so forty-unit runs typed in backwards.)
+  if (isReveal(state.effect)) {
+    const o =
+      state.phase === "scatter"
+        ? (state.i * scatterStride(state.total)) % state.total
+        : state.i;
+    return String(o);
+  }
   let o: number;
   if (state.phase === "scatter") {
     o = ((state.i * 7919) % 101) / 101;
@@ -571,6 +627,35 @@ function unitOffset(state: SplitState): string {
   return String(Math.round(o * 1000) / 1000);
 }
 
+/** speed= (units per second, a COUNT) into a per-unit delay step in
+ * seconds; invalid or absent falls to the effect's default rate. */
+function revealStep(speedAttr: string | undefined, dflt: number): number {
+  const speed =
+    speedAttr !== undefined && COUNT.test(speedAttr) && Number(speedAttr) > 0
+      ? Number(speedAttr)
+      : dflt;
+  return Math.round(1000 / speed) / 1000;
+}
+
+/** The one-shot reveals: sequential ordinals, the high unit cap. */
+function isReveal(effect: string): boolean {
+  return effect === "typewriter" || effect === "fadein";
+}
+
+function gcd(a: number, b: number): number {
+  return b === 0 ? a : gcd(b, a % b);
+}
+
+/** The smallest stride >= ~61.8% of total that's coprime with it (falls
+ * back to 1 for degenerate totals - a 1- or 2-unit "scramble" is fate). */
+function scatterStride(total: number): number {
+  let stride = Math.max(1, Math.round(total * 0.618));
+  while (stride < total && gcd(stride, total) !== 1) {
+    stride += 1;
+  }
+  return gcd(stride, total) === 1 ? stride : 1;
+}
+
 function countUnits(nodes: Node[], by: SplitBy): number {
   let n = 0;
   for (const node of nodes) {