@cube-drone/marquee-html-renderer 0.9.0 → 0.9.1

package/dist/render.js

@@ -4,6 +4,7 @@
 // vocabulary shrugs (children survive, effect doesn't); comments render
 // nothing; invalid constructs render inert placeholders.
 import { bareWebProfile } from "./profile.js";
+import { effectLook, splitPieces } from "./effects.js";
 export function render(node, profile = bareWebProfile) {
     return renderNode(node, { profile, note: { n: 0, pending: [] } });
 }
@@ -154,8 +155,24 @@ export function usedFontTokens(html) {
     for (const m of html.matchAll(/mq-font-([a-z0-9-]+)/g)) {
         used.add(m[1]);
     }
+    // A scheme that wears a grab-bag face of its own needs that face shipped.
+    for (const m of html.matchAll(/mq-scheme-([a-z0-9-]+)/g)) {
+        for (const [scheme, token] of SCHEME_FONTS) {
+            if (m[1] === scheme || m[1].startsWith(`${scheme}-`)) {
+                used.add(token);
+            }
+        }
+    }
     return [...used].sort();
 }
+/** Schemes (and their `-flavor` variants) that wear a grab-bag face by
+ * default. Kept in lockstep with marquee.css and the Rust renderer. */
+const SCHEME_FONTS = [
+    ["earthbound", "press-start"],
+    ["crosscode", "vt323"],
+    ["ff6", "vt323"],
+    ["chronotrigger", "vt323"],
+];
 /** 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 - teeny, tiny, huge, enormous - are unnecessary
@@ -266,6 +283,11 @@ function styleVarList(attrs, profile) {
     else if (isColorValue(bg)) {
         vars.push(`--mq-bg:${bg}`);
     }
+    // A scheme's signature color - the thing its game let you customize (an
+    // EarthBound frame, an FF6 window). Schemes without one ignore it.
+    if (isColorValue(attrs["accent"])) {
+        vars.push(`--mq-accent:${attrs["accent"]}`);
+    }
     return vars.join(";");
 }
 function styleVars(attrs, profile) {
@@ -293,6 +315,14 @@ function fontClass(attrs) {
 }
 function directive(name, attrs, nodes, ctx) {
     const { profile } = ctx;
+    // The profile hook sees the children rendered; built-ins that lay their
+    // children out themselves (table, stack) render them again, so rewind the
+    // aside numbering first - or a note inside counts twice.
+    const saved = { n: ctx.note.n, pending: [...ctx.note.pending] };
+    const rewind = () => {
+        ctx.note.n = saved.n;
+        ctx.note.pending = [...saved.pending];
+    };
     const inner = children(nodes, ctx);
     const custom = profile.directive(name, attrs, inner);
     if (custom !== null) {
@@ -332,7 +362,15 @@ function directive(name, attrs, nodes, ctx) {
             return `<div class="mq-media"${style}>${inner}</div>`;
         }
         case "table":
+            rewind();
             return renderTable(attrs, nodes, ctx);
+        case "stack":
+            rewind();
+            return renderStack(attrs, nodes, ctx);
+        case "layer":
+            // Outside a stack a layer is just a section-like container: its style
+            // knobs apply, place/backing mean nothing.
+            return `<div class="mq-layer${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, profile)}>${inner}</div>`;
         case "center":
         case "right":
         case "left":
@@ -422,17 +460,81 @@ function renderTable(attrs, nodes, ctx) {
     // Cell sidenotes land just below the table, like a paragraph's would.
     return flushNotes(ctx, `<table class="mq-table">${rows.join("")}</table>`);
 }
+/** A stack paints at most this many layers; the rest flow below the box. */
+const MAX_LAYERS = 8;
+const PLACES = new Set([
+    "fill", "top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right",
+]);
+/** The `aspect` vocabulary as CSS aspect-ratio values. */
+const STACK_ASPECTS = {
+    "16:9": "16/9",
+    "4:3": "4/3",
+    "3:2": "3/2",
+    "1:1": "1/1",
+    card: "5/7",
+};
+/** :::stack (SPEC.md, "Stacks"): every direct child is a layer, source order
+ * is z-order. The stylesheet puts every layer in one grid cell, so the box
+ * is as big as its biggest layer needs and paint order is DOM order: no
+ * z-index, no absolute positioning, nothing clipped. Layers past the cap
+ * render in flow below the box. */
+function renderStack(attrs, nodes, ctx) {
+    const vars = [];
+    const aspect = Object.hasOwn(STACK_ASPECTS, attrs["aspect"] ?? "") ? STACK_ASPECTS[attrs["aspect"]] : undefined;
+    if (aspect !== undefined) {
+        vars.push(`--mq-stack-aspect:${aspect}`);
+    }
+    const w = mediaSize(attrs["width"]);
+    if (w !== null) {
+        vars.push(`--mq-stack-w:${w}`);
+    }
+    const style = vars.length === 0 ? "" : ` style="${vars.join(";")}"`;
+    const layers = nodes.slice(0, MAX_LAYERS).map((n) => renderLayer(n, ctx)).join("");
+    const rest = nodes.slice(MAX_LAYERS);
+    const restHtml = rest.length === 0 ? "" : `<div class="mq-stack-rest">${children(rest, ctx)}</div>`;
+    // The class tells the stylesheet a cover base fills the box rather than
+    // sizing it.
+    const cls = aspect === undefined ? "mq-stack" : "mq-stack mq-stack-aspect";
+    return `<div class="${cls}"${style}>${layers}</div>${restHtml}`;
+}
+/** One layer of a stack: a `:::layer` child carries knobs; any other child
+ * block is a layer with the defaults (`fill`, no backing). */
+function renderLayer(node, ctx) {
+    const isLayer = node.type === "directive" && node.name === "layer";
+    const attrs = isLayer ? node.attrs : {};
+    const content = isLayer ? node.children : [node];
+    const place = PLACES.has(attrs["place"] ?? "") ? attrs["place"] : "fill";
+    const backing = attrs["backing"] === "box" || attrs["backing"] === "outline" ? ` mq-backing-${attrs["backing"]}` : "";
+    // A fill layer that is exactly one embed is that media covering the box -
+    // the one crop the spec permits, of pictures, never of words.
+    const only = content.length === 1 ? content[0] : undefined;
+    const cover = place === "fill" && only?.type === "paragraph" && only.children.length === 1 && only.children[0].type === "embed"
+        ? " mq-layer-cover"
+        : "";
+    const inner = children(content, ctx);
+    return `<div class="mq-layer mq-place-${place}${backing}${cover}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx.profile)}>${inner}</div>`;
+}
 /** Effect/typographic spans. The `<font>` tag is deliberate: presentational
  * attributes are outside CSP's jurisdiction and are implemented by the
  * browser itself, so color survives with no stylesheet and no style
  * attributes - the floor of the degradation ladder. The --mq-color slot is
  * the stylesheet-era ceiling on the same element. */
 function span(name, attrs, nodes, ctx) {
+    const saved = { n: ctx.note.n, pending: [...ctx.note.pending] };
     const inner = children(nodes, ctx);
     const custom = ctx.profile.span(name, attrs, inner);
     if (custom !== null) {
         return custom;
     }
+    const look = effectLook(name, attrs, nodes);
+    if (look !== null) {
+        if (look.units !== null) {
+            // A split renders its children again: rewind the aside numbering.
+            ctx.note.n = saved.n;
+            ctx.note.pending = [...saved.pending];
+        }
+        return renderEffect(name, look, nodes, inner, ctx);
+    }
     switch (name) {
         case "sup":
             return `<sup>${inner}</sup>`;
@@ -492,194 +594,44 @@ function span(name, attrs, nodes, ctx) {
             ctx.note.pending.push(`<span class="mq-note-num">${ctx.note.n}</span>${inner}`);
             return `<sup class="mq-noteref">${ctx.note.n}</sup>`;
         }
-        case "marquee": {
-            const dir = isToken(attrs["direction"]) ? ` data-direction="${attrs["direction"]}"` : "";
-            const speed = attrs["speed"] !== undefined && COUNT.test(attrs["speed"])
-                ? ` style="--mq-speed:${attrs["speed"]}"`
-                : "";
-            return `<span class="mq-marquee"${dir}${speed}><span class="mq-marquee-inner">${inner}</span></span>`;
-        }
-        case "blink": {
-            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": {
-            // 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
 }
-// -- per-unit effects (by=letter / by=word): each unit in its own span with
-// a phase offset in --mq-o; the stylesheet replays the effect's keyframes
-// through a negative animation-delay. Pure markup - the document stays a
-// document. Locale pinned so segmentation (and thus output) is stable.
-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.
- * 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;
-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"
-        ? phaseAttr
-        : effect === "jitter"
-            ? "scatter"
-            : "ramp";
-    const state = { effect, by, phase, i: 0, total: 0 };
-    state.total = countUnits(nodes, by);
-    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>`;
+// -- effects: the look (classes, knobs, per-unit split) comes from
+// effects.ts, shared with every other surface that draws effects.
+function renderEffect(name, look, nodes, inner, ctx) {
+    const data = look.data.map(([k, v]) => ` data-${k}="${escapeAttr(v)}"`).join("");
+    const style = look.vars.length === 0 ? "" : ` style="${look.vars.map(([k, v]) => `${k}:${escapeAttr(v)}`).join(";")}"`;
+    if (name === "marquee") {
+        return `<span class="${look.className}"${data}${style}><span class="mq-marquee-inner">${inner}</span></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
- * isn't whitespace. */
-function isUnit(seg, by) {
-    return by === "word" ? seg.isWordLike === true : !/^\s+$/.test(seg.segment);
-}
-/** Offsets are deterministic (goldens exist; a document renders the same
- * 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;
-    }
-    else {
-        switch (state.effect) {
-            case "rainbow":
-                o = state.i / state.total; // gradient across the whole run
-                break;
-            case "wave":
-                o = (state.i % 8) / 8; // fixed ripple wavelength
-                break;
-            case "bounce":
-                o = (state.i % 6) / 6;
-                break;
-            default:
-                o = (state.i % 8) / 8; // jitter in ramp mode: a rippling shudder
-                break;
-        }
-    }
-    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) {
-        if (node.type === "text") {
-            for (const seg of SEGMENTERS[by].segment(node.value)) {
-                if (isUnit(seg, by)) {
-                    n += 1;
-                }
-            }
-        }
-        else if (node.type === "emphasis" ||
-            node.type === "strong" ||
-            node.type === "strikethrough") {
-            n += countUnits(node.children, by);
-        }
-    }
-    return n;
-}
-function splitRender(nodes, ctx, state) {
+    const body = look.units === null ? inner : splitRender(nodes, ctx, look);
+    return `<span class="${look.className}"${data}${style}>${body}</span>`;
+}
+/** Each unit in its own span with its phase offset; spaces and punctuation
+ * between units ride along as plain text; each word's units sit in a group
+ * that wraps as one. */
+function splitRender(nodes, ctx, look) {
+    const pieces = (list) => list
+        .map((p) => p.kind === "text"
+        ? escapeText(p.text)
+        : p.kind === "unit"
+            ? `<span class="mq-l" style="--mq-o:${p.offset}">${escapeText(p.text)}</span>`
+            : `<span class="mq-w">${pieces(p.pieces)}</span>`)
+        .join("");
     let out = "";
     for (const node of nodes) {
         if (node.type === "text") {
-            for (const seg of SEGMENTERS[state.by].segment(node.value)) {
-                if (!isUnit(seg, state.by)) {
-                    out += escapeText(seg.segment); // spaces/punctuation ride along
-                    continue;
-                }
-                const o = unitOffset(state);
-                state.i += 1;
-                out += `<span class="mq-l" style="--mq-o:${o}">${escapeText(seg.segment)}</span>`;
-            }
+            out += pieces(splitPieces(node, look));
         }
         else if (node.type === "emphasis") {
-            out += `<em>${splitRender(node.children, ctx, state)}</em>`;
+            out += `<em>${splitRender(node.children, ctx, look)}</em>`;
         }
         else if (node.type === "strong") {
-            out += `<strong>${splitRender(node.children, ctx, state)}</strong>`;
+            out += `<strong>${splitRender(node.children, ctx, look)}</strong>`;
         }
         else if (node.type === "strikethrough") {
-            out += `<del>${splitRender(node.children, ctx, state)}</del>`;
+            out += `<del>${splitRender(node.children, ctx, look)}</del>`;
         }
         else {
             out += renderNode(node, ctx); // anything else renders whole, un-split

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-drone/marquee-html-renderer",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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.9.0"
+    "@cube-drone/marquee-parser": "^0.9.1"
   },
   "devDependencies": {
-    "@cube-drone/marquee-css": "^0.9.0",
-    "@cube-drone/marquee-fonts": "^0.9.0",
-    "@cube-drone/marquee-turbolink": "^0.9.0",
+    "@cube-drone/marquee-css": "^0.9.1",
+    "@cube-drone/marquee-fonts": "^0.9.1",
+    "@cube-drone/marquee-turbolink": "^0.9.1",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0"
   }